Formatted Output:Print Formats, Print Functions, Print Conversion Specifiers

<< Formatted Input:Scan Formats, Scan Functions, Scan Conversion Specifiers

STL Conventions:Iterator Conventions, Algorithm Conventions >>

Chapter 8. Formatted Output

Print Formats (page 31) · Print Functions (page 32) · Print Conversion Specifiers

(page 33)

Several library functions help you convert data values from encoded internal

representations to text sequences that are generally readable by people. You

provide a format string (page 31) as the value of the format argument to each of

these functions, hence the term formatted output. The functions fall into two

categories.

The byte print functions (declared in <stdio.h>) convert internal representations to

sequences of type char, and help you compose such sequences for display: fprintf,

printf, sprintf, vfprintf, vprintf, and vsprintf. For these function, a format

string is a multibyte string that begins and ends in the initial shift state (page 12).

The wide print functions (declared in <wchar.h> and hence added with

Amendment 1) convert internal representations to sequences of type wchar_t, and

help you compose such sequences for display: fwprintf, swprintf, wprintf,

vfwprintf, vswprintf, and vwprintf. For these functions, a format string is a

wide-character string. In the descriptions that follow, a wide character wc from a

format string or a stream is compared to a specific (byte) character c as if by

evaluating the expression wctob(wc) == c.

Print Formats

A format string has the same syntax for both the print functions and the scan

functions (page 25), as shown in the diagram.

A format string consists of zero or more conversion specifications interspersed

with literal text and white space. White space is a sequence of one or more

characters c for which the call isspace(c) returns nonzero. (The characters defined

as white space can change when you change the LC_CTYPE locale category.) For

the print functions, a conversion specification is one of the print conversion

specifications (page 32) described below.

A print function scans the format string once from beginning to end to determine

what conversions to perform. Every print function accepts a varying number of

arguments, either directly or under control of an argument of type va_list. Some

print conversion specifications in the format string use the next argument in the

list. A print function uses each successive argument no more than once. Trailing

arguments can be left unused.

In the description that follows:

v integer conversions are the conversion specifiers that end in d, i, o, u, x, or X

v floating-point conversions are the conversion specifiers that end in e, E, f, g, or

Print Functions

For the print functions, literal text or white space (page 31) in a format string

generates characters that match the characters in the format string. A print

conversion specification typically generates characters by converting the next

argument value to a corresponding text sequence. A print conversion specification

has the format:

Following the percent character (%) in the format string, you can write zero or

more format flags:

v - -- to left-justify a conversion

v + -- to generate a plus sign for signed values that are positive

v space -- to generate a space for signed values that have neither a plus nor a

minus sign

v # -- to prefix 0 on an o conversion, to prefix 0x on an x conversion, to prefix 0X

on an X conversion, or to generate a decimal point and fraction digits that are

otherwise suppressed on a floating-point conversion

v 0 -- to pad a conversion with leading zeros after any sign or prefix, in the

absence of a minus (-) format flag or a specified precision

Following any format flags, you can write a field width that specifies the

minimum number of characters to generate for the conversion. Unless altered by a

format flag, the default behavior is to pad a short conversion on the left with space

characters. If you write an asterisk (*) instead of a decimal number for a field

width, then a print function takes the value of the next argument (which must be

of type int) as the field width. If the argument value is negative, it supplies a -

format flag and its magnitude is the field width.

Following any field width, you can write a dot (.) followed by a precision that

specifies one of the following: the minimum number of digits to generate on an

integer conversion; the number of fraction digits to generate on an e, E, or f

conversion; the maximum number of significant digits to generate on a g or G

conversion; or the maximum number of characters to generate from a C string on

an s conversion.

If you write an * instead of a decimal number for a precision, a print function

takes the value of the next argument (which must be of type int) as the precision.

If the argument value is negative, the default precision applies. If you do not write

either an * or a decimal number following the dot, the precision is zero.

Standard C++ Library

Print Conversion Specifiers

Following any precision (page 32), you must write a one-character print

conversion specifier, possibly preceded by a one-character qualifier. Each

combination determines the type required of the next argument (if any) and how

the library functions alter the argument value before converting it to a text

sequence. The integer (page 32) and floating-point conversions (page 32) also

determine what base to use for the text representation. If a conversion specifier

requires a precision p and you do not provide one in the format, then the

conversion specifier chooses a default value for the precision. The following table

lists all defined combinations and their properties.

Conversion

Argument

Converted

Default Pre-

Specifier

Type

Value

Base cision

int x

(unsigned char)x

%lc

wint_t x

wchar_t a[2] = {x}

int x

(int)x

%hd

int x

(short)x

%ld

long x

(long)x

double x

(double)x

%Le

long double

(long double)x

double x

(double)x

%LE

long double

(long double)x

double x

(double)x

%Lf

long double

(long double)x

double x

(double)x

%Lg

long double

(long double)x

double x

(double)x

%LG

long double

(long double)x

int x

(int)x

%hi

int x

(short)x

%li

long x

(long)x

