Format Specification

The function fmt_spec is used to create a format specification object which describes how a number is to be formatted. The function as_fmt_spec parses a string with a concise representation of the specification into a fmt_spec object.

as_fmt_spec(x = character())

fmt_spec(fill = " ", align = c(">", "<", "^", "="), sign = c("-", "+",
  "(", " "), symbol = NULL, zero = FALSE, width = NULL, comma = FALSE,
  precision = NULL, type = NULL)

Arguments

x
A string representation of the spec. See Details.
fill
A string. See Details.
align
A string. See Details.
sign
A string. See Details.
symbol
A string. See Details.
zero
A logical vector of length one. See Details.
width
An integer vector of length one. See Details.
comma
An logical vector of length one. See Details.
precision
An integer vector of length one. See Details.
type
A character vector of length one. See Details.

Value

An object of class "fmt_spec". This is a list with elements:

fill
Character vector of length one. See Details.
align
Character vector of length one. See Details.
sign
Character vector of length one. See Details.
symbol
Character vector of length one. See Details.
width
Integer vector of length one. See Details.
comma
Logical vector of length one. See Details.
precision
Integer vector of length one.
type
Character vector of length one, or NULL if the default type

Details

The returned function takes a number as the only argument, and returns a string representing the formatted number. The general form of a specifier is: [[fill]align][sign][symbol][0][width][,][.precision][type]

The fill can be any character. The presence of a fill character is signaled by the *align* character following it, which must be one of the following:

  • >: Forces the field to be right-aligned within the available space.
  • <: Forces the field to be left-aligned within the available space.
  • ^: Forces the field to be centered within the available space.
  • =: like >, but with any sign and symbol to the left of any padding.

The sign can be:

  • "-" : nothing for positive and a minus sign for negative. (Default behavior.)
  • "+" : a plus sign for positive and a minus sign for negative. {"("} : nothing for positive and parentheses for negative. {" "} (space) : a space for positive and a minus sign for negative.

The symbol can be:

  • "$": Apply currency symbols as per the locale.
  • "#": The behavior epends on the type:
    • "b": Prefix with "0b".
    • "o": Prefix with "0o".
    • "x", "X", code"a", "A": Prefix with "0x".

The zero (0) option enables zero-padding; this implicitly sets fill to "0" and align to "=".

The width defines the minimum field width; if not specified, then the width will be determined by the content.

The comma (",") option enables the use of a group separator, such as a comma for thousands. The grouping mark and intervals are specified by the locale.

Depending on the type, the precision either indicates the number of digits that follow the decimal point ("f", "%"), or the number of significant digits (NULL, "a", "e", "g", "r", "s", "p"). If the precision is not specified, it defaults to 6 for all types except NULL, which defaults to 12. The recision is ignored for integer formats (types "b", "o", "d", "x", "X" and "c"). See precision_fixed and precision_round for help picking an appropriate precision.

The available type values are:

  • NULL: The default format. It is similar to "g", but insignificant trailing zeros are trimmed.
  • "a","A": Double precision values in binary notation of the form h.hhhp[+-]d. This is a binary fraction expressed in hex and multiplied by a decimal power of 2. The number of hex digits after the decimal point is specified by the precision.
  • "b": Integer values in binary notation.
  • "c": Convert to character using as.character.
  • "d": Integer values in decimal notation.
  • "e","E": Double precision value in exponential notation of the form m.dde[+-]xx or m.ddE[+-]xx.
  • "f": Double precision value in fixed point decimal notation in the form mmm.ddd. The number of decimal palcaes is specified by the precision.
  • "g","G": Double precision value in the either fixed point ("f") or exponential ("e") notation, rounded to significant digits, specified by the precision. Fixed point is used if precision is less than 4, or the exopnent is greater than or equal to the precision. Trailing zeros are not dropped.
  • "n": Shorthand for ",g".
  • "o": Integer values in octal notation.
  • "p": Multiplied by 100, rounded to significant digits, and then formatted with "f" and a percent sign ("%") suffix.
  • "r": Decimal notation, but rounded to significant digits.
  • "s": Decimal notation ("f") with an [SI prefix](#locale_formatPrefix), rounded to significant digits.
  • "u": Integer values converted to its unicode character.
  • "%": Multiplied by 100, and then formatted with decimal notation ("f") and a percent sign ("%") suffix.
  • "x", "X": Hexadecimal notation, rounded to integer. "x" uses lower-case letters, and "X", upper-case letters.

Note that these formats are not the same as those in sprintf.