-
Notifications
You must be signed in to change notification settings - Fork 306
/
sprintf.Rd
198 lines (168 loc) · 7.35 KB
/
sprintf.Rd
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
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
% File src/library/base/man/sprintf.Rd
% Part of the R package, http://www.R-project.org
% Copyright 1995-2008 R Core Development Team
% Distributed under GPL 2 or later
\name{sprintf}
\alias{sprintf}
\alias{gettextf}
\title{Use C-style String Formatting Commands}
\description{
A wrapper for the C function \code{sprintf}, that returns a character
vector containing a formatted combination of text and variable values.
}
\usage{
sprintf(fmt, \dots)
gettextf(fmt, \dots, domain = NULL)
}
\arguments{
\item{fmt}{a character vector of format strings, each of up to 8192 bytes.}
\item{\dots}{values to be passed into \code{fmt}. Only logical,
integer, real and character vectors are supported, but some coercion
will be done: see the \sQuote{Details} section.}
\item{domain}{see \code{\link{gettext}}.}
}
\details{
\code{sprintf} is a wrapper for the system \code{sprintf} C-library
function. Attempts are made to check that the mode of the values
passed match the format supplied, and \R's special values (\code{NA},
\code{Inf}, \code{-Inf} and \code{NaN}) are handled correctly.
\code{gettextf} is a convenience function which provides C-style
string formatting with possible translation of the format string.
The arguments (including \code{fmt}) are recycled if possible a whole
number of times to the length of the longest, and then the formatting
is done in parallel.
The following is abstracted from Kernighan and Ritchie
(see References). The string \code{fmt} contains normal characters,
which are passed through to the output string, and also conversion
specifications which operate on the arguments provided through
\code{\dots}. The allowed conversion specifications start with a
\code{\%} and end with one of the letters in the set
\code{difeEgGsxX\%}. These letters denote the following types:
\describe{
\item{\code{d, i, x, X}}{Integer value, \code{x} and \code{X}
being hexadecimal (using the same case for \code{a-f} as the code).
Numeric variables with exactly integer values will be coerced to
integer. Formats \code{d} and \code{i} can also be used for
logical variables, which will be converted to \code{0}, \code{1}
or \code{NA}.
}
\item{\code{f}}{Double precision value, in decimal notation of the
form "[-]mmm.ddd". The number of decimal places is specified by
the precision: the default is 6; a precision of 0 suppresses the
decimal point. Non-finite values are converted to \code{NA},
\code{NaN} or (perhaps a sign followed by) \code{Inf}.
}
\item{\code{e, E}}{Double precision value, in decimal notation of the
form \code{[-]m.ddde[+-]xx} or \code{[-]m.dddE[+-]xx}.
}
\item{\code{g, G}}{Double precision value, in \code{\%e} or
\code{\%E} format if the exponent is less than -4 or greater than or
equal to the precision, and \code{\%f} format otherwise.
}
\item{\code{s}}{Character string. Character \code{NA}s are
converted to \code{"NA"}.
}
\item{\code{\%}}{Literal \code{\%} (none of the extra formatting
characters given below are permitted in this case).
}
}
Conversion by \code{\link{as.character}} is used for non-character
arguments with \code{s} and by \code{\link{as.double}} for
non-double arguments with \code{f, e, E, g, G}. NB: the length is
determined before conversion, so do not rely on the internal
coercion if this would change the length. The coercion is done only
once, so if \code{length(fmt) > 1} then all elements must expect the
same types of arguments.
In addition, between the initial \code{\%} and the terminating
conversion character there may be, in any order:
\describe{
\item{\code{m.n}}{Two numbers separated by a period, denoting the
field width (\code{m}) and the precision (\code{n}).}
\item{\code{-}}{Left adjustment of converted argument in its field.}
\item{\code{+}}{Always print number with sign: by default only
negative numbers are printed with a sign.}
\item{a space}{Prefix a space if the first character is not a sign.}
\item{\code{0}}{For numbers, pad to the field width with leading zeros.}
}
Further, immediately after \code{\%} may come \code{1$} to \code{99$}
to refer to numbered argument: this allows arguments to be
referenced out of order and is mainly intended for translators of
error messages. If this is done it is best if all formats are
numbered: if not the unnumbered ones process the arguments in order.
See the examples. This notation allows arguments to be used more than
once, in which case they must be used as the same type (integer,
double or character).
A field width or precision (but not both) may be indicated by an
asterisk \code{*}: in this case an argument specifies the desired
number. A negative field width is taken as a '-' flag followed by a
positive field width. A negative precision is treated as if the
precision were omitted. The argument should be integer, but a double
argument will be coerced to integer.
There is a limit of 8192 bytes on elements of \code{fmt} and also on
strings included by a \code{\%s} conversion specification.
}
\value{
A character vector of length that of the longest input.
}
\references{
Kernighan, B. W. and Ritchie, D. M. (1988)
\emph{The C Programming Language.} Second edition, Prentice Hall.
describes the format options in table B-1 in the Appendix.
}
\author{
Original code by Jonathan Rougier, \email{J.C.Rougier@durham.ac.uk}.
}
\seealso{
\code{\link{formatC}} for a way of formatting vectors of numbers in a
similar fashion.
\code{\link{paste}} for another way of creating a vector combining
text and values.
\code{\link{gettext}} for the mechanisms for the automated translation
of text.
}
\examples{
% Escape all the '%' here !
## be careful with the format: most things in R are floats
## only integer-valued reals get coerced to integer.
sprintf("\%s is \%f feet tall\n", "Sven", 7.1) # OK
try(sprintf("\%s is \%i feet tall\n", "Sven", 7.1)) # not OK
try(sprintf("\%s is \%i feet tall\n", "Sven", 7)) # OK
## use a literal \% :
sprintf("\%.0f\%\% said yes (out of a sample of size \%.0f)", 66.666, 3)
## various formats of pi :
sprintf("\%f", pi)
sprintf("\%.3f", pi)
sprintf("\%1.0f", pi)
sprintf("\%5.1f", pi)
sprintf("\%05.1f", pi)
sprintf("\%+f", pi)
sprintf("\% f", pi)
sprintf("\%-10f", pi) # left justified
sprintf("\%e", pi)
sprintf("\%E", pi)
sprintf("\%g", pi)
sprintf("\%g", 1e6 * pi) # -> exponential
sprintf("\%.9g", 1e6 * pi) # -> "fixed"
sprintf("\%G", 1e-6 * pi)
## no truncation:
sprintf("\%1.f",101)
## re-use one argument three times, show difference between \%x and \%X
xx <- sprintf("\%1$d \%1$x \%1$X", 0:15)
xx <- matrix(xx, dimnames=list(rep("", 16), "\%d\%x\%X"))
noquote(format(xx, justify="right"))
## More sophisticated:
sprintf("min 10-char string '\%10s'",
c("a", "ABC", "and an even longer one"))
n <- 1:18
sprintf(paste("e with \%2d digits = \%.",n,"g",sep=""), n, exp(1))
## Using arguments out of order
sprintf("second \%2$1.0f, first \%1$5.2f, third \%3$1.0f", pi, 2, 3)
## Using asterisk for width or precision
sprintf("precision \%.*f, width '\%*.3f'", 3, pi, 8, pi)
## Asterisk and argument re-use, 'e' example reiterated:
sprintf("e with \%1$2d digits = \%2$.*1$g", n, exp(1))
## re-cycle arguments
sprintf("\%s \%d", "test", 1:3)
}
\keyword{print}
\keyword{character}