formatC {base} | R Documentation

## Formatting Using C-style Formats

### Description

Formatting numbers individually and flexibly, using `C` style format specifications. `format.char` is a helper function for `formatC`.

### Usage

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

### Arguments

`x` | an atomic numerical or character object, typically a vector of real numbers.
`digits` | the desired number of digits after the decimal point (`format = "f"`) or significant digits (`format = "g"`, `= "e"` or `= "fg"`). Default: 2 for integer, 4 for real numbers. If less than 0, the C default of 6 digits is used.
`width` | the total field width; if both `digits` and `width` are unspecified, `width` defaults to 1, otherwise to `digits + 1`. `width = 0` will use `width = digits`, `width < 0` means left justify the number in this field (equivalent to `flag ="-"`). If necessary, the result will have more characters than `width`.
`format` | equal to `"d"` (for integers), `"f"`, `"e"`, `"E"`, `"g"`, `"G"`, `"fg"` (for reals), or `"s"` (for strings). Default is `"d"` for integers, `"g"` for reals. `"f"` gives numbers in the usual `xxx.xxx` format; `"e"` and `"E"` give `n.ddde+nn` or `n.dddE+nn` (scientific format); `"g"` and `"G"` put `x[i]` into scientific format only if it saves space to do so. `"fg"` uses fixed format as `"f"`, but `digits` as number of significant digits. Note that this can lead to quite long result strings, see examples below.
`flag` | format modifier as in Kernighan and Ritchie (1988, page 243). `"0"` pads leading zeros; `"-"` does left adjustment, others are `"+"`, `" "`, and `"#"`.
`mode` | `"double"` (or `"real"`), `"integer"` or `"character"`. Default: Determined from the storage mode of `x`.

### Details

If you set `format` it over-rides the setting of `mode`, so `formatC(123.45, mode="double", format="d")` gives `123`.

The rendering of scientific format is platform-dependent: 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`.

### Value

A character object of same size and attributes as `x`. Unlike `format`, each number is formatted individually. Looping over each element of `x`, `sprintf(...)` is called (inside the C function `str_signif`).
`format.char(x)` and `formatC`, for character `x`, do simple (left or right) padding with white space.

### Author(s)

Originally written by Bill Dunlap, later much improved by Martin Maechler, it was first adapted for R by Friedrich Leisch.

### References

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

### See Also

`format`.

### Examples

    xx  <- pi * 10^(-5:4)
    dd <- options(digits = 4)   # only for format
    cbind(format(xx), formatC(xx))
    cbind(formatC(xx, wid = 9, flag = "-"))
    cbind(formatC(xx, dig = 5, wid = 8, format = "f", flag = "0"))

    format.char(c("a", "Abc", "no way"), wid = -7)  # <=> flag = "-"
    formatC(    c("a", "Abc", "no way"), wid = -7)  # <=> flag = "-"
    formatC(c((-1:1)/0,c(1,100)*pi), wid=8, dig=1)

    xx <- c(1e-12,-3.98765e-10,1.45645e-69,1e-70,pi*1e37,3.44e4)
    ##       1        2             3        4      5       6
    formatC(xx)
    formatC(xx, format="fg")       # special "fixed" format.
    formatC(xx, format="f", dig=80)#>> also long strings
    options(dd) # reset