12.4 Wide-Character Print Format Control Strings

The fwprintf, swprintf, wprintf, and other wide-character print functions use a format control string that consists of the following:

Each conversion specification begins with the % wide character or with the wide-character sequence of %n$. This character sequence is used to reorder the arguments.

The beginning is followed, in sequence, by the following:

  1. Zero or more format control flags, which can modify the meaning of the conversion specification. See Format Control Flags

  2. An optional field width, which specifies the minimum width of the field. See Field Width.

  3. An optional precision specifier, which specifies the number of digits to print. See Precision Specifier.

  4. An optional length modifier, which specifies the size of the argument. See Length Modifiers.

  5. A conversion specifier, which indicates the type of conversion to perform. This specifier is required. For a list, see Conversion Specifiers.

12.4.1 Format Control Flags

The following table describes the valid format control flags, all of which are optional.

' <single quote>

The integer portion of the result of a decimal conversion ( %i , %d , %u , %f , %F , %g , or %G ) is formatted with thousands' grouping wide characters. The numeric grouping wide character is used.

- <hyphen>

The result of the conversion is left-justified within the field; the results are right-justified when this flag is not specified.

+

The result of a signed conversion is always prepended with a sign (+ or -). If this flag is not specified, the conversion begins with a sign only when a negative value is converted.

<space>

If the first wide character of a signed conversion is not a sign, or if a signed conversion results in no wide characters, a <space> is prefixed to the result. If the <space> and + flags both appear, the <space> flag is ignored.

#

An alternate conversion form is used:

  • For o (unsigned octal) conversion specifier, the precision is incremented so that the first digit is zero.

  • For x or X (unsigned hexadecimal) conversion specifier, a nonzero value is prepended with 0x or 0X, respectively.

  • For b or B (binary) conversion specifier, the value is prepended with 0b or 0B, respectively.

  • For a, A, e, E, f, F, g, or G (any floating point) conversion specifier, the result always contains a decimal-point (radix) character, even if no digits follow it; normally, a decimal-point character appears in the result only if there is a digit to follow it. For g and G conversion specifiers, trailing zeros are not removed from the result.

0

For d, i, o, u, x, X, a, A, b, B, e, E, f, F, g, or G conversion specifier, leading zeros (following any indication of sign or base) are used to pad to the field width; no space padding is performed.

If the 0 and - flags both appear, the 0 flag is ignored.

For d, i, o, u, x, and X conversion specifiers, if a precision is specified, the 0 flag is ignored.

If the 0 and ' flags both appear, the grouping wide characters are inserted before zero padding.

12.4.2 Field Width

The field width specifier is optional. If the converted value has fewer wide characters than the specified field width, it is padded with spaces by default on the left; it is padded on the right, if the left-adjustment control flag ( - ) is given to the field width. The field width takes the form of an asterisk ( * ) or a decimal integer.

12.4.3 Precision Specifier

The precision specifier is optional and controls the number of digits printed for the following conversion specifiers:

  • For the d, i, o, u, x, and X conversion specifiers, indicates the minimum number of digits to appear.

  • For the a, A, e, E, f, and F conversion specifiers, indicates the number of digits to appear after the radix character.

  • For the g and G conversion specifiers, indicates the maximum number of significant digits.

  • For a string in the s conversion specifier, indicates the maximum number of wide characters to print.

The precision takes the form of a period character (.) followed either by an asterisk character (*) or by an optional decimal digit string where a NULL digit string is treated as 0.

12.4.4 Length Modifiers

The following table describes the length modifiers, all of which are optional.

h

For the b, B, d, i, o, u, x, or X conversion specifier, applies a short or unsigned short to the argument.

For an n (converted length assignment) operation, assigns the converted length to an object of type short.

hh

For the b, B, d, i, o, u, x, or X conversion specifier, treats the argument as a signed char or unsigned char.

For an n (converted length assignment) operation, assigns the converted length to an object of type signed char.

j

For the b, B, d, i, o, u, x, or X conversion specifier, applies a intmax_t or uintmax_t to the argument.

For an n (converted length assignment) operation, assigns the converted length to an object of type intmax_t.

l (ell)

For the b, B, d, i, o, u, x, or X conversion specifier, applies a long int or unsigned long int to the argument.

For an n (converted length assignment) operation, assigns the converted length to an object of type unsigned long int.

ll (ell-ell)

For the b, B, d, i, o, u, x, or X conversion specifier, applies a long long or unsigned long long to the argument.

For an n (converted length assignment) operation, assigns the converted length to an object of type long long.

L

For the a, A, e, E, f, F, g, or G conversion specifier, applies a long double to the argument.

t

For the b, B, d, i, o, u, x, or X conversion specifier, applies a ptrdiff_t or the corresponding unsigned type to the argument.

For an n (converted length assignment) operation, assigns the converted length to an object of type ptrdiff_t.

z

For the b, B, d, i, o, u, x, or X conversion specifier, applies a size_t or the corresponding signed integer type to the argument.

For an n (converted length assignment) operation, assigns the converted length to an object of type size_t.

