

   FFlleexxiibbllee FFoorrmmaattttiinngg

        formatC(x, digits = NULL, width = NULL,
                format = NULL, flag = "", mode = NULL)
        format.char(x, width = NULL, flag = "-")

   AArrgguummeennttss::

          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 `"d"' for integers, `"g"'
             for reals.

             `"f"' gives numbers in the usual ``xxx.xxx'' for-
             mat;  `"e"' and `"E"' give ``n.dddenn'' or
             ``n.dddEnn'' (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, 2nd
             ed., page 243.  `"0"'  pads leading zeros; `"-"'
             does left adjustment, others are `"+"', `" "', and
             `"#"'.

       mode: `"double"' (or `"real"'), `"integer"' or `"charac-
             ter"'.  Default: Automatic.

   DDeessccrriippttiioonn::

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

   DDeettaaiillss::

        If you set `format' it over-rides the setting of
        `mode', so `formatC(123.45, mode="double", format="d")'
        gives `123'.

   VVaalluuee::

        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.

   AAuutthhoorr((ss))::

        Originally written by Bill Dunlap, later much improved
        by Martin Maechler, it was first adapted for R by
        Friedrich Leisch.

   SSeeee AAllssoo::

        `format'.

   EExxaammpplleess::

        xx  <- pi * 10^(-5:4)
        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

