format {base} | R Documentation

## Encode in a Common Format

### Description

Format an R object for pretty printing: `format.pval` is intended for formatting p-values.

### Usage

    format(x, ...)

    ## S3 method for class 'AsIs':
    format(x, width = 12, ...)

    ## S3 method for class 'data.frame':
    format(x, ..., justify = "none")

    ## Default S3 method:
    format(x, trim = FALSE, digits = NULL,
           nsmall = 0, justify = c("left", "right", "none"),
           big.mark = "",   big.interval = 3,
         small.mark = "", small.interval = 5,
       decimal.mark = ".", ...)

    ## S3 method for class 'factor':
    format(x, ...)

    format.pval(pv, digits = max(1, getOption("digits") - 2),
                eps = .Machine$double.eps, na.form = "NA")

    prettyNum(x, big.mark = "",   big.interval = 3,
               small.mark = "", small.interval = 5,
             decimal.mark = ".", ...)

### Arguments

`x` | any R object (conceptually); typically numeric.
`trim` | logical; if `TRUE`, leading blanks are trimmed off the strings.
`digits` | how many significant digits are to be used for `numeric x`. The default, `NULL`, uses `options()$digits`. This is a suggestion: enough decimal places will be used so that the smallest (in magnitude) number has this many significant digits.
`nsmall` | number of digits which will always appear to the right of the decimal point in formatting real/complex numbers in non-scientific formats. Allowed values `0 <= nsmall <= 20`.
`justify` | should character vector be left-justified, right-justified or left alone. When justifying, the field width is that of the longest string.
`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 used to indicate the numeric decimal point.
`pv` | a numeric vector.
`eps` | a numerical tolerance: see Details.
`na.form` | character representation of `NA`s.
`width` | the returned vector has elements of at most `width`.
`...` | further arguments passed to or from other methods.

### Details

These functions convert their first argument to a vector (or array) of character strings which have a common format (as is done by `print`), fulfilling `length(format*(x, *)) == length(x)`. The trimming with `trim = TRUE` is useful when the strings are to be used for plot `axis` annotation.

`format.AsIs` deals with columns of complicated objects that have been extracted from a data frame.

`format.pval` is mainly an auxiliary function for `print.summary.lm` etc., and does separate formatting for fixed, floating point and very small values; those less than `eps` are formatted as `"< [eps]"` (where “[eps]” stands for `format(eps, digits)`.

The function `formatC` provides a rather more flexible formatting facility for numbers, but does not provide a common format for several numbers, nor it is platform-independent.

`format.data.frame` formats the data frame column by column, applying the appropriate method of `format` for each column.

`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` not resulting from something like `format(<number>)`.

### Note

Currently `format` drops trailing zeroes, so `format(6.001, digits=2)` gives `"6"` and `format(c(6.0, 13.1), digits=2)` gives `c(" 6", "13")`.

Character(s) `"` in input strings `x` are escaped to `\"`.

### References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.

### See Also

`format.info` indicates how something would be formatted; `formatC`, `paste`, `as.character`, `sprintf`.

### Examples

    format(1:10)

    zz <- data.frame("(row names)"= c("aaaaa", "b"), check.names=FALSE)
    format(zz)
    format(zz, justify="left")

    ## use of nsmall
    format(13.7)
    format(13.7, nsmall=3)

    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="'")

    pN <- pnorm(1:7, lower=FALSE)
    cbind(format (pN, small.mark = " ", digits = 15))
    cbind(formatC(pN, small.mark = " ", digits = 17, format = "f"))

[Package Contents]