\Header{format}{Encode in a Common Format}
\methalias{format.AsIs}{format}
\methalias{format.data.frame}{format}
\methalias{format.default}{format}
\methalias{format.factor}{format}
\methalias{format.pval}{format}
\alias{prettyNum}{format}
\keyword{character}{format}
\keyword{print}{format}
\begin{Description}\relax
Format an \R{} object for pretty printing: \code{format.pval} is
intended for formatting p-values.\end{Description}
\begin{Usage}
\begin{verbatim}
format(x, ...)

## S3 method for class 'AsIs':
format(x, width = 12, ...)

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

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

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

format.pval(pv, digits = max(1, getOption("digits") - 2),
            eps = .Machine$double.eps, na.form = "NA")

prettyNum(x, big.mark = "",   big.interval = 3,
           small.mark = "", small.interval = 5,
         decimal.mark = ".", ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] any \R{} object (conceptually); typically numeric.
\item[\code{trim}] logical; if \code{TRUE}, leading blanks are trimmed off the
strings.
\item[\code{digits}] how many significant digits are to be used for
\code{\Link{numeric} x}.  The default, \code{NULL}, uses
\code{\Link{options}()\$digits}.  This is a suggestion: enough decimal
places will be used so that the smallest (in magnitude) number has
this many significant digits.
\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 \code{0 <= nsmall <= 20}.
\item[\code{justify}] should character vector be left-justified,
right-justified or left alone.  When justifying, the field width is
that of the longest string.
\item[\code{big.mark}] character; if not empty used as mark between every
\code{big.interval} decimals \emph{before} (hence \code{big}) the
decimal point.
\item[\code{big.interval}] see \code{big.mark} above; defaults to 3.
\item[\code{small.mark}] character; if not empty used as mark between every
\code{small.interval} decimals \emph{after} (hence \code{small}) the
decimal point.
\item[\code{small.interval}] see \code{small.mark} above; defaults to 5.
\item[\code{decimal.mark}] the character used to indicate the numeric
decimal point.
\item[\code{pv}] a numeric vector.
\item[\code{eps}] a numerical tolerance: see Details.
\item[\code{na.form}] character representation of \code{NA}s.
\item[\code{width}] the returned vector has elements of at most \code{width}.
\item[\code{...}] further arguments passed to or from other methods.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
These functions convert their first argument to a vector (or array) of
character strings which have a common format (as is done by
\code{\Link{print}}), fulfilling \code{length(format*(x, *)) ==
    length(x)}.  The trimming with \code{trim = TRUE} is useful
when the strings are to be used for plot \code{\Link{axis}} annotation.

\code{format.AsIs} deals with columns of complicated objects that
have been extracted from a data frame.

\code{format.pval} is mainly an auxiliary function for
\code{\Link{print.summary.lm}} etc., and does separate formatting for
fixed, floating point and very small values; those less than
\code{eps} are formatted as \code{"< [eps]"} (where \dQuote{[eps]}
stands for \code{format(eps, digits)}.

The function \code{\Link{formatC}} provides a rather more flexible
formatting facility for numbers, but does \emph{not} provide a common
format for several numbers, nor it is platform-independent.

\code{format.data.frame} formats the data frame column by column,
applying the appropriate method of \code{format} for each column.

\code{prettyNum} is the utility function for prettifying \code{x}. If
\code{x} is not a character, \code{format(x[i], ...)} is applied to
each element, and then it is left unchanged if all the other arguments
are at their defaults.  Note that \code{prettyNum(x)} may behave
unexpectedly if \code{x} is a \code{character} not resulting from
something like \code{format(<number>)}.\end{Details}
\begin{Note}\relax
Currently \code{format} drops trailing zeroes, so \code{format(6.001,
    digits=2)} gives \code{"6"} and \code{format(c(6.0, 13.1),
    digits=2)} gives \code{c(" 6", "13")}.

Character(s) \code{"} in input strings \code{x} are escaped to \code{\bsl{}"}.\end{Note}
\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{\Link{format.info}} indicates how something would be formatted;
\code{\Link{formatC}}, \code{\Link{paste}}, \code{\Link{as.character}},
\code{\Link{sprintf}}.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
format(1:10)

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)

r <- c("76491283764.97430", "29.12345678901", "-7.1234", "-100.1","1123")
## American:
prettyNum(r, big.mark = ",")
## Some Europeans:
prettyNum(r, big.mark = "'", decimal.mark = ",")

(dd <- sapply(1:10, function(i)paste((9:0)[1:i],collapse="")))
prettyNum(dd, big.mark="'")

pN <- pnorm(1:7, lower=FALSE)
cbind(format (pN, small.mark = " ", digits = 15))
cbind(formatC(pN, small.mark = " ", digits = 17, format = "f"))
\end{ExampleCode}
\end{Examples}

