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 of length one containing a formatted combination of text
     and variable values.

_U_s_a_g_e:

     sprintf(fmt, ...)

_A_r_g_u_m_e_n_t_s:

     fmt: a format string

     ...: values to be passed into `fmt'

_D_e_t_a_i_l_s:

     This is just a wrapper for the system's C call.  No attempt is
     made to check that the mode of the values passed match the format
     supplied, and R's special values (`NA', `Inf', `-Inf' and on most
     platforms `NaN') are unlikely to be handled correctly.

     The following is abstracted from K&R (see References, below).  The
     string `fmt' contains normal characters, which are passed through
     to the output string, and also special characters that operate on
     the arguments provided through `...'.  Special characters start
     with a `%' and terminate with one of the letters in the set
     `difeEgGs%'.  These letters denote the following types:

     `_d,_i' Integer value

     `_f' Double precision value, in decimal notation of the form
          "[-]mmm.ddd".  The number of decimal places is specified by
          the precision: the default is 6; a precision of 0 suppresses
          the decimal point.

     `_e,_E' Double precision value, in 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

     `_s' Character string

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

     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

     _a _s_p_a_c_e Prefix a space if the first number is not a sign

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

     Note that the arguments are simply passed through to `sprintf',
     and so any formatting errors, e.g. passing a float to the
     conversion character `i', are replicated in the resulting string. 
     See the examples for an illustration.

_V_a_l_u_e:

     A character vector of length one.

_A_u_t_h_o_r(_s):

     Jonathan Rougier, J.C.Rougier@durham.ac.uk

_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 but with more error-checking and with handling of special
     values.

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

_E_x_a_m_p_l_e_s:

     ## be careful with the format: most things in R are floats

     sprintf("%s is %f feet tall\n", "Sven", 7) # OK
     sprintf("%s is %i feet tall\n", "Sven", 7) # not OK
     sprintf("%s is %i feet tall\n", "Sven", as.integer(7)) # OK again

     ## 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)

     ## More sophisticated:

     lapply(c("a", "ABC", "and an even longer one"),
            function(ch) sprintf("10-string `%10s'", ch))

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

