R: Formatting Using C-style Formats

formatC {base} | R Documentation

## Formatting Using C-style Formats

### Description

Formatting numbers individually and flexibly, using `C` style format specifications.

### Usage

    formatC(x, digits = NULL, width = NULL,
            format = NULL, flag = "", mode = NULL,
            big.mark = "", big.interval = 3L,
            small.mark = "", small.interval = 5L,
            decimal.mark = ".", preserve.width = "individual",
            zero.print = NULL, drop0trailing = FALSE)

    prettyNum(x, big.mark = "",   big.interval = 3L,
              small.mark = "", small.interval = 5L,
              decimal.mark = ".",
              preserve.width = c("common", "individual", "none"),
              zero.print = NULL, drop0trailing = FALSE, is.cmplx = NA,
              ...)

### Arguments

`x` | an atomic numerical or character object, possibly `complex` only for `prettyNum()`, typically a vector of real numbers. Any class is discarded, with a warning.
`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. If specified as more than 50, 50 will be used with a warning unless `format = "f"` where it is limited to typically 324. (Not more than 15–21 digits need be accurate, depending on the OS and compiler used. This limit is just a precaution against segfaults in the underlying C runtime.)
`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`. For character data this is interpreted in characters (not bytes nor display 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 the minimum number of significant digits. This can lead to quite long result strings, see examples below. Note that unlike `signif` this prints large numbers with more significant digits than `digits`. Trailing zeros are dropped in this format, unless `flag` contains `"#"`.
`flag` | For `formatC`, a character string giving a format modifier as in Kernighan and Ritchie (1988, page 243). `"0"` pads leading zeros; `"-"` does left adjustment, others are `"+"`, `" "`, and `"#"`. There can be more than one of these, in any order.
`mode` | `"double"` (or `"real"`), `"integer"` or `"character"`. Default: Determined from the storage mode of `x`.
`big.mark` | character; if not empty used as mark between every `big.interval` decimals before (hence `big`) the decimal point.
`big.interval` | see `big.mark` above; defaults to 3.
`small.mark` | character; if not empty used as mark between every `small.interval` decimals after (hence `small`) the decimal point.
`small.interval` | see `small.mark` above; defaults to 5.
`decimal.mark` | the character to be used to indicate the numeric decimal point.
`preserve.width` | string specifying if the string widths should be preserved where possible in those cases where marks (`big.mark` or `small.mark`) are added. `"common"`, the default, corresponds to `format`-like behavior whereas `"individual"` is the default in `formatC()`.
`zero.print` | logical, character string or `NULL` specifying if and how zeros should be formatted specially. Useful for pretty printing ‘sparse’ objects.
`drop0trailing` | logical, indicating if trailing zeros, i.e., `"0"` after the decimal mark, should be removed; also drops `"e+00"` in exponential formats.
`is.cmplx` | optional logical, to be used when `x` is `"character"` to indicate if it stems from `complex` vector or not. By default (`NA`), `x` is checked to ‘look like’ complex.
`...` | arguments passed to `format`.

### 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 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`.

`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. Note that `prettyNum(x)` may behave unexpectedly if `x` is a `character` vector not resulting from something like `format(<number>)`: in particular it assumes that a period is a 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` ....

### 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` is not appropriate for use within `print` methods: use `decimal.mark = getOption("OutDec")` there.

### Author(s)

`formatC` was originally written by Bill Dunlap for S-PLUS, 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 C like formatting.

### Examples

    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 long-double arithmetic, which is platform-specific.
    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[1:4], format = "f", digits = 75) #>> even longer strings

    formatC(c(3.24, 2.3e-6), 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)

    ## 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)

[Package base version 3.1.2 Index]