\HeaderA{str}{Compactly Display the Structure of an Arbitrary R Object}{str}
\methaliasA{str.data.frame}{str}{str.data.frame}
\methaliasA{str.default}{str}{str.default}
\aliasA{strOptions}{str}{strOptions}
\keyword{print}{str}
\keyword{documentation}{str}
\keyword{utilities}{str}
\begin{Description}\relax
Compactly display the internal \bold{str}ucture of an \R{} object, a
diagnostic function and an alternative to \code{\LinkA{summary}{summary}}
(and to some extent, \code{\LinkA{dput}{dput}}).  Ideally, only one line for
each \sQuote{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 \bold{any} \R{}
object.  It calls \code{\LinkA{args}{args}} for (non-primitive) function objects.

\code{strOptions()} is a convenience function for setting
\code{\LinkA{options}{options}(str = .)}, see the examples.
\end{Description}
\begin{Usage}
\begin{verbatim}
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, ...))
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{object}] any \R{} object about which you want to have some
information.
\item[\code{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.
\item[\code{vec.len}] numeric (>= 0) indicating how many \sQuote{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 \code{vec.len} component of option \code{"str"} (see
\code{\LinkA{options}{options}}) which defaults to 4.
\item[\code{digits.d}] number of digits for numerical components (as for
\code{\LinkA{print}{print}}).  Defaults to the \code{digits.d} component of
option \code{"str"} which defaults to 3.
\item[\code{nchar.max}] maximal number of characters to show for
\code{\LinkA{character}{character}} strings.  Longer strings are truncated, see
\code{longch} example below.
\item[\code{give.attr}] logical; if \code{TRUE} (default), show attributes
as sub structures.
\item[\code{give.length}] logical; if \code{TRUE} (default), indicate
length (as \code{[1:...]}).
\item[\code{give.head}] logical; if \code{TRUE} (default), give (possibly
abbreviated) mode/class and length (as \code{<type>[1:...]}).
\item[\code{width}] the page width to be used.  The default is the currently
active \code{\LinkA{options}{options}("width")}; note that this has only a
weak effect, unless \code{strict.width} is not \code{"no"}.
\item[\code{nest.lev}] current nesting level in the recursive calls to
\code{str}.
\item[\code{indent.str}] the indentation string to use.
\item[\code{comp.str}] string to be used for separating list components.
\item[\code{no.list}] logical; if true, no \sQuote{list of \dots} nor the
class are printed.
\item[\code{envir}] the environment to be used for \emph{promise} (see
\code{\LinkA{delayedAssign}{delayedAssign}}) objects only.
\item[\code{strict.width}] string indicating if the \code{width} argument's
specification should be followed strictly, one of the values
\code{c("no", "cut", "wrap")}.
Defaults to the \code{strict.width} component of option \code{"str"}
(see \code{\LinkA{options}{options}}) which defaults to \code{"no"} for back
compatibility reasons; \code{"wrap"} uses
\code{\LinkA{strwrap}{strwrap}(*, width=width)} whereas \code{"cut"} cuts
directly to \code{width}.  Note that a small \code{vec.length}
may be better than setting \code{strict.width = "wrap"}.
\item[\code{formatNum}] a function such as \code{\LinkA{format}{format}} for
formatting numeric vectors.  It defaults to the \code{formatNum}
component of option \code{"str"}, see \dQuote{Usage} of
\code{strOptions()} above, which is almost back compatible to \R{}
version \eqn{\le}{<=} 2.7.x, however, using \code{\LinkA{formatC}{formatC}}
may be slightly better.
\item[\code{...}] potential further arguments (required for Method/Generic
reasons).
\end{ldescription}
\end{Arguments}
\begin{Value}
\code{str} does not return anything, for efficiency reasons.
The obvious side effect is output to the terminal.
\end{Value}
\begin{Author}\relax
Martin Maechler \email{maechler@stat.math.ethz.ch} since 1990.
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{ls.str}{ls.str}} for \emph{listing} objects with their structure;
\code{\LinkA{summary}{summary}}, \code{\LinkA{args}{args}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
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)

\end{ExampleCode}
\end{Examples}

