formatC                 package: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

