\HeaderA{format}{Encode in a Common Format}{format}
\methaliasA{format.AsIs}{format}{format.AsIs}
\methaliasA{format.data.frame}{format}{format.data.frame}
\methaliasA{format.default}{format}{format.default}
\methaliasA{format.factor}{format}{format.factor}
\keyword{character}{format}
\keyword{print}{format}
\begin{Description}\relax
Format an \R{} object for pretty printing.
\end{Description}
\begin{Usage}
\begin{verbatim}
format(x, ...)

## Default S3 method:
format(x, trim = FALSE, digits = NULL,
       nsmall = 0, justify = c("left", "right", "centre", "none"),
       width = NULL, na.encode = TRUE, scientific = NA,
       big.mark = "",   big.interval = 3,
     small.mark = "", small.interval = 5,
   decimal.mark = ".", ...)

## S3 method for class 'data.frame':
format(x, ..., justify = "none")

## S3 method for class 'factor':
format(x, ...)

## S3 method for class 'AsIs':
format(x, width = 12, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] any \R{} object (conceptually); typically numeric.
\item[\code{trim}] logical; if \code{FALSE}, logical, numeric and complex
values are right-justified to a common width: if \code{TRUE} the
leading blanks for justification are suppressed.
\item[\code{digits}] how many significant digits are to be used for
numeric and complex \code{x}.  The default, \code{NULL}, uses
\code{\LinkA{getOption}{getOption}(digits)}.  This is a suggestion: enough decimal
places will be used so that the smallest (in magnitude) number has
this many significant digits, and also to satisfy \code{nsmall}.
(For the intepretation for complex numbers see \code{\LinkA{signif}{signif}}.)
\item[\code{nsmall}] number of digits which will always appear to the right of
the decimal point in formatting real/complex numbers in
non-scientific formats.  Allowed values are \code{0 <= nsmall <= 20}.
\item[\code{justify}] should a \emph{character} vector be left-justified (the
default), right-justified, centred or left alone.
\item[\code{width}] \code{default} method: the \emph{minimum} field width or
\code{NULL} or \code{0} for no restriction.

\code{AsIs} method: the \emph{maximum} field width for non-character
objects.  \code{NULL} corresponds to the default 12.

\item[\code{na.encode}] logical: should \code{NA} strings be encoded?
\item[\code{scientific}] Either a logical specifiying whether 
elements of a real or complex vector should be encoded in scientific
format, or an integer penalty (see \code{\LinkA{options}{options}("scipen")}.
Missing values correspond to the current default penalty.
\item[\code{...}] further arguments passed to or from other methods.
\item[\code{big.mark, big.interval,
small.mark, small.interval,
decimal.mark}] used for prettying longer decimal sequences, passed to
\code{\LinkA{prettyNum}{prettyNum}}: that help page explains the details.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{format} is a generic function.  Apart from the methods described
here there are methods for dates (see \code{\LinkA{format.Date}{format.Date}}),
date-times (see \code{\LinkA{format.POSIXct}{format.POSIXct}})) and for other classes such
as \code{format.octmode} and \code{format.dist}.

\code{format.data.frame} formats the data frame column by column,
applying the appropriate method of \code{format} for each column.
Methods for columns are often similar to \code{as.character} but offer
more control.  Matrix and data-frame columns will be converted to
separate columns in the result, and character columns (normally all)
will be given class \code{"\LinkA{AsIs}{AsIs}"}.

\code{format.factor} converts the factor to a character vector and
then calls the default method (and so \code{justify} applies).

\code{format.AsIs} deals with columns of complicated objects that
have been extracted from a data frame.  Character objects are passed
to the default method (and so \code{width} does not apply).
Otherwise it calls \code{\LinkA{toString}{toString}} to convert the object
to character (if a vector or list, element by element) and then
right-justifies the result.

Justification for character vectors (and objects converted to
character vectors by their methods) is done on display width (see
\code{\LinkA{nchar}{nchar}}), taking double-width characters and the rendering
of special characters (as escape sequences, including escaping
backslash: see \code{\LinkA{print.default}{print.default}}) into account.  Character
strings are padded with blanks to the display width of the widest.
(If \code{na.encode = FALSE} missing character strings are not
included in the width computations and are not encoded.)

Numeric vectors are encoded with the minimum number of decimal places
needed to display all the elements to at least the \code{digit}
significant digits.  However, if all the elements then have trailing
zeroes, the number of decimal places is reduced until at least one
element has a non-zero final digit.

Raw vectors are converted to their 2-digit hexadecimal representation
by \code{\LinkA{as.character}{as.character}}.
\end{Details}
\begin{Value}
An object of similar structure to \code{x} containing character
representations of the elements of the first argument \code{x}
in a common format.

For numeric or complex \code{x}, dims and dimnames are preserved on
matrices/arrays and names on vectors: as from \R{} 2.2.0 no other
attributes are copied.

If \code{x} is a list, the result is a character vector obtained by
applying \code{format.default(x, ...)} to each element of the list
(after \code{\LinkA{unlist}{unlist}}ing elements which are themselves lists),
and then collapsing the result for each element with
\code{paste(collapse = ", ")}.  The defaults in this case are
\code{trim = TRUE, justify = "none"} since one does not usually want
alignment in the collapsed strings.
\end{Value}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{format.info}{format.info}} indicates how an atomic vector would be
formatted.

\code{\LinkA{formatC}{formatC}}, \code{\LinkA{paste}{paste}}, \code{\LinkA{as.character}{as.character}},
\code{\LinkA{sprintf}{sprintf}}, \code{\LinkA{print}{print}}, \code{\LinkA{toString}{toString}},
\code{\LinkA{encodeString}{encodeString}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
format(1:10)
format(1:10, trim = TRUE)

zz <- data.frame("(row names)"= c("aaaaa", "b"), check.names=FALSE)
format(zz)
format(zz, justify = "left")

## use of nsmall
format(13.7)
format(13.7, nsmall = 3)
format(c(6.0, 13.1), digits = 2)
format(c(6.0, 13.1), digits = 2, nsmall = 1)

## use of scientific
format(2^31-1)
format(2^31-1, sci = TRUE)

## a list
z <- list(a=letters[1:3], b=(-pi+0i)^((-2:2)/2), c=c(1,10,100,1000),
          d=c("a", "longer", "character", "string"))
format(z, digits = 2)
format(z, digits = 2, justify = "left", trim = FALSE)
\end{ExampleCode}
\end{Examples}

