# 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 = 3,
          small.mark = "", small.interval = 5,
        decimal.mark = ".", preserve.width = "individual")

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

### 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. If specified as more than 50, 50 will be used with a warning. (Not more than about 15 digits will be significant, and 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`.

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

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

### Value

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

### Author(s)

`formatC` was 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`.

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

    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", digits=80) #>> also long strings

    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)

[Package base version 2.6.0 Index]