sprintf                 package:base                 R Documentation

_U_s_e _C-_s_t_y_l_e _S_t_r_i_n_g _F_o_r_m_a_t_t_i_n_g _C_o_m_m_a_n_d_s

_D_e_s_c_r_i_p_t_i_o_n:

     A wrapper for the C function 'sprintf', that returns a character
     vector containing a formatted combination of text and variable
     values.

_U_s_a_g_e:

     sprintf(fmt, ...)
     gettextf(fmt, ..., domain = NULL)

_A_r_g_u_m_e_n_t_s:

     fmt: a character vector of format strings, each of up to 8192
          bytes.

     ...: values to be passed into 'fmt'.  Only logical, integer, real
          and character vectors are supported, but some coercion will
          be done: see the 'Details' section.

  domain: see 'gettext'.

_D_e_t_a_i_l_s:

     'sprintf' is a wrapper for the system 'sprintf' C-library
     function.  Attempts are made to check that the mode of the values
     passed match the format supplied, and R's special values ('NA',
     'Inf', '-Inf' and 'NaN') are handled correctly.

     'gettextf' is a convenience function which provides C-style string
     formatting with possible translation of the format string.

     The arguments (including 'fmt') are recycled if possible a whole
     number of times to the length of the longest, and then the
     formatting is done in parallel.  As from R 2.9.0 zero-length
     arguments are allowed and will give a zero-length result.  All
     arguments are evaluated even if unused, and hence some types
     (e.g., '"symbol"' or '"language"', see 'typeof') are not allowed.

     The following is abstracted from Kernighan and Ritchie (see
     References).  The string 'fmt' contains normal characters, which
     are passed through to the output string, and also conversion
     specifications which operate on the arguments provided through
     '...'.  The allowed conversion specifications start with a '%' and
     end with one of the letters in the set 'difeEgGsxXaA%'.  These
     letters denote the following types:


     '_d, _i, _x, _X' Integer value, 'x' and 'X' being hexadecimal (using
          the same case for 'a-f' as the code). Numeric variables with
          exactly integer values will be coerced to integer. Formats
          'd' and 'i' can also be used for logical variables, which
          will be converted to '0', '1' or 'NA'.

     '_f' Double precision value, in "*f*ixed point" decimal notation of
          the form "[-]mmm.ddd".  The number of decimal places ("d") is
          specified by the precision: the default is 6; a precision of
          0 suppresses the decimal point.  Non-finite values are
          converted to 'NA', 'NaN' or (perhaps a sign followed by)
          'Inf'.

     '_e, _E' Double precision value, in "*e*xponential" decimal notation
          of the form '[-]m.ddde[+-]xx' or '[-]m.dddE[+-]xx'.

     '_g, _G' Double precision value, in '%e' or '%E' format if the
          exponent is less than -4 or greater than or equal to the
          precision, and '%f' format otherwise. (The precision (default
          6) specifies the number of _significant_ digits here, whereas
          in '%f, %e', it is the number of digits after the decimal
          point.)

     '_a, _A' Double precision value, in binary notation of the form
          '[-]0xh.hhhp[+-]d'.  This is a binary fraction expressed in
          hex multiplied by a (decimal) power of 2.  The number of hex
          digits after the decimal point is specified by the precision:
          the default is enough digits to represent exactly the
          internal binary representation.  Non-finite values are
          converted to 'NA', 'NaN' or (perhaps a sign followed by)
          'Inf'.  Format '%a' uses lower-case for 'x', 'p' and the hex
          values: format '%A' uses upper-case.

          This might not be supported on all platforms as it is a
          feature of C99. The format is not uniquely defined: although
          it would be possible to make the leading 'h' always zero or
          one, this is not always done.  Most systems will suppress
          trailing zeros, but a few do not.  On a well-written
          platform, for normal numbers there will be a leading one
          before the decimal point plus (by default) 13 hexadecimal
          digits, hence 53 bits.  (The treatment of denormalized
          numbers is very platform-dependent.)

     '_s' Character string.  Character 'NA's are converted to '"NA"'.

     '%' Literal '%' (none of the extra formatting characters given
          below are permitted in this case).


     Conversion by 'as.character' is used for non-character arguments
     with 's' and by 'as.double' for non-double arguments with 'f, e,
     E, g, G'.  NB: the length is determined before conversion, so do
     not rely on the internal coercion if this would change the length.
      The coercion is done only once, so if 'length(fmt) > 1' then all
     elements must expect the same types of arguments.

     In addition, between the initial '%' and the terminating
     conversion character there may be, in any order:


     '_m._n' Two numbers separated by a period, denoting the field width
          ('m') and the precision ('n').

     '-' Left adjustment of converted argument in its field.

     '+' Always print number with sign: by default only negative
          numbers are printed with a sign.

     _a _s_p_a_c_e Prefix a space if the first character is not a sign.

     '_0' For numbers, pad to the field width with leading zeros.

     '#' specifies "alternate output" for numbers, its action depending
          on the type: For 'x' or 'X', '0x' or '0X' will be prefixed to
          a non-zero result.  For 'e', 'e', 'f', 'g' and 'G', the
          output will always have a decimal point; for 'g' and 'G',
          trailing zeros will not be removed.


     Further, immediately after '%' may come '1$' to '99$' to refer to
     numbered argument: this allows arguments to be referenced out of
     order and is mainly intended for translators of error messages. 
     If this is done it is best if all formats are numbered: if not the
     unnumbered ones process the arguments in order. See the examples. 
     This notation allows arguments to be used more than once, in which
     case they must be used as the same type (integer, double or
     character).

     A field width or precision (but not both) may be indicated by an
     asterisk '*': in this case an argument specifies the desired
     number.  A negative field width is taken as a '-' flag followed by
     a positive field width.  A negative precision is treated as if the
     precision were omitted.  The argument should be integer, but a
     double argument will be coerced to integer.

     There is a limit of 8192 bytes on elements of 'fmt', and on
     strings included from a single '%'_letter_ conversion
     specification.

     Field widths and precisions of '%s' conversions are interpreted as
     bytes, not characters, as described in the C standard.

