You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 412e2d8
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md
+15-15Lines changed: 15 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,12 @@
1
1
---
2
2
title: "Format Specification Syntax: printf and wprintf Functions"
3
-
ms.date: "07/02/2019"
3
+
ms.date: "07/30/2019"
4
4
helpviewer_keywords: ["format specification fields for printf function", "printf function format specification fields", "flag directives, printf function", "type fields, printf function", "width fields, printf function", "precision fields, printf function"]
5
5
ms.assetid: 664b1717-2760-4c61-bd9c-22eee618d825
6
6
---
7
7
# Format specification syntax: printf and wprintf functions
8
8
9
-
The various `printf` and `wprintf` functions take a format string and optional arguments and produce a formatted sequence of characters for output. The format string contains zero or more *directives*, which are either literal characters for output or encoded *conversion specifications* that describe how to format an argument in the output. This topic describes the syntax used to encode conversion specifications in the format string. For a listing of these functions, see [Stream I/O](../c-runtime-library/stream-i-o.md).
9
+
The various `printf` and `wprintf` functions take a format string and optional arguments and produce a formatted sequence of characters for output. The format string contains zero or more *directives*, which are either literal characters for output or encoded *conversion specifications* that describe how to format an argument in the output. This article describes the syntax used to encode conversion specifications in the format string. For a listing of these functions, see [Stream I/O](../c-runtime-library/stream-i-o.md).
10
10
11
11
A conversion specification consists of optional and required fields in this form:
12
12
@@ -51,15 +51,15 @@ Integer types such as `short`, `int`, `long`, `long long`, and their `unsigned`
|**e**|Floating-point|Signed value that has the form [-]*d.dddd*__e±__*dd*[*d*] where *d* is one decimal digit, *dddd* is one or more decimal digits depending on the specified precision, or six by default, and *dd*[*d*] is two or three decimal digits depending on the [output format](../c-runtime-library/set-output-format.md) and size of the exponent.|
54
+
|**e**|Floating-point|Signed value that has the form [-]*d.dddd*__e±__*dd*\[*d*], where *d* is one decimal digit, *dddd* is one or more decimal digits depending on the specified precision, or six by default, and *dd*\[*d*] is two or three decimal digits depending on the [output format](../c-runtime-library/set-output-format.md) and size of the exponent.|
55
55
|**E**|Floating-point|Identical to the **e** format except that **E** rather than **e** introduces the exponent.|
56
56
|**f**|Floating-point|Signed value that has the form [-]*dddd*__.__*dddd*, where *dddd* is one or more decimal digits. The number of digits before the decimal point depends on the magnitude of the number, and the number of digits after the decimal point depends on the requested precision, or six by default.|
57
57
|**F**|Floating-point|Identical to the **f** format except that infinity and nan output is capitalized.|
58
58
|**g**|Floating-point|Signed values are displayed in **f** or **e** format, whichever is more compact for the given value and precision. The **e** format is used only when the exponent of the value is less than -4 or greater than or equal to the *precision* argument. Trailing zeros are truncated, and the decimal point appears only if one or more digits follow it.|
59
59
|**G**|Floating-point|Identical to the **g** format, except that **E**, rather than **e**, introduces the exponent (where appropriate).|
60
60
|**a**|Floating-point|Signed hexadecimal double-precision floating-point value that has the form [-]0x*h.hhhh*__p±__*dd*, where *h.hhhh* are the hex digits (using lower case letters) of the mantissa, and *dd* are one or more digits for the exponent. The precision specifies the number of digits after the point.|
61
61
|**A**|Floating-point|Signed hexadecimal double-precision floating-point value that has the form [-]0X*h.hhhh*__P±__*dd*, where *h.hhhh* are the hex digits (using capital letters) of the mantissa, and *dd* are one or more digits for the exponent. The precision specifies the number of digits after the point.|
62
-
|**n**|Pointer to integer|Number of characters that are successfully written so far to the stream or buffer. This value is stored in the integer whose address is given as the argument. The size of the integer pointed to can be controlled by an argument size specification prefix. The **n** specifier is disabled by default; for information see the important security note.|
62
+
|**n**|Pointer to integer|Number of characters that are successfully written so far to the stream or buffer. This value is stored in the integer whose address is given as the argument. The size of the integer pointed at can be controlled by an argument size specification prefix. The **n** specifier is disabled by default; for information see the important security note.|
63
63
|**p**|Pointer type|Displays the argument as an address in hexadecimal digits.|
64
64
|**s**|String|When used with `printf` functions, specifies a single-byte or multi-byte character string; when used with `wprintf` functions, specifies a wide-character string. Characters are displayed up to the first null character or until the *precision* value is reached.|
65
65
|**S**|String|When used with `printf` functions, specifies a wide-character string; when used with `wprintf` functions, specifies a single-byte or multi-byte character string. Characters are displayed up to the first null character or until the *precision* value is reached.|
@@ -71,10 +71,10 @@ Starting in Visual Studio 2015, if the argument that corresponds to a floating-p
71
71
|-----------|------------|
72
72
|infinity|`inf`|
73
73
|Quiet NaN|`nan`|
74
-
|Signalling NaN|`nan(snan)`|
74
+
|Signaling NaN|`nan(snan)`|
75
75
|Indefinite NaN|`nan(ind)`|
76
76
77
-
Any of these values may be prefixed by a sign. If a floating-point *type* conversion specifier character is a capital letter, then the output is also formatted in capital letters. For example, if the format specifier is `%F` instead of `%f`, an infinity is formatted as `INF` instead of `inf`. The `scanf` functions can also parse these strings, so these values can make a round-trip through `printf` and `scanf` functions.
77
+
Any of these values may be prefixed by a sign. If a floating-point *type* conversion specifier character is a capital letter, then the output is also formatted in capital letters. For example, if the format specifier is `%F` instead of `%f`, an infinity is formatted as `INF` instead of `inf`. The `scanf` functions can also parse these strings, so these values can make a roundtrip through `printf` and `scanf` functions.
78
78
79
79
Before Visual Studio 2015, the CRT used a different, non-standard format for output of infinite, indefinite, and NaN values:
80
80
@@ -85,7 +85,7 @@ Before Visual Studio 2015, the CRT used a different, non-standard format for out
85
85
|Indefinite (same as quiet NaN)|*digit*`.#IND`*random-digits*|
86
86
|NaN|*digit*`.#NAN`*random-digits*|
87
87
88
-
Any of these may have been prefixed by a sign, and may have been formatted slightly differently depending on field width and precision, sometimes with unusual effects. For example, `printf("%.2f\n", INFINITY)` would print `1.#J` because the #INF would be "rounded" to a precision of 2 digits.
88
+
Any of these may have been prefixed by a sign, and may have been formatted slightly differently depending on field width and precision, sometimes with unusual effects. For example, `printf("%.2f\n", INFINITY)` would print `1.#J` because the #INF would be "rounded" to 2 digits of precision.
89
89
90
90
> [!NOTE]
91
91
> If the argument that corresponds to `%s` or `%S`, or the `Buffer` field of the argument that corresponds to `%Z`, is a null pointer, "(null)" is displayed.
@@ -111,7 +111,7 @@ The first optional field in a conversion specification contains *flag directives
111
111
|**0**|If *width* is prefixed by **0**, leading zeros are added until the minimum width is reached. If both **0** and **-** appear, the **0** is ignored. If **0** is specified for an integer format (**i**, **u**, **x**, **X**, **o**, **d**) and a precision specification is also present—for example, `%04.d`—the **0** is ignored. If **0** is specified for the **a** or **A** floating-point format, leading zeros are prepended to the mantissa, after the `0x` or `0X` prefix.|No padding.|
112
112
|**blank** (' ')|Use a blank to prefix the output value if it is signed and positive. The blank is ignored if both the blank and + flags appear.|No blank appears.|
113
113
|**#**|When it's used with the **o**, **x**, or **X** format, the **#** flag uses 0, 0x, or 0X, respectively, to prefix any nonzero output value.|No blank appears.|
114
-
||When it's used with the **e**, **E**, **f**, **F**, **a** or **A** format, the **#** flag forces the output value to contain a decimal point.|Decimal point appears only if digits follow it.|
114
+
||When it's used with the **e**, **E**, **f**, **F**, **a**, or **A** format, the **#** flag forces the output value to contain a decimal point.|Decimal point appears only if digits follow it.|
115
115
||When it's used with the **g** or **G** format, the **#** flag forces the output value to contain a decimal point and prevents the truncation of trailing zeros.<br /><br /> Ignored when used with **c**, **d**, **i**, **u**, or **s**.|Decimal point appears only if digits follow it. Trailing zeros are truncated.|
116
116
117
117
<aname="width"></a>
@@ -120,21 +120,21 @@ The first optional field in a conversion specification contains *flag directives
120
120
121
121
In a conversion specification, the optional width specification field appears after any *flags* characters. The *width* argument is a non-negative decimal integer that controls the minimum number of characters that are output. If the number of characters in the output value is less than the specified width, blanks are added to the left or the right of the values—depending on whether the left-alignment flag (**-**) is specified—until the minimum width is reached. If *width* is prefixed by 0, leading zeros are added to integer or floating-point conversions until the minimum width is reached, except when conversion is to an infinity or NaN.
122
122
123
-
The width specification never causes a value to be truncated. If the number of characters in the output value is greater than the specified width, or if *width*is not given, all characters of the value are output, subject to the *precision* specification.
123
+
The width specification never causes a value to be truncated. If the number of characters in the output value is greater than the specified width, or if *width*isn't given, all characters of the value are output, subject to the *precision* specification.
124
124
125
125
If the width specification is an asterisk (`*`), an `int` argument from the argument list supplies the value. The *width* argument must precede the value that's being formatted in the argument list, as shown in this example:
126
126
127
-
`printf("%0*f", 5, 3); /* 00003 is output */`
127
+
`printf("%0*d", 5, 3); /* 00003 is output */`
128
128
129
-
A missing or small *width* value in a conversion specification does not cause the truncation of an output value. If the result of a conversion is wider than the *width* value, the field expands to contain the conversion result.
129
+
A missing or small *width* value in a conversion specification doesn't cause the truncation of an output value. If the result of a conversion is wider than the *width* value, the field expands to contain the conversion result.
130
130
131
131
<aname="precision"></a>
132
132
133
133
## Precision specification
134
134
135
135
In a conversion specification, the third optional field is the precision specification. It consists of a period (.) followed by a non-negative decimal integer that, depending on the conversion type, specifies the number of string characters, the number of decimal places, or the number of significant digits to be output.
136
136
137
-
Unlike the width specification, the precision specification can cause either truncation of the output value or rounding of a floating-point value. If *precision* is specified as 0 and the value to be converted is 0, the result is no characters output, as shown in this example:
137
+
Unlike the width specification, the precision specification can cause either truncation of the output value or rounding of a floating-point value. If *precision* is specified as 0, and the value to be converted is 0, the result is no characters output, as shown in this example:
138
138
139
139
`printf( "%.0d", 0 ); /* No characters output */`
140
140
@@ -154,13 +154,13 @@ The *type* character determines either the interpretation of *precision* or the
154
154
|**e**, **E**|The precision specifies the number of digits to be printed after the decimal point. The last printed digit is rounded.|Default precision is 6. If *precision* is 0 or the period (.) appears without a number following it, no decimal point is printed.|
155
155
|**f**, **F**|The precision value specifies the number of digits after the decimal point. If a decimal point appears, at least one digit appears before it. The value is rounded to the appropriate number of digits.|Default precision is 6. If *precision* is 0, or if the period (.) appears without a number following it, no decimal point is printed.|
156
156
|**g**, **G**|The precision specifies the maximum number of significant digits printed.|Six significant digits are printed, and any trailing zeros are truncated.|
157
-
|**s**, **S**|The precision specifies the maximum number of characters to be printed. Characters in excess of *precision*are not printed.|Characters are printed until a null character is encountered.|
157
+
|**s**, **S**|The precision specifies the maximum number of characters to be printed. Characters in excess of *precision*aren't printed.|Characters are printed until a null character is encountered.|
158
158
159
159
<aname="size"></a>
160
160
161
161
## Argument size specification
162
162
163
-
In a conversion specification, the *size* field is an argument length modifier for the *type* conversion specifier. The *size* field prefixes to the *type* field—**hh**, **h**, **j**, **l** (lowercase L), **L**, **ll**, **t**, **w**, **z**, **I** (uppercase i), **I32**, and **I64**—specify the "size" of the corresponding argument—long or short, 32-bit or 64-bit, single-byte character or wide character—depending on the conversion specifier that they modify. These size prefixes are used with *type* characters in the `printf` and `wprintf` families of functions to specify the interpretation of argument sizes, as shown in the following table. The *size* field is optional for some argument types. When no size prefix is specified, the formatter consumes integer arguments—for example, signed or unsigned `char`, `short`, `int`, `long`, and enumeration types—as 32-bit `int` types, and `float`, `double`, and `long double` floating-point arguments are consumed as 64-bit `double` types. This matches the default argument promotion rules for variable argument lists. For more information about argument promotion, see Ellipses and Default Arguments in [Postfix expressions](../cpp/postfix-expressions.md). On both 32-bit and 64-bit systems, the conversion specification of a 64-bit integer argument must include a size prefix of **ll** or **I64**. Otherwise, the behavior of the formatter is undefined.
163
+
In a conversion specification, the *size* field is an argument length modifier for the *type* conversion specifier. The *size* field prefixes to the *type* field—**hh**, **h**, **j**, **l** (lowercase L), **L**, **ll**, **t**, **w**, **z**, **I** (uppercase i), **I32**, and **I64**—specify the "size" of the corresponding argument—long or short, 32-bit or 64-bit, single-byte character or wide character—depending on the conversion specifier that they modify. These size prefixes are used with *type* characters in the `printf` and `wprintf` families of functions to specify the interpretation of argument sizes, as shown in the following table. The *size* field is optional for some argument types. When no size prefix is specified, the formatter consumes integer arguments—for example, signed or unsigned `char`, `short`, `int`, `long`, and enumeration types—as 32-bit `int` types, and `float`, `double`, and `long double` floating-point arguments are consumed as 64-bit `double` types. This behavior matches the default argument promotion rules for variable argument lists. For more information about argument promotion, see Ellipses and Default Arguments in [Postfix expressions](../cpp/postfix-expressions.md). On both 32-bit and 64-bit systems, the conversion specification of a 64-bit integer argument must include a size prefix of **ll** or **I64**. Otherwise, the behavior of the formatter is undefined.
164
164
165
165
Some types are different sizes in 32-bit and 64-bit code. For example, `size_t` is 32 bits long in code compiled for x86, and 64 bits in code compiled for x64. To create platform-agnostic formatting code for variable-width types, you can use a variable-width argument size modifier. Alternatively, use a 64-bit argument size modifier and explicitly promote the variable-width argument type to 64 bits. The Microsoft-specific **I** (uppercase i) argument size modifier handles variable-width integer arguments, but we recommend the type-specific **j**, **t**, and **z** modifiers for portability.
166
166
@@ -187,7 +187,7 @@ The `ptrdiff_t` and `size_t` types are `__int32` or `unsigned __int32` on 32-bit
187
187
188
188
In Visual C++, although `long double` is a distinct type, it has the same internal representation as `double`.
189
189
190
-
An **hc** or **hC** type specifier is synonymous with **c** in `printf` functions and with **C** in `wprintf` functions. An **lc**, **lC**, **wc** or **wC** type specifier is synonymous with **C** in `printf` functions and with **c** in `wprintf` functions. An **hs** or **hS** type specifier is synonymous with **s** in `printf` functions and with **S** in `wprintf` functions. An **ls**, **lS**, **ws** or **wS** type specifier is synonymous with **S** in `printf` functions and with **s** in `wprintf` functions.
190
+
An **hc** or **hC** type specifier is synonymous with **c** in `printf` functions and with **C** in `wprintf` functions. An **lc**, **lC**, **wc**, or **wC** type specifier is synonymous with **C** in `printf` functions and with **c** in `wprintf` functions. An **hs** or **hS** type specifier is synonymous with **s** in `printf` functions and with **S** in `wprintf` functions. An **ls**, **lS**, **ws** or **wS** type specifier is synonymous with **S** in `printf` functions and with **s** in `wprintf` functions.
0 commit comments