12.4.5 Conversion Specifiers

The following table describes the valid conversion specifiers:

a, A

An argument of type double is converted to a floating point number in the form [-]0xh.hhhhpd, where there is one hexadecimal digit (which is nonzero if the argument is a normalized floating-point number and is otherwise unspecified) before the decimal-point wide character and the number of hexadecimal digits after it is equal to the precision.

  • If the precision is missing and FLT_RADIX is a power of 2, the precision is made sufficient for an exact representation of the value.

  • If the precision is missing and FLT_RADIX is not a power of 2, the precision is made sufficient to distinguish values of type double, except that trailing zeros are omitted.

  • If the precision is zero and the # flag is not specified, no decimal-point wide character appears.

The letters "abcdef" are used for the "a" conversion specifier and the letters "ABCDEF" for the "A" conversion specifier. The "A" conversion specifier produces a number with "X" and "P" instead of "x" and "p". The exponent always contains at least one digit, and only as many more digits as necessary to represent the decimal exponent of 2. If the value is zero, the exponent is zero.

b, B

An argument of type int or unsigned is converted to binary.

c

If no l (ell) qualifier is present, an argument of type int is converted to a wide character, and the resulting wide character is written. Otherwise, the wint_t argument is converted to wchar_t and written.

C

Equivalent to the lc conversion specifier.

d, i

An argument of type int is converted to a signed decimal in the form [-]dddd and written to the output stream. The precision specifies the minimum number of digits. If the value can be represented in fewer digits, leading zeros are added.The default precision is 1.

e, E

An argument of type double is converted to a decimal notation in the form [-]d.ddde[+|-]dd. The leading sign appears (subject to the format control flags) only if the argument is negative. If the argument is nonzero, the digit before the decimal point character is nonzero. The precision is used as the number of digits following the decimal point character.

  • If the precision is not specified, a default precision of 6 is used.

  • If the precision is zero and no # flag is present, the decimal point character is suppressed. The value is rounded to the appropriate number.

For E conversions, the exponent begins with the character E rather than e. The exponent always contains a two-digit number.

f , F

An argument of type double is converted to a decimal notation in the form [-]ddd.ddd. The leading sign appears (subject to the format control flags) only if the argument is negative.

The precision specification controls the number of digits following the decimal point character. If the precision is not specified, a default precision of 6 is used. If the precision is zero and no # flag is present, the decimal point character is suppressed. Otherwise, at least one digit is produced before the decimal-point character. The value is rounded to the appropriate number.

g, G

An argument of type double is converted using the f or e style of conversion depending on the value of the argument (F or E if G is specified). In either case, the precision specifies the number of significant digits that are contained in the result. The e style conversion is used only if the exponent from such a conversion would be less than -4 or greater than the precision. Trailing zeros are removed from the result, and a decimal-point character only appears if it is followed by a digit.

n

The number of wide characters that have been written to the output stream is assigned to the integer pointed to by the argument. No output is produced.

o

An argument of type unsigned is converted to an unsigned octal format in the form dddd and written to the output stream. The precision specifies the minimum number of digits. If the value can be represented in fewer digits, leading zeros are added.The default precision is 1.

p, P

An argument of type void * is converted to a value of type int and the value is formatted as for a hexadecimal x conversion for p and a hexadecimal X conversion for P.

s

If no l (ell) qualifier is present, the argument is a pointer to a character array containing a character sequence beginning in the initial shift state. Characters from the array are converted, with the conversion state described by an mbstate_t object initialized to zero before the first character is converted, and written up to (but not including) the null-terminating wide character.

  • If the precision is specified, no more than that many wide characters are written.

  • If the precision is not specified, or is greater than the size of the array, a null-terminating wide character is written.

If an l (ell) qualifier is present, the argument is a pointer to an array of type wchar_t. Wide characters from the array are written up to (but not including) a terminating null-terminating wide character.

  • If no precision is specified, or is greater than the size of the array, a null-terminating wide character is written.

  • If a precision is specified, no more than that many wide characters are written.

S

Nonstandard conversion. The argument is a pointer to an array of character type with a preceding length specifier. No special provisions are made for multibyte characters. Characters from the array are written up to the indicated length.

If precision is specified, no more than that many characters are written.

U

Equivalent to the ls conversion specifier.

u

An argument of type int is converted to an unsigned decimal notation and written to the output stream. The precision specifies the minimum number of digits. If the value can be represented in fewer digits, leading zeros are added.The default precision is 1.

x, X

An argument of type unsigned is converted to an unsigned hexadecimal notation and written to the output stream. The default precision is 1, but if more digits are required, leading zeros are added.

Hexadecimal notation uses digits (0 through 9) and characters (a through f or A through F) for x or X conversions respectively. Subject to the alternate-form control flag, 0x or 0X is affixed to the output

%

A % wide character is written to the output stream. No arguments are converted. The entire conversion specification is %%.

The arguments must correspond with the conversion type specifiers, left to right in the string; otherwise, indeterminate results occur.