_V_a_l_u_e:

     A character vector of length that of the longest input.  If any
     element of 'fmt' or any character argument is declared as UTF-8,
     the element of the result will be in UTF-8 and have the encoding
     declared as UTF-8.  Otherwise it will be in the current locale's
     encoding.

_W_a_r_n_i_n_g:

     The format string is passed down the OS's 'sprintf' function, and
     incorrect formats can cause the latter to crash the R process .  R
     does perform sanity checks on the format, and since R 2.10.0, we
     have not seen crashes anymore.  But not all possible user errors
     on all platforms have been tested, and some might be terminal.

_A_u_t_h_o_r(_s):

     Original code by Jonathan Rougier.

_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. describes the format
     options in table B-1 in the Appendix.

_S_e_e _A_l_s_o:

     'formatC' for a way of formatting vectors of numbers in a similar
     fashion.

     'paste' for another way of creating a vector combining text and
     values.

     'gettext' for the mechanisms for the automated translation of
     text.

_E_x_a_m_p_l_e_s:

     ## be careful with the format: most things in R are floats
     ## only integer-valued reals get coerced to integer.

     sprintf("%s is %f feet tall\n", "Sven", 7.1)      # OK
     try(sprintf("%s is %i feet tall\n", "Sven", 7.1)) # not OK
         sprintf("%s is %i feet tall\n", "Sven", 7  )  # OK

     ## use a literal % :

     sprintf("%.0f%% said yes (out of a sample of size %.0f)", 66.666, 3)

     ## various formats of pi :

     sprintf("%f", pi)
     sprintf("%.3f", pi)
     sprintf("%1.0f", pi)
     sprintf("%5.1f", pi)
     sprintf("%05.1f", pi)
     sprintf("%+f", pi)
     sprintf("% f", pi)
     sprintf("%-10f", pi) # left justified
     sprintf("%e", pi)
     sprintf("%E", pi)
     sprintf("%g", pi)
     sprintf("%g",   1e6 * pi) # -> exponential
     sprintf("%.9g", 1e6 * pi) # -> "fixed"
     sprintf("%G", 1e-6 * pi)

     ## no truncation:
     sprintf("%1.f",101)

     ## re-use one argument three times, show difference between %x and %X
     xx <- sprintf("%1$d %1$x %1$X", 0:15)
     xx <- matrix(xx, dimnames=list(rep("", 16), "%d%x%X"))
     noquote(format(xx, justify="right"))

     ## More sophisticated:

     sprintf("min 10-char string '%10s'",
             c("a", "ABC", "and an even longer one"))

     n <- 1:18
     sprintf(paste("e with %2d digits = %.",n,"g",sep=""), n, exp(1))

     ## Using arguments out of order
     sprintf("second %2$1.0f, first %1$5.2f, third %3$1.0f", pi, 2, 3)

     ## Using asterisk for width or precision
     sprintf("precision %.*f, width '%*.3f'", 3, pi, 8, pi)

     ## Asterisk and argument re-use, 'e' example reiterated:
     sprintf("e with %1$2d digits = %2$.*1$g", n, exp(1))

     ## re-cycle arguments
     sprintf("%s %d", "test", 1:3)

     ## binary output showing rounding/representation errors
     x <- seq(0, 1.0, 0.1); y <- c(0,.1,.2,.3,.4,.5,.6,.7,.8,.9,1)
     cbind(x, sprintf("%a", x), sprintf("%a", y))