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,
             big.mark = "", big.interval = 3,
           small.mark = "", small.interval = 5,
         decimal.mark = ".")

     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 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: 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'.

big.mark, big.interval,
small.mark, small.interval,
decimal.mark: used
          for prettying longer decimal sequences, passed to
          'prettyNum': that help page explains the details.

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', 'sprintf' for more general C like formatting.

Examples:

     xx  <- pi * 10^(-5:4)
     cbind(format(xx, digits=4), formatC(xx))
     cbind(formatC(xx, wid = 9, flag = "-"))
     cbind(formatC(xx, dig = 5, wid = 8, format = "f", flag = "0"))
     cbind(format(xx, digits=4), formatC(xx, dig = 4, format = "fg"))

     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

