\Header{str}{Compactly Display the Structure of an Arbitrary R Object}
\alias{ls.str}{str}
\alias{lsf.str}{str}
\methalias{str.data.frame}{str}
\methalias{str.default}{str}
\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{\Link{summary}}
(and to some extent, \code{\Link{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{\Link{args}} for (non-primitive) function objects.

\code{\Link{ls.str}} and \code{\Link{lsf.str}} are useful \dQuote{versions}
of \code{\Link{ls}}, calling \code{str} on each object.  They are not
foolproof and should rather not be used for programming, but are
provided for their usefulness.
\end{Description}
\begin{Usage}
\begin{verbatim}
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))
\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 0: 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{\Link{print}}).
\item[\code{nchar.max}] maximal number of characters to show for
\code{\Link{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{\Link{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{...}] potential further arguments (required for Method/Generic reasons).
\item[\code{pos}] integer indicating \code{\Link{search}} path position.
\item[\code{envir}] environment to use, see \code{\Link{ls}}.
\item[\code{pattern}] a \link{regular expression} passed to \code{\Link{ls}}.
Only names matching \code{pattern} are considered.
\item[\code{mode}] character specifying the \code{\Link{mode}} of objects to
consider.  Passed to \code{\Link{exists}} and \code{\Link{get}}.
\end{ldescription}
\end{Arguments}
\begin{Value}
\code{str} does not return anything, for efficiency reasons.
The obvious side effect is output to the terminal.

\code{ls.str} and \code{lsf.str} invisibly return a character vector
of the matching names, similarly to \code{\Link{ls}}.
\end{Value}
\begin{Author}\relax
Martin Maechler \email{maechler@stat.math.ethz.ch} since 1990.
\end{Author}
\begin{SeeAlso}\relax
\code{\Link{summary}}, \code{\Link{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) !
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")

\end{ExampleCode}
\end{Examples}

