R: Compactly Display the Structure of an Arbitrary R Object

str {utils} | 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, ...)

    ## S3 method for class 'data.frame':
    str(object, ...)

    ## Default S3 method:
    str(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, ...,  envir = as.environment(pos), mode = "any",
            max.level = 1, give.attr = FALSE)
    lsf.str(pos = 1, ..., envir = as.environment(pos))

### 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.
`envir` | environment to use, see `ls`.
`pattern` | a 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

    require(stats)
    ## 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()

    ch <- letters[1:12]; is.na(ch) <- 3:5
    str(ch) # character NA's

    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]