int *x

%hn

short *x

%ln

long *x

int x

(unsigned

int)x

%ho

int x

(unsigned

short)x

%lo

long x

(unsigned

long)x

void *x

(void *)x

char x[]

x[0]...

large

%ls

wchar_t x[]

x[0]...

large

int x

(unsigned

int)x

%hu

int x

(unsigned

short)x

%lu

long x

(unsigned

long)x

int x

(unsigned

int)x

%hx

int x

(unsigned

short)x

%lx

long x

(unsigned

long)x

int x

(unsigned

int)x

%hX

int x

(unsigned

short)x

%lX

long x

(unsigned

long)x

none

'%'

The print conversion specifier determines any behavior not summarized in this

table. In the following descriptions, p is the precision. Examples follow each of the

print conversion specifiers. A single conversion can generate up to 509 characters.

You write %c to generate a single character from the converted value.

printf("%c", 'a')

generates a

printf("<%3c|%-3c>", 'a', 'b') generates <

a|b

For a wide stream (page 18), conversion of the character x occurs as if by calling

btowc(x).

wprintf(L"%c", 'a')

generates btowc(a)

Chapter 8. Formatted Output

You write %lc to generate a single character from the converted value. Conversion

of the character x occurs as if it is followed by a null character in an array of two

elements of type wchar_t converted by the conversion specification ls (page 35).

printf("%lc", L'a')

generates a

wprintf(L"lc", L'a')

generates L'a'

You write %d, %i, %o, %u, %x, or %X to generate a possibly signed integer

representation. %d or %i specifies signed decimal representation, %o unsigned octal,

%u unsigned decimal, %x unsigned hexadecimal using the digits 0-9 and a-f, and

%X unsigned hexadecimal using the digits 0-9 and A-F. The conversion generates at

least p digits to represent the converted value. If p is zero, a converted value of

zero generates no digits.

printf("%d %o %x", 31, 31, 31) generates 31 37 1f

printf("%hu", 0xffff)

generates 65535

printf("%#X %+d", 31, 31)

generates 0X1F +31

You write %e or %E to generate a signed fractional representation with an

exponent. The generated text takes the form ±d.dddE±dd, where ± is either a plus

or minus sign, d is a decimal digit, the dot (.) is the decimal point for the current

locale, and E is either e (for %e conversion) or E (for %E conversion). The generated

text has one integer digit, a decimal point if p is nonzero or if you specify the #

format flag, p fraction digits, and at least two exponent digits. The result is

rounded. The value zero has a zero exponent.

printf("%e", 31.4)

generates 3.140000e+01

printf("%.2E", 31.4)

generates 3.14E+01

You write %f to generate a signed fractional representation with no exponent. The

generated text takes the form ±d.ddd, where ± is either a plus or minus sign, d is a

decimal digit, and the dot (.) is the decimal point for the current locale. The

generated text has at least one integer digit, a decimal point if p is nonzero or if

you specify the # format flag, and p fraction digits. The result is rounded.

printf("%f", 31.4)

generates 31.400000

printf("%.0f %#.0f", 31.0, 31.0)generates 31 31.

You write %g or %G to generate a signed fractional representation with or without

an exponent, as appropriate. For %g conversion, the generated text takes the same

form as either %e or %f conversion. For %G conversion, it takes the same form as

either %E or %f conversion. The precision p specifies the number of significant digits

generated. (If p is zero, it is changed to 1.) If %e conversion would yield an

exponent in the range [-4, p), then %f conversion occurs instead. The generated text

has no trailing zeros in any fraction and has a decimal point only if there are

nonzero fraction digits, unless you specify the # format flag.

printf("%.6g", 31.4)

generates 31.4

printf("%.1g", 31.4)

generates 3.14e+01

You write %n to store the number of characters generated (up to this point in the

format) in the object of type int whose address is the value of the next successive

argument.

printf("abc%n", &x)

stores 3

You write %p to generate an external representation of a pointer to void. The

conversion is implementation defined.

printf("%p", (void *)&x)

generates, e.g. F4C0

You write %s to generate a sequence of characters from the values stored in the

argument C string.

Standard C++ Library

printf("%s", "hello")

generates hello

printf("%.2s", "hello")

generates he

For a wide stream (page 18), conversion occurs as if by repeatedly calling mbrtowc,

beginning in the initial conversion state (page 12). The conversion generates no

more than p characters, up to but not including the terminating null character.

wprintf(L"%s", "hello")

generates hello

You write %ls to generate a sequence of characters from the values stored in the

argument wide-character string. For a byte stream (page 18), conversion occurs as

if by repeatedly calling wcrtomb, beginning in the initial conversion state (page 12),

so long as complete multibyte characters can be generated. The conversion

generates no more than p characters, up to but not including the terminating null

character.

printf("%ls", L"hello")

generates hello

wprintf(L"%.2s", L"hello")

generates he

You write %% to generate the percent character (%).

printf("%%")

generates %

Chapter 8. Formatted Output

Standard C++ Library

Table of Contents: