Formatting Using C-style Formats

DESCRIPTION:

formatC provides a flexible way to format numbers (and character strings) using C language style format specifications. format.char is used to format strings (and numbers) but with less control of the format.

USAGE:

formatC(x, digits=NULL, width=NULL, format=NULL, flag="",
        mode=NULL, big.mark="", big.interval=3, small.mark="",
        small.interval=5, decimal.mark=".")

format.char(x, width=NULL, flag="-")

REQUIRED ARGUMENTS:

x
a vector of numbers or character strings.

OPTIONAL ARGUMENTS:

digits
an integer specifying the number of digits after the decimal point if format is "f", "fg" or "e", or the number of significant digits if format is "g". The default value is 1 for integers and 4 for real numbers. If digits is a negative value, then the default value is 6. This value is used to create a format string, such as "%f9.3" (digits=3), to pass to function sprintf.
width
an integer specifying the total field width, used to create a format string, such as "%f9.3" (width=9), to pass to sprintf. A negative value for width means to left justify the number in the field (same as flag="-". If necessary, the result will have more characters than width.
format
a character string: "d" or "ld" for integers, "f", "e", "E", "g", "G", "fg" for real numbers, and "s" for strings. If both format and mode arguments are supplied, then format overrides mode. The default value is "ld" for integers, "g" for real numbers, and "s" for character strings. Format "f" gives numbers in the 'xxx.xxx' format; "e" and "E" give 'n.ddde+nn' or 'n.dddE+nn' (scientific format); "g" and "G" put the number into scientific format only if it saves space to do so.
flag
a character string containing one or more if these characters: '0+- #'. "0" pads with leading zeros, "-" means left alignment, "+" adds a plus sign on the front of the number, "#" causes an integer value to be followed by ".0".
mode
one of these character strings: "single", "double", "numeric", "character", "integer". The default value is determined from the storage mode of x.
big.mark
a character to use as a separator in the integer part of a number between the number of digits specified by big.interval.
big.interval
an integer, the number of digits before the decimal point that are between the big.marks. The default value is 3, so that the big.mark is a thousands separator.
small.mark
a character to put between every small.interval number of digits after the decimal point.
small.interval
an integer specifying the number of digits between the small.marks. The default value is 5.
decimal.mark
a character to use as the decimal mark, separating the integer part of a number from the fractional part. The default is ".".

VALUE:

a character vector of the same length of x where each input value has been formatted.

Differences in S-PLUS and R:

The S-PLUS versions of formatC and format.char do not preserve the attributes of x.

In S-PLUS, setting the argument flag to "#" or "0" has no effect.

In R, the argument digits refers to the number of digits after the decimal for format="f" and the number of significant digits for formats "g", "e" and "fg".

In R, the argument mode must be one of these strings: "double" ("real") or "integer". "character" is illegal, although the R help file says it is allowed.

REFERENCES:

Kernighan, B. W. and Ritchie, D. M. (1988) The C Programming Language. Second edition. Prentice Hall.

SEE ALSO:

, .

EXAMPLES:

xx  <- pi * 10^(-5:4)
#  Compare format() and formatC()
cbind(format=format(xx, digits=4), formatC=formatC(xx))

formatC(pi*1e8, big.mark=",",mode="integer")
#  "314,159,265"