Skip to content

Commit 412e2d8

Browse files
authored
Merge pull request #2200 from corob-msft/cr-1366
Fix 1366, issue in printf format specifications
2 parents a21ba2a + 49f4cd6 commit 412e2d8

1 file changed

Lines changed: 15 additions & 15 deletions

File tree

‎docs/c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md‎

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
---
22
title: "Format Specification Syntax: printf and wprintf Functions"
3-
ms.date: "07/02/2019"
3+
ms.date: "07/30/2019"
44
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"]
55
ms.assetid: 664b1717-2760-4c61-bd9c-22eee618d825
66
---
77
# Format specification syntax: printf and wprintf functions
88

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).
1010

1111
A conversion specification consists of optional and required fields in this form:
1212

@@ -51,15 +51,15 @@ Integer types such as `short`, `int`, `long`, `long long`, and their `unsigned`
5151
|**u**|Integer|Unsigned decimal integer.|
5252
|**x**|Integer|Unsigned hexadecimal integer; uses "abcdef."|
5353
|**X**|Integer|Unsigned hexadecimal integer; uses "ABCDEF."|
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.|
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.|
5555
|**E**|Floating-point|Identical to the **e** format except that **E** rather than **e** introduces the exponent.|
5656
|**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.|
5757
|**F**|Floating-point|Identical to the **f** format except that infinity and nan output is capitalized.|
5858
|**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.|
5959
|**G**|Floating-point|Identical to the **g** format, except that **E**, rather than **e**, introduces the exponent (where appropriate).|
6060
|**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.|
6161
|**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.|
6363
|**p**|Pointer type|Displays the argument as an address in hexadecimal digits.|
6464
|**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.|
6565
|**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
7171
|-----------|------------|
7272
|infinity|`inf`|
7373
|Quiet NaN|`nan`|
74-
|Signalling NaN|`nan(snan)`|
74+
|Signaling NaN|`nan(snan)`|
7575
|Indefinite NaN|`nan(ind)`|
7676

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 round trip through `printf` and `scanf` functions.
7878

7979
Before Visual Studio 2015, the CRT used a different, non-standard format for output of infinite, indefinite, and NaN values:
8080

@@ -85,7 +85,7 @@ Before Visual Studio 2015, the CRT used a different, non-standard format for out
8585
|Indefinite (same as quiet NaN)|*digit* `.#IND` *random-digits*|
8686
|NaN|*digit* `.#NAN` *random-digits*|
8787

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.
8989

9090
> [!NOTE]
9191
> 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
111111
|**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.|
112112
|**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.|
113113
|**#**|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.|
115115
||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.|
116116

117117
<a name="width"></a>
@@ -120,21 +120,21 @@ The first optional field in a conversion specification contains *flag directives
120120

121121
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.
122122

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.
124124

125125
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:
126126

127-
`printf("%0*f", 5, 3); /* 00003 is output */`
127+
`printf("%0*d", 5, 3); /* 00003 is output */`
128128

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.
130130

131131
<a name="precision"></a>
132132

133133
## Precision specification
134134

135135
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.
136136

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:
138138

139139
`printf( "%.0d", 0 ); /* No characters output */`
140140

@@ -154,13 +154,13 @@ The *type* character determines either the interpretation of *precision* or the
154154
|**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.|
155155
|**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.|
156156
|**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.|
158158

159159
<a name="size"></a>
160160

161161
## Argument size specification
162162

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.
164164

165165
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.
166166

@@ -187,7 +187,7 @@ The `ptrdiff_t` and `size_t` types are `__int32` or `unsigned __int32` on 32-bit
187187

188188
In Visual C++, although `long double` is a distinct type, it has the same internal representation as `double`.
189189

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.
191191

192192
> [!NOTE]
193193
> **Microsoft Specific**

0 commit comments

Comments
 (0)