str                   package:base                   R Documentation

Compactly Display the Structure of an Arbitrary R Object

Description:

     Compactly display the internal structure of an R object, 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.

Usage:

     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(pos = 1, pattern, ..., mode = "any",
             max.level = 1, give.attr = FALSE)
     lsf.str(pos = 1, pattern, ...)

Arguments:

  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.

     ...: potential further arguments (required for Method/Generic
          reasons).

     pos: integer indicating `search' path position.

 pattern: regular expression passed to `ls'.  Only names matching
          `pattern' are considered.

    mode: character specifying the `mode' of objects to consider. 
          Passed to `exists' and `get'.

Value:

     `str' does not return anything, for efficiency reasons. The
     obvious side effect is output to the terminal.

     `ls.str' and `lsf.str' invisibly return a character vector of the
     matching names, similarly to `ls'.

Author(s):

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

See Also:

     `summary', `args'.

Examples:

     ## 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?
     ## which base functions have "file" in their name ?
     lsf.str(pos = length(search()), pattern = "file")

