\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}
\keyword{print}{str}
\keyword{documentation}{str}
\keyword{utilities}{str}
\begin{Description}\relax
Compactly display the internal \bold{str}ucture of an \R{} object, a
\dQuote{diagnostic} function and an alternative to \code{\LinkA{summary}{summary}}
(and to some extent, \code{\LinkA{dput}{dput}}).  Ideally, only one line for
each \dQuote{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.
\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 = 4, digits.d = 3,
    nchar.max = 128, give.attr = TRUE, give.length = TRUE,
    wid = getOption("width"), nest.lev = 0,
    indent.str = paste(rep.int(" ", max(0, nest.lev + 1)), collapse = ".."),
    comp.str="$ ", no.list = FALSE, envir = baseenv(),
    ...)
\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 \dQuote{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.
\item[\code{digits.d}] number of digits for numerical components (as for
\code{\LinkA{print}{print}}).
\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{wid}] the page width to be used.  The default is the currently
active \code{\LinkA{options}{options}("width")}.
\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 \dQuote{list of ..} is nor the
class is printed.
\item[\code{envir}] the environment to be used for \emph{promise} (see
\code{\LinkA{delayedAssign}{delayedAssign}}) objects only.
\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)
## 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 = 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)


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}