Formatting Using Cstyle Formats
Description
Formatting numbers individually and flexibly, formatC()
using
C
style format specifications.
prettyNum()
is used for “prettifying” (possibly
formatted) numbers, also in format.default
.
.format.zeros()
, an auxiliary function of prettyNum()
reformats the zeros in a vector x
of formatted numbers.
Usage
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16  formatC(x, digits = NULL, width = NULL,
format = NULL, flag = "", mode = NULL,
big.mark = "", big.interval = 3L,
small.mark = "", small.interval = 5L,
decimal.mark = getOption("OutDec"),
preserve.width = "individual", zero.print = NULL,
drop0trailing = FALSE)
prettyNum(x, big.mark = "", big.interval = 3L,
small.mark = "", small.interval = 5L,
decimal.mark = getOption("OutDec"), input.d.mark = decimal.mark,
preserve.width = c("common", "individual", "none"),
zero.print = NULL, drop0trailing = FALSE, is.cmplx = NA,
...)
.format.zeros(x, zero.print, nx = suppressWarnings(as.numeric(x)))

Arguments
x 
an atomic numerical or character object, possibly

digits 
the desired number of digits after the decimal
point ( Default: 2 for integer, 4 for real numbers. If less than 0,
the C default of 6 digits is used. If specified as more than 50, 50
will be used with a warning unless 
width 
the total field width; if both 
format 
equal to

flag 
For 
mode 

big.mark 
character; if not empty used as mark between every

big.interval 
see 
small.mark 
character; if not empty used as mark between every

small.interval 
see 
decimal.mark 
the character to be used to indicate the numeric decimal point. 
input.d.mark 
if 
preserve.width 
string specifying if the string widths should
be preserved where possible in those cases where marks
( 
zero.print 
logical, character string or 
drop0trailing 
logical, indicating if trailing zeros,
i.e., 
is.cmplx 
optional logical, to be used when 
... 
arguments passed to 
nx 
numeric vector of the same length as 
Details
If you set format
it overrides the setting of mode
, so
formatC(123.45, mode = "double", format = "d")
gives 123
.
The rendering of scientific format is platformdependent: some systems
use n.ddde+nnn
or n.dddenn
rather than n.ddde+nn
.
formatC
does not necessarily align the numbers on the decimal
point, so formatC(c(6.11, 13.1), digits = 2, format = "fg")
gives
c("6.1", " 13")
. If you want common formatting for several
numbers, use format
.
prettyNum
is the utility function for prettifying x
.
x
can be complex (or format(<complex>)
, here. If
x
is not a character, format(x[i], ...)
is applied to
each element, and then it is left unchanged if all the other arguments
are at their defaults. Use the input.d.mark
argument for
prettyNum(x)
when x
is a character
vector not
resulting from something like format(<number>)
with a period as
decimal mark.
Because gsub
is used to insert the big.mark
and small.mark
, special characters need escaping. In particular,
to insert a single backslash, use "\\\\"
.
The C doubles used for R numerical vectors have signed zeros, which
formatC
may output as 0
, 0.000
....
There is a warning if big.mark
and decimal.mark
are the
same: that would be confusing to those reading the output.
Value
A character object of same size and attributes as x
(after
discarding any class), in the current locale's encoding.
Unlike format
, each number is formatted individually.
Looping over each element of x
, the C function
sprintf(...)
is called for numeric inputs (inside the C
function str_signif
).
formatC
: for character x
, do simple (left or right)
padding with white space.
Note
Prior to R 3.0.2 this copied the class of x
to the return
value and could easily create invalid objects.
The default for decimal.mark
in formatC()
was changed in
R 3.2.0: for use within print
methods in packages which might
be used with earlier versions: use decimal.mark = getOption("OutDec")
explicitly.
Author(s)
formatC
was originally written by Bill Dunlap for SPLUS, later
much improved by Martin Maechler.
It was first adapted for R by Friedrich Leisch and since much improved by the R Core team.
References
Kernighan, B. W. and Ritchie, D. M. (1988) The C Programming Language. Second edition. Prentice Hall.
See Also
format
.
sprintf
for more general Clike formatting.
Examples
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57  xx < pi * 10^(5:4)
cbind(format(xx, digits = 4), formatC(xx))
cbind(formatC(xx, width = 9, flag = ""))
cbind(formatC(xx, digits = 5, width = 8, format = "f", flag = "0"))
cbind(format(xx, digits = 4), formatC(xx, digits = 4, format = "fg"))
formatC( c("a", "Abc", "no way"), width = 7) # <=> flag = ""
formatC(c((1:1)/0,c(1,100)*pi), width = 8, digits = 1)
## note that some of the results here depend on the implementation
## of longdouble arithmetic, which is platformspecific.
xx < c(1e12,3.98765e10,1.45645e69,1e70,pi*1e37,3.44e4)
## 1 2 3 4 5 6
formatC(xx)
formatC(xx, format = "fg") # special "fixed" format.
formatC(xx[1:4], format = "f", digits = 75) #>> even longer strings
formatC(c(3.24, 2.3e6), format = "f", digits = 11, drop0trailing = TRUE)
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 = "'")
## examples of 'small.mark'
pN < stats::pnorm(1:7, lower.tail = FALSE)
cbind(format (pN, small.mark = " ", digits = 15))
cbind(formatC(pN, small.mark = " ", digits = 17, format = "f"))
cbind(ff < format(1.2345 + 10^(0:5), width = 11, big.mark = "'"))
## all with same width (one more than the specified minimum)
## individual formatting to common width:
fc < formatC(1.234 + 10^(0:8), format = "fg", width = 11, big.mark = "'")
cbind(fc)
## Powers of two, stored exactly, formatted individually:
pow.2 < formatC(2^(1:32), digits = 24, width = 1, format = "fg")
## nicely printed (the last line showing 5^32 exactly):
noquote(cbind(pow.2))
## complex numbers:
r < 10.0000001; rv < (r/10)^(1:10)
(zv < (rv + 1i*rv))
op < options(digits = 7) ## (system default)
(pnv < prettyNum(zv))
stopifnot(pnv == "1+1i", pnv == format(zv),
pnv == prettyNum(zv, drop0trailing = TRUE))
## more digits change the picture:
options(digits = 8)
head(fv < format(zv), 3)
prettyNum(fv)
prettyNum(fv, drop0trailing = TRUE) # a bit nicer
options(op)
