\Header{formatC}{Flexible Formatting}
\alias{format.char}{formatC}
\keyword{character}{formatC}
\keyword{print}{formatC}
\begin{Usage}
\begin{verbatim}
formatC(x, digits = NULL, width = NULL,
        format = NULL, flag = "", mode = NULL)
format.char(x, width = NULL, flag = "-")
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\texttt{x}] an atomic numerical or character object, typically a vector
of real numbers.
\item[\texttt{digits}] the desired number of digits after the decimal
point (\texttt{format = "f"}) or \emph{significant} digits
(\texttt{format = "g"}, \texttt{= "e"} or \texttt{= "fg"}).

Default: 2 for integer, 4 for real numbers.  If less than 0,
the C default of 6 digits is used.
\item[\texttt{width}] the total field width; if both \texttt{digits} and
\texttt{width} are unspecified, \texttt{width} defaults to 1,
otherwise to \texttt{digits + 1}.  \texttt{width = 0} will use
\texttt{width = digits}, \texttt{width < 0} means left
justify the number in this field (equivalent to \texttt{flag ="-"}).
If necessary, the result will have more characters than \texttt{width}.
\item[\texttt{format}] equal to \texttt{"d"}  (for integers), \texttt{"f"},
\texttt{"e"}, \texttt{"E"}, \texttt{"g"}, \texttt{"G"}, \texttt{"fg"} (for
reals), or \texttt{"s"} (for strings). Default \texttt{"d"} for
integers, \texttt{"g"} for reals.

\texttt{"f"} gives numbers in the usual
``xxx.xxx'' format;  \texttt{"e"} and \texttt{"E"} give ``n.dddenn'' or
``n.dddEnn'' (scientific format); \texttt{"g"} and \texttt{"G"} put
\texttt{x[i]} into scientific format only if it saves space to do so.

\texttt{"fg"} uses fixed format as \texttt{"f"}, but \texttt{digits} as
number of \emph{significant} digits.  Note that this can lead to
quite long result strings, see examples below.
\item[\texttt{flag}] format modifier as in Kernighan and Ritchie, 2nd ed.,
page 243.
\texttt{"0"}  pads leading zeros; \texttt{"-"} does left adjustment,
others are \texttt{"+"}, \texttt{" "}, and \texttt{"\#"}.
\item[\texttt{mode}] \texttt{"double"} (or \texttt{"real"}), \texttt{"integer"} or
\texttt{"character"}.
Default: Automatic.
\end{ldescription}
\end{Arguments}
\begin{Description}
Formatting numbers individually and flexibly, using \texttt{C} style
format specifications.\end{Description}
\begin{Details}
If you set \texttt{format} it over-rides the setting of \texttt{mode}, so
\texttt{formatC(123.45, mode="double", format="d")} gives \texttt{123}.\end{Details}
\begin{Value}
A character object of same size and attributes as \texttt{x}.
Unlike \texttt{\Link{format}}, each number is formatted individually.
Looping over each element of \texttt{x}, \texttt{sprintf(...)} is
called (inside the C function \texttt{str\_signif}).

\texttt{format.char(x)} and \texttt{formatC}, for character \texttt{x}, do
simple (left or right) padding with white space.\end{Value}
\begin{Author}
Originally written by Bill Dunlap, later much improved by Martin Maechler,
it was first adapted for \R\ by Friedrich Leisch.\end{Author}
\begin{SeeAlso}
\texttt{\Link{format}}.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
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
\end{ExampleCode}
\end{Examples}

