Next: Character Type, Previous: String manipulation, Up: Library [Contents][Index]
The function sprintf formats its argument according to
format (see below) and returns the resulting string. It takes
varying number of parameters, the only mandatory one being
format.
The format string is a simplified version of the format argument to
C printf-family functions.
The format string is composed of zero or more directives: ordinary characters (not ‘%’), which are copied unchanged to the output stream; and conversion specifications, each of which results in fetching zero or more subsequent arguments. Each conversion specification is introduced by the character ‘%’, and ends with a conversion specifier. In between there may be (in this order) zero or more flags, an optional minimum field width, and an optional precision.
Notice, that in practice that means that you should use single quotes with the format arguments, to protect conversion specifications from being recognized as variable references (see singe-vs-double).
No type conversion is done on arguments, so it is important that the
supplied arguments match their corresponding conversion specifiers.
By default, the arguments are used in the order given, where each
‘*’ and each conversion specifier asks for the next argument. If
insufficiently many arguments are given, sprintf raises
‘e_range’ exception. One can also specify explicitly which
argument is taken, at each place where an argument is required, by
writing ‘%m$’, instead of ‘%’ and ‘*m$’
instead of ‘*’, where the decimal integer m denotes the
position in the argument list of the desired argument, indexed
starting from 1. Thus,
sprintf('%*d', width, num);
and
sprintf('%2$*1$d', width, num);
are equivalent. The second style allows repeated references to the same argument.
The character ‘%’ is followed by zero or more of the following flags:
The value should be converted to an alternate form. For ‘o’ conversions, the first character of the output string is made zero (by prefixing a ‘0’ if it was not zero already). For ‘x’ and ‘X’ conversions, a non-zero result has the string ‘0x’ (or ‘0X’ for ‘X’ conversions) prepended to it. Other conversions are not affected by this flag.
The value should be zero padded. For ‘d’, ‘i’, ‘o’, ‘u’, ‘x’, and ‘X’ conversions, the converted value is padded on the left with zeros rather than blanks. If the ‘0’ and ‘-’ flags both appear, the ‘0’ flag is ignored. If a precision is given, the ‘0’ flag is ignored. Other conversions are not affected by this flag.
The converted value is to be left adjusted on the field boundary. (The default is right justification.) The converted value is padded on the right with blanks, rather than on the left with blanks or zeros. A ‘-’ overrides a ‘0’ if both are given.
A blank should be left before a positive number (or empty string) produced by a signed conversion.
A sign (‘+’ or ‘-’) always be placed before a number produced by a signed conversion. By default a sign is used only for negative numbers. A ‘+’ overrides a space if both are used.
An optional decimal digit string (with nonzero first digit) specifying a minimum field width. If the converted value has fewer characters than the field width, it will be padded with spaces on the left (or right, if the left-adjustment flag has been given). Instead of a decimal digit string one may write ‘*’ or ‘*m$’ (for some decimal integer m) to specify that the field width is given in the next argument, or in the m-th argument, respectively, which must be of numeric type. A negative field width is taken as a ‘-’ flag followed by a positive field width. In no case does a non-existent or small field width cause truncation of a field; if the result of a conversion is wider than the field width, the field is expanded to contain the conversion result.
An optional precision, in the form of a period (‘.’) followed by an optional decimal digit string. Instead of a decimal digit string one may write ‘*’ or ‘*m$’ (for some decimal integer m) to specify that the precision is given in the next argument, or in the m-th argument, respectively, which must be of numeric type. If the precision is given as just ‘.’, or the precision is negative, the precision is taken to be zero. This gives the minimum number of digits to appear for ‘d’, ‘i’, ‘o’, ‘u’, ‘x’, and ‘X’ conversions, or the maximum number of characters to be printed from a string for the ‘s’ conversion.
A character that specifies the type of conversion to be applied. The conversion specifiers and their meanings are:
The numeric argument is converted to signed decimal notation. The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is padded on the left with zeros. The default precision is ‘1’. When ‘0’ is printed with an explicit precision ‘0’, the output is empty.
The numeric argument is converted to unsigned octal (‘o’), unsigned decimal (‘u’), or unsigned hexadecimal (‘x’ and ‘X’) notation. The letters ‘abcdef’ are used for ‘x’ conversions; the letters ‘ABCDEF’ are used for ‘X’ conversions. The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is padded on the left with zeros. The default precision is ‘1’. When ‘0’ is printed with an explicit precision 0, the output is empty.
The string argument is written to the output. If a precision is specified, no more than the number specified of characters are written.
A ‘%’ is written. No argument is converted. The complete conversion specification is ‘%%’.
Next: Character Type, Previous: String manipulation, Up: Library [Contents][Index]