R: Compactly Display the Structure of an Arbitrary R Object

str {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")

[Package Contents]