printf
From Cppwiki
The printf family of functions are standard C library functions that allow for the formatting of strings to a variety of destinations.
- #include <cstdio>
- namespace std {
- int printf(char const * format [, ARG ...]);
- int fprintf(FILE * file, char const * format [, ARG ...]);
- int sprintf(char * buffer, char const * format [, ARG ...]);
- int snprintf(char * buffer, size_t count, char const * format [, ARG ...]);
- }
Some libraries may also support the additional non-standard function:
- int asprintf(char ** buffer_ptr, char const * format [, ARG ...]);
Libraries may also support wchar_t forms of these functions under names wprintf,fwprintf,swprintf and snwprintf.
Contents |
Description
Each of the functions in the 'printf' family serves a different though similar purpose. The 'printf' function formats text to stdout, 'fprint' formats to the given FILE*, 'sprintf' formats to a buffer passed to the function. 'snprintf' does the same with a buffer size passed in addition to the other parameters. The 'asprintf' function allocates a buffer for the formatted text. Each of these functions returns the number of characters formatted.
Format field
Every function in the printf family accepts a format parameter. This parameter is a string which controls what text will be sent to the destination. The format field consists of plain text and inserts denoted by special strings beginning with the '%' character.
Inserts format
Each insert has the following syntax:
%[FLAGS][WIDTH][.PRECISION]TYPE
As denoted, all parts other than the '%' and a type are optional.
Flags
'-' The result of the conversion will be left justified.
'+' The result of a signed conversion (as determined by TYPE)
will always have either a '+' or '-'. If this flag is not
used, positive values will not show a leading '+'.
'0' If TYPE is 'd', 'i', 'o', 'u', 'x', 'X', 'e', 'E', 'f', 'g'
or 'G', leading zeros are used to pad the field width
following any indication of sign or base.
Width / Precision
WIDTH and PRECISION are both optional fields that combine to determine how much data is formatted to the destination. WIDTH specifies a minimum field width, while PRECISION specifies both the number of significant digits to format in the case of an integral TYPE and the number of digits to print to the right of the decimal point in the case of a floating point TYPE. Both WIDTH and PRECISION may appear directly in the format string as positive integral values, or the '*' character may be used instead, in which case the value of the field is taken as an 'int' from the argument list.
Size
The SIZE field overrides the size of the argument as would normally be chosen based on TYPE. Due to promotion rules it is not usually needed when the argument is of a size less than or equal to 'int', but is often needed to correctly format types larger than 'int'. Some SIZE values are as follows:
'h' Treat the argument as a 'short'.
'I' Treat the argument as an 'int'
'L' Treat the argument as a 'long'
Library documentation should be consulted for other values of SIZE that are accepted.
Type
TYPE is a non-optional field. It tells the function what type of argument to take from the list and what format to print it in.
'%' Format a '%' character to the destination.
'c' Format a single character.
'C' Formats a wchar_t as a single multi-byte character.
's' Formats characters from a until PRECISION is reached or
a NUL terminator is found.
'S' Converts wchar_t characters to multi-byte output characters.
Like 's', stop formatting when either PRECISION characters
have been formatted, or a NUL terminator is encountered.
'd' Format a signed decimal integer.
Takes an int.
'i' Format a signed decimal integer. (same as 'd')
Takes an int.
'u' Format an unsigned decimal integer.
Takes an int.
'x' Format an unsigned hexadecimal integer. Uses lowercase
hex letters (abcdef and 0x). Takes an int.
'X' Format an unsigned hexadecimal integer. Used uppercase
hex letters (ABCDEF and 0X). Takes an int.
'f' Format a signed value in the format "[-]9999.9999"
Takes a floating point number.
'e' Format a signed value in the format "[-]9.99999e[+|-]9999"
Takes a floating point number.
'E' Same as 'e', except uses an uppercase 'E' to introduce
the exponent.
'g' Format a signed value in the format of either 'f' or 'e'
based on the passed value and PRECISION.
'G' Format a signed value in the format of either 'f' or 'E'
based on the passed value and PRECISION.
'n' Stores a count of the number of characters formatted so far.
Takes a pointer to int.
'p' Format a pointer in an implementation defined manner.
Note that if the library supports wchar_t versions of the 'printf' functions then the meanins of the 'c', 'C', 's' and 'S' TYPE specifiers are reversed for those functions. 'c' and 's' will format wchar_t chars and strings in that case, while 'C' and 'S' will format char values and char strings, respectively.
See also
See library documentation for format specifiers that may be supported in addition to those listed above.
