C-style formatted output

DESCRIPTION:

Use the C sprintf function to combine numbers and strings into a formatted string.

USAGE:

sprintf(format, ...)
gettextf(format, ..., domain=NULL)

REQUIRED ARGUMENTS:

format
A format string as used by the standard C sprintf function, although not all features are supported. Each % (except %%) signals that start of a conversion specification for one of the ... arguments. See the DETAILS section below. If translation were enabled, the format string would be translated by the function when used in a call to gettextf.

OPTIONAL ARGUMENTS:

...
As in the C sprintf function, the arguments after the format string correspond to the % conversion specifications in the format string. Usually each conversion specification refers to one ... argument, but if there are *'s in the conversion specification then each * refers to one ... argument.
domain
the domain to use for language translation. This argument is ignored in this version of S-PLUS.

VALUE:

A vector of formatted strings. The length of the output vector is the length of the longest argument; shorter arguments are recycled to the length of the longest. However, if any argument is 0 long, the output will be 0 long.

DETAILS:

The conversion specifiers start with a % and end with one of the following conversion characters:

"s"     string
"d"     signed decimal integer
"i"     signed decimal integer
"u"     unsigned decimal integer
"o"     octal integer
"x"     hexadecimal integer
"X"     hexadecimal integer, with capital A-F
"f"     floating point number, no scientific notation
"g"     floating point number, use e+exponent scientific notation
        if it would be shorter
"G"     floating point number, use E+exponent scientific notation
        if it would be shorter
"e"     floating point number, e+exponent scientific notation
"E"     floating point number, E+exponent scientific notation
"c"     single character
"p"     pointer

The integral conversion character may be preceded by an "l" (ell) to indicate the value is a C long (this only makes a difference on 64-bit platforms) or an "h" for a C short (only bottom 16 bits are used). By default they refer to 32 bit C ints (Splus integers are C longs).

The conversion character (along with the possible size modifier) may be preceded by minwidth.precision where minwidth and precision are both integers and neither must be present. Their precise meaning depends on the conversion character, but in general minwidth gives the minimum number of characters to use and precision gives details like the number of significant digits, the number of digits after the decimal point, or the maximum number of characters to use. Please refer to a C language manual for details.

Either minwidth or precision may be given as "*", which means to use the next argument in the ... list as the value. Thus one conversion specification may use 1, 2, or 3 arguments from the ... list, depending the presence of the asterisks.

The conversion character (along with possible minwidth.precision and size modifier) may be preceded by some single character flags, whose meaning depends on the conversion character. E.g., for "d" a "0" means to fill the space before the most significant digit with 0's and a "+" means to precede positive numbers with a plus sign. Please refer to a C language manual for details.

The C standard allows the % specifier to start with "%n$" for a number "n" and this means the specifier refers to the n'th ... argument. The Splus sprintf does not support this feature now: the ... arguments must be in same order as the conversion specifiers.

These functions emulate the R functions sprintf and gettextf. Because Native Language Support and support for domains are not included in this version of S-PLUS, calling gettextf gives the same result as calling sprintf.

SEE ALSO:

, , , .

EXAMPLES:

sprintf("pi is about %4.2f", asin(1)*2)
# [1] "pi is about 3.14"
sprintf("Hex for decimal %2d is 0x%02x", c(3,19,40), c(3,19,40))
# [1] "Hex for decimal  3 is 0x03" "Hex for decimal 19 is 0x13"
# [3] "Hex for decimal 40 is 0x28"
> sprintf(c("%d","%x","%o"), 46) # vector for formats, one number to format
# [1] "46" "2e" "56"
> sprintf("%*.*g", 12, 2:10, exp(10)) # vary number of significant digits
# [1] "     2.2e+04" "     2.2e+04"
# [3] "   2.203e+04" "       22026"
# [5] "     22026.5" "    22026.47"
# [7] "   22026.466" "  22026.4658"
# [9] " 22026.46579"
cat(sep="\n", sprintf("\"%4.4s\" is 4 letter abbreviation for %s.",
    c("A","Alabama"), c("A","Alabama")))
# "   A" is 4 letter abbreviation for A.
# "Alab" is 4 letter abbreviation for Alabama.