str                   package:base                   R Documentation

_C_o_m_p_a_c_t_l_y _D_i_s_p_l_a_y _t_h_e _S_t_r_u_c_t_u_r_e _o_f _a_n _A_r_b_i_t_r_a_r_y _R _O_b_j_e_c_t

_D_e_s_c_r_i_p_t_i_o_n:

     This is a ``diagnostic'' function, and an alternative to `summary'
     (and to some extent, `dput').  Ideally, only one line for each
     ``basic'' structure is displayed.  It is especially well suited to
     compactly display the (abbreviated) contents of (possibly nested)
     lists.  The idea is to give reasonable output for any R object. 
     It calls `args' for (non-primitive) function objects.

     `ls.str' and `lsf.str' are useful ``versions'' of `ls', calling
     `str' on each object.  They are not foolproof and should rather
     not be used for programming, but are provided for their
     usefulness.

_U_s_a_g_e:

     str(object, ...)
     str.data.frame(object, ...)
     str.default(object, max.level = 0, vec.len = 4, digits.d = 3,
         nchar.max = 128, give.attr = TRUE, give.length = TRUE,
         wid = getOption("width"), nest.lev = 0,
         indent.str = paste(rep(" ", max(0, nest.lev + 1)), collapse = ".."))

     ls.str(name, pattern, mode = "any", max.level = 1, give.attr = FALSE)
     lsf.str(...)

_A_r_g_u_m_e_n_t_s:

  object: any R object about which you want to have some information.

max.level: maximal level of nesting which is applied for displaying
          nested structures, e.g., a list containing sub lists. Default
          0: Display all nesting levels.

 vec.len: numeric (>= 0) indicating how many ``first few'' elements are
          displayed of each vector.  The number is multiplied by
          different factors (from .5 to 3) depending on the kind of
          vector.  Default 4.

digits.d: number of digits for numerical components (as for `print').

nchar.max: maximal number of characters to show for `character'
          strings.  Longer strings are truncated, see `longch' example
          below.

give.attr: logical; if `TRUE' (default), show attributes as sub
          structures.

give.length: logical; if `TRUE' (default), indicate length (as
          `[1:...]').

     wid: the page width to be used.  The default is the currently
          active `options("width")'.

nest.lev: current nesting level in the recursive calls to `str'.

indent.str: the indentation string to use.

_V_a_l_u_e:

     Nothing, for efficiency reasons. The obvious side effect is output
     to the terminal.

_A_u_t_h_o_r(_s):

     Martin Maechler maechler@stat.math.ethz.ch since 1990.

_S_e_e _A_l_s_o:

     `summary', `args'.

_E_x_a_m_p_l_e_s:

     ## The following examples show some of `str' capabilities
     str(1:12)
     str(ls)
     str(args)#- more useful than  args(args) !
     data(freeny); str(freeny)
     str(str)
     str(.Machine, digits = 20)
     str( lsfit(1:9,1:9))
     str( lsfit(1:9,1:9),  max =1)
     op <- options(); str(op)#- save first; otherwise internal options() is used.
     need.dev <- !exists(".Device") || is.null(.Device)
     if(need.dev) postscript()
     str(par()); if(need.dev) graphics.off()

     nchar(longch <- paste(rep(letters,100), collapse=""))
     str(longch)
     str(longch, nchar.max = 52)

     lsf.str()#- how do the functions look like which I am using?
     ls.str(mode = "list")#- what are the structured objects I have defined?

