1% File src/library/base/man/format.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2019 R Core Team
4% Copyright 2003-2016 The R Foundation
5% Distributed under GPL 2 or later
6
7\name{format}
8\alias{format}
9\alias{format.AsIs}
10\alias{format.data.frame}
11\alias{format.default}
12\alias{format.factor}
13\description{
14  Format an \R object for pretty printing.
15}
16\title{Encode in a Common Format}
17\usage{
18format(x, \dots)
19
20\method{format}{default}(x, trim = FALSE, digits = NULL, nsmall = 0L,
21       justify = c("left", "right", "centre", "none"),
22       width = NULL, na.encode = TRUE, scientific = NA,
23       big.mark   = "",   big.interval = 3L,
24       small.mark = "", small.interval = 5L,
25       decimal.mark = getOption("OutDec"),
26       zero.print = NULL, drop0trailing = FALSE, \dots)
27
28\method{format}{data.frame}(x, \dots, justify = "none")
29
30\method{format}{factor}(x, \dots)
31
32\method{format}{AsIs}(x, width = 12, \dots)
33}
34\arguments{
35  \item{x}{any \R object (conceptually); typically numeric.}
36
37  \item{trim}{logical; if \code{FALSE}, logical, numeric and complex
38    values are right-justified to a common width: if \code{TRUE} the
39    leading blanks for justification are suppressed.}
40
41  \item{digits}{how many significant digits are to be used for
42    numeric and complex \code{x}.  The default, \code{NULL}, uses
43    \code{\link{getOption}("digits")}.  This is a suggestion: enough decimal
44    places will be used so that the smallest (in magnitude) number has
45    this many significant digits, and also to satisfy \code{nsmall}.
46    (For the interpretation for complex numbers see \code{\link{signif}}.)}
47
48  \item{nsmall}{the minimum number of digits to the right of the decimal
49    point in formatting real/complex numbers in non-scientific formats.
50    Allowed values are \code{0 <= nsmall <= 20}.}
51
52  \item{justify}{should a \emph{character} vector be left-justified (the
53    default), right-justified, centred or left alone.  Can be abbreviated.}
54
55  \item{width}{\code{default} method: the \emph{minimum} field width or
56    \code{NULL} or \code{0} for no restriction.
57
58    \code{AsIs} method: the \emph{maximum} field width for non-character
59    objects.  \code{NULL} corresponds to the default \code{12}.
60  }
61
62  \item{na.encode}{logical: should \code{NA} strings be encoded?  Note
63    this only applies to elements of character vectors, not to numerical,
64    complex nor logical \code{NA}s, which are always encoded as \code{"NA"}.}
65  % because Mr Gorjanc won't read, PR#12318
66
67  \item{scientific}{Either a logical specifying whether
68    elements of a real or complex vector should be encoded in scientific
69    format, or an integer penalty (see \code{\link{options}("scipen")}).
70    Missing values correspond to the current default penalty.}
71
72  \item{\dots}{further arguments passed to or from other methods.}
73
74  \item{big.mark, big.interval, small.mark,
75    small.interval, decimal.mark, zero.print, drop0trailing}{%
76    used for prettying (longish) numerical and complex sequences.
77    Passed to \code{\link{prettyNum}}: that help page explains the details.}
78}
79\details{
80  \code{format} is a generic function.  Apart from the methods described
81  here there are methods for dates (see \code{\link{format.Date}}),
82  date-times (see \code{\link{format.POSIXct}}) and for other classes such
83  as \code{format.octmode} and \code{format.dist}.
84
85  \code{format.data.frame} formats the data frame column by column,
86  applying the appropriate method of \code{format} for each column.
87  Methods for columns are often similar to \code{as.character} but offer
88  more control.  Matrix and data-frame columns will be converted to
89  separate columns in the result, and character columns (normally all)
90  will be given class \code{"\link{AsIs}"}.
91
92  \code{format.factor} converts the factor to a character vector and
93  then calls the default method (and so \code{justify} applies).
94
95  \code{format.AsIs} deals with columns of complicated objects that
96  have been extracted from a data frame.  Character objects and (atomic)
97  matrices are passed to the default method (and so \code{width} does
98  not apply).
99  Otherwise it calls \code{\link{toString}} to convert the object
100  to character (if a vector or list, element by element) and then
101  right-justifies the result.
102
103  Justification for character vectors (and objects converted to
104  character vectors by their methods) is done on display width (see
105  \code{\link{nchar}}), taking double-width characters and the rendering
106  of special characters (as escape sequences, including escaping
107  backslash but not double quote: see \code{\link{print.default}}) into
108  account.  Thus the width is as displayed by \code{print(quote =
109  FALSE)} and not as displayed by \code{\link{cat}}.  Character strings
110  are padded with blanks to the display width of the widest.  (If
111  \code{na.encode = FALSE} missing character strings are not included in
112  the width computations and are not encoded.)
113
114  Numeric vectors are encoded with the minimum number of decimal places
115  needed to display all the elements to at least the \code{digits}
116  significant digits.  However, if all the elements then have trailing
117  zeroes, the number of decimal places is reduced until
118  \code{nsmall} is reached or at least one
119  element has a non-zero final digit; see also the argument
120  documentation for \code{big.*}, \code{small.*} etc, above.  See the
121  note in \code{\link{print.default}} about \code{digits >= 16}.
122
123  Raw vectors are converted to their 2-digit hexadecimal representation
124  by \code{\link{as.character}}.
125
126  \code{format.default(x)} now provides a \dQuote{minimal} string when
127  \code{\link{isS4}(x)} is true.
128
129  The internal code respects the option
130  \code{\link{getOption}("OutDec")} for the \sQuote{decimal mark}, so if
131  this is set to something other than \code{"."} then it takes precedence
132  over argument \code{decimal.mark}.
133}
134\value{
135  An object of similar structure to \code{x} containing character
136  representations of the elements of the first argument \code{x}
137  in a common format, and in the current locale's encoding.
138
139  For character, numeric, complex or factor \code{x}, dims and dimnames
140  are preserved on matrices/arrays and names on vectors: no other
141  attributes are copied.
142
143  If \code{x} is a list, the result is a character vector obtained by
144  applying \code{format.default(x, \dots)} to each element of the list
145  (after \code{\link{unlist}}ing elements which are themselves lists),
146  and then collapsing the result for each element with
147  \code{paste(collapse = ", ")}.  The defaults in this case are
148  \code{trim = TRUE, justify = "none"} since one does not usually want
149  alignment in the collapsed strings.
150}
151\references{
152  Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
153  \emph{The New S Language}.
154  Wadsworth & Brooks/Cole.
155}
156
157\seealso{
158  \code{\link{format.info}} indicates how an atomic vector would be
159  formatted.
160
161  \code{\link{formatC}}, \code{\link{paste}}, \code{\link{as.character}},
162  \code{\link{sprintf}}, \code{\link{print}}, \code{\link{prettyNum}},
163  \code{\link{toString}}, \code{\link{encodeString}}.
164}
165\examples{
166format(1:10)
167format(1:10, trim = TRUE)
168
169zz <- data.frame("(row names)"= c("aaaaa", "b"), check.names = FALSE)
170format(zz)
171format(zz, justify = "left")
172
173## use of nsmall
174format(13.7)
175format(13.7, nsmall = 3)
176format(c(6.0, 13.1), digits = 2)
177format(c(6.0, 13.1), digits = 2, nsmall = 1)
178
179## use of scientific
180format(2^31-1)
181format(2^31-1, scientific = TRUE)
182
183## a list
184z <- list(a = letters[1:3], b = (-pi+0i)^((-2:2)/2), c = c(1,10,100,1000),
185          d = c("a", "longer", "character", "string"),
186          q = quote( a + b ), e = expression(1+x))
187## can you find the "2" small differences?
188(f1 <- format(z, digits = 2))
189(f2 <- format(z, digits = 2, justify = "left", trim = FALSE))
190f1 == f2 ## 2 FALSE, 4 TRUE
191
192## A "minimal" format() for S4 objects without their own format() method:
193cc <- methods::getClassDef("standardGeneric")
194format(cc) ## "<S4 class ......>"
195}
196\keyword{character}
197\keyword{print}
198