str                  package:utils                  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:

     Compactly display the internal *str*ucture 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.

     'strOptions()' is a convenience function for setting 'options(str
     = .)', see the examples.

_U_s_a_g_e:

     str(object, ...)

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

     ## Default S3 method:
     str(object, max.level = NA,
         vec.len  = strO$vec.len, digits.d = strO$digits.d,
         nchar.max = 128, give.attr = TRUE,
         give.head = TRUE, give.length = give.head,
         width = getOption("width"), nest.lev = 0,
         indent.str = paste(rep.int(" ", max(0, nest.lev + 1)),
                            collapse = ".."),
         comp.str="$ ", no.list = FALSE, envir = baseenv(),
         strict.width = strO$strict.width,
         formatNum = strO$formatNum, ...)

     strOptions(strict.width = "no", digits.d = 3, vec.len = 4,
                formatNum = function(x, ...)
                            format(x, trim=TRUE, drop0trailing=TRUE, ...))

_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
          NA: 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.  Defaults to the 'vec.len' component of option
          '"str"' (see 'options') which defaults to 4.

digits.d: number of digits for numerical components (as for 'print'). 
          Defaults to the 'digits.d' component of option '"str"' which
          defaults to 3.

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:...]').

give.head: logical; if 'TRUE' (default), give (possibly abbreviated)
          mode/class and length (as '<type>[1:...]').

   width: the page width to be used.  The default is the currently
          active 'options("width")'; note that this has only a weak
          effect, unless 'strict.width' is not '"no"'.

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

indent.str: the indentation string to use.

comp.str: string to be used for separating list components.

 no.list: logical; if true, no 'list of ...' nor the class are printed.

   envir: the environment to be used for _promise_ (see
          'delayedAssign') objects only.

strict.width: string indicating if the 'width' argument's specification
          should be followed strictly, one of the values 'c("no",
          "cut", "wrap")'. Defaults to the 'strict.width' component of
          option '"str"' (see 'options') which defaults to '"no"' for
          back compatibility reasons; '"wrap"' uses 'strwrap(*,
          width=width)' whereas '"cut"' cuts directly to 'width'.  Note
          that a small 'vec.length' may be better than setting
          'strict.width = "wrap"'.

formatNum: a function such as 'format' for formatting numeric vectors. 
          It defaults to the 'formatNum' component of option '"str"',
          see "Usage" of 'strOptions()' above, which is almost back
          compatible to R version <= 2.7.x, however, using 'formatC'
          may be slightly better.

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

_V_a_l_u_e:

     'str' does not return anything, 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:

     'ls.str' for _listing_ objects with their structure; 'summary',
     'args'.

_E_x_a_m_p_l_e_s:

     require(stats); require(grDevices); require(graphics)
     ## The following examples show some of 'str' capabilities
     str(1:12)
     str(ls)
     str(args) #- more useful than  args(args) !
     str(freeny)
     str(str)
     str(.Machine, digits.d = 20)
     str( lsfit(1:9,1:9))
     str( lsfit(1:9,1:9), max.level = 1)
     str( lsfit(1:9,1:9), width = 60, strict.width = "cut")
     str( lsfit(1:9,1:9), width = 60, strict.width = "wrap")
     op <- options(); str(op) # save first;
                              # otherwise internal options() is used.
     need.dev <-
       !exists(".Device") || is.null(.Device) || .Device == "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)

     str(longch, strict.width = "wrap")

     ## Settings for narrow transcript :
     op <- options(width = 60,
                   str = strOptions(strict.width = "wrap"))
     str(lsfit(1:9,1:9))
     str(options())
     ## reset to previous:
     options(op)


     str(quote( { A+B; list(C,D) } ))


     ## S4 classes :
     require(stats4)
     x <- 0:10; y <- c(26, 17, 13, 12, 20, 5, 9, 8, 5, 4, 8)
     ll <- function(ymax=15, xh=6)
           -sum(dpois(y, lambda=ymax/(1+x/xh), log=TRUE))
     fit <- mle(ll)
     str(fit)