Skip to content

Commit 0cc6e53

Browse files
TylerMSFTTylerMSFT
authored andcommitted
acrolinx and formatting updates
1 parent 477a2d4 commit 0cc6e53

File tree

3 files changed

+125
-127
lines changed

3 files changed

+125
-127
lines changed

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

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -61,13 +61,13 @@ Integer types such as `short`, `int`, `long`, `long long`, and their `unsigned`
6161
|**`F`**|Floating-point|Identical to the **`f`** format except that infinity and nan output is capitalized.|
6262
|**`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.|
6363
|**`G`**|Floating-point|Identical to the **`g`** format, except that **`E`**, rather than **`e`**, introduces the exponent (where appropriate).|
64-
|**`a`**|Floating-point|Signed hexadecimal double-precision floating-point value that has the form [-]0x*`h.hhhh`*____*`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.|
65-
|**`A`**|Floating-point|Signed hexadecimal double-precision floating-point value that has the form [-]0X*`h.hhhh`*____*`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.|
64+
|**`a`**|Floating-point|Signed hexadecimal double-precision floating-point value that has the form *[-]0xh.hhhh*____*`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.|
65+
|**`A`**|Floating-point|Signed hexadecimal double-precision floating-point value that has the form *[-]0Xh.hhhh*____*`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.|
6666
|**`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.|
6767
|**`p`**|Pointer type|Display the argument as an address in hexadecimal digits.|
6868
|**`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.|
6969
|**`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.|
70-
|**`Z`**|`ANSI_STRING` or `UNICODE_STRING` structure|When the address of an [ANSI_STRING](/windows/win32/api/ntdef/ns-ntdef-string) or [UNICODE_STRING](/windows/win32/api/ntdef/ns-ntdef-_unicode_string) structure is passed as the argument, displays the string contained in the buffer pointed to by the `Buffer` field of the structure. Use a *size* modifier prefix of **w** to specify a `UNICODE_STRING` argument—for example, `%wZ`. The `Length` field of the structure must be set to the length, in bytes, of the string. The `MaximumLength` field of the structure must be set to the length, in bytes, of the buffer.<br /><br />Typically, the **`Z`** type character is used only in driver debugging functions that use a conversion specification, such as `dbgPrint` and `kdPrint`.|
70+
|**`Z`**|`ANSI_STRING` or `UNICODE_STRING` structure|When the address of an [`ANSI_STRING`](/windows/win32/api/ntdef/ns-ntdef-string) or [`UNICODE_STRING`](/windows/win32/api/ntdef/ns-ntdef-_unicode_string) structure is passed as the argument, display the string contained in the buffer pointed to by the `Buffer` field of the structure. Use a *size* modifier prefix of **`w`** to specify a `UNICODE_STRING` argument—for example, `%wZ`. The `Length` field of the structure must be set to the length, in bytes, of the string. The `MaximumLength` field of the structure must be set to the length, in bytes, of the buffer.<br /><br />Typically, the **`Z`** type character is used only in driver debugging functions that use a conversion specification, such as `dbgPrint` and `kdPrint`.|
7171

7272
Starting in Visual Studio 2015, if the argument that corresponds to a floating-point conversion specifier (**`a`**, **`A`**, **`e`**, **`E`**, **`f`**, **`F`**, **`g`**, **`G`**) is infinite, indefinite, or NaN, the formatted output conforms to the C99 standard. This table lists the formatted output:
7373

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

92-
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.
92+
Any of these may have been prefixed by a sign, and may have been formatted differently depending on field width and precision, sometimes with unusual effects. For example, `printf("%.2f\n", INFINITY)` prints `1.#J` because the *#INF* would be "rounded" to two digits of precision.
9393

9494
> [!NOTE]
9595
> 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.
@@ -113,7 +113,7 @@ The first optional field in a conversion specification contains *flag directives
113113
|**`-`**|Left align the result within the given field width.|Right align.|
114114
|**`+`**|Use a sign (+ or -) to prefix the output value if it's of a signed type.|Sign appears only for negative signed values (-).|
115115
|**`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.|
116-
|**blank** (' ')|Use a blank to prefix the output value if it's signed and positive. The blank is ignored if both the blank and + flags appear.|No blank appears.|
116+
|**blank (' ')**|Use a blank to prefix the output value if it's signed and positive. The blank is ignored if both the blank and + flags appear.|No blank appears.|
117117
|**`#`**|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.|
118118
||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.|
119119
||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.|
@@ -124,7 +124,7 @@ The first optional field in a conversion specification contains *flag directives
124124

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

127-
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.
127+
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 provided, all characters of the value are output, subject to the *precision* specification.
128128

129129
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:
130130

@@ -154,17 +154,17 @@ The *type* character determines either the interpretation of *precision* or the
154154
|----------|-------------|-------------|
155155
|**`a`**, **`A`**|The precision specifies the number of digits after the point.|Default precision is 13. If precision is 0, no decimal point is printed unless the **`#`** flag is used.|
156156
|**`c`**, **`C`**|The precision has no effect.|Character is printed.|
157-
|**`d`**, **`i`**, **`o`**, **`u`**, **`x`**, **`X`**|The precision specifies the minimum number of digits to be printed. If the number of digits in the argument is less than *precision*, the output value is padded on the left with zeros. The value is not truncated when the number of digits exceeds *precision*.|Default precision is 1.|
157+
|**`d`**, **`i`**, **`o`**, **`u`**, **`x`**, **`X`**|The precision specifies the minimum number of digits to be printed. If the number of digits in the argument is less than *precision*, the output value is padded on the left with zeros. The value isn't truncated when the number of digits exceeds *precision*.|Default precision is 1.|
158158
|**`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.|
159159
|**`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.|
160160
|**`g`**, **`G`**|The precision specifies the maximum number of significant digits printed.|Six significant digits are printed, and any trailing zeros are truncated.|
161-
|**`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.|
161+
|**`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 found.|
162162

163163
<a name="size"></a>
164164

165165
## Argument size specification
166166

167-
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 Ellipsis 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.
167+
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 Ellipsis 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.
168168

169169
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. Instead, 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.
170170

0 commit comments

Comments
 (0)