formatC                 package:base                 R Documentation

_F_o_r_m_a_t_t_i_n_g _U_s_i_n_g _C-_s_t_y_l_e _F_o_r_m_a_t_s

_D_e_s_c_r_i_p_t_i_o_n:

     Formatting numbers individually and flexibly, using 'C' style
     format specifications.

_U_s_a_g_e:

     formatC(x, digits = NULL, width = NULL,
             format = NULL, flag = "", mode = NULL,
             big.mark = "", big.interval = 3L,
           small.mark = "", small.interval = 5L,
         decimal.mark = ".", preserve.width = "individual",
             zero.print = NULL, drop0trailing = FALSE)

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

_A_r_g_u_m_e_n_t_s:

       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 unless 'format = "f"'
          where it is limited to typically 324. (Not more than 15-21
          digits need be accurate, depending on the OS and compiler
          used.  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'.  For character data this is interpreted in
          characters (not bytes nor display 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.  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'.  Trailing zeros are
          _dropped_ in this format, unless 'flag' contains '"#"'.

    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.

drop0trailing: logical, indicating if trailing zeros, i.e., '"0"'
          _after_ the decimal mark, should be removed; also drops
          '"e+00"' in exponential formats.

     ...: arguments passed to 'format'.

_D_e_t_a_i_l_s:

     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.

_V_a_l_u_e:

     A character object of same size and attributes as 'x', in the
     current locale's encoding. Unlike 'format', each number is
     formatted individually. Looping over each element of 'x', the C
     function 'sprintf(...)' is called for numeric inputs (inside the C
     function 'str_signif').

     'formatC': for character 'x', do simple (left or right) padding
     with white space.

_A_u_t_h_o_r(_s):

     'formatC' was originally written by Bill Dunlap, later much
     improved by Martin Maechler. It was first adapted for R by
     Friedrich Leisch.

_R_e_f_e_r_e_n_c_e_s:

     Kernighan, B. W. and Ritchie, D. M. (1988) _The C Programming
     Language._  Second edition. Prentice Hall.

_S_e_e _A_l_s_o:

     'format'.

     'sprintf' for more general C like formatting.

_E_x_a_m_p_l_e_s:

     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[1:4], format="f", digits=75) #>> even longer strings

     formatC(c(3.24, 2.3e-6), format="f", digits=11, drop0trailing=TRUE)

     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)