| int _cdecl wsprintf(lpszOutput, lpszFormat, . . . ) | |||||
| LPSTR lpszOutput; | /* address of string for output | */ | |||
| LPSTR lpszFormat; | /* address of format-control string | */ | |||
The wsprintf function formats and stores a series of characters and values in a buffer. Each argument (if any) is converted according to the corresponding format specified in the format string.
lpszOutput
Points to a null-terminated string to receive the string formatted as specified in the lpszFormat parameter.
lpszFormat
Points to a null-terminated string that contains the format-control string. In addition to the standard ASCII characters, a format specification for each argument appears in this string. For more information about the format specification, see the following Comments section.
. . .
Specifies zero or more optional arguments. The number and type of the optional arguments depend on the corresponding format-control character sequences specified in the lpszFormat parameter.
The return value is the number of bytes stored in the lpszOutput string, not counting the terminating null character, if the function is successful.
The largest buffer that wsprintf can create is 1K.
Unlike most Windows functions, wsprintf uses the C calling convention (_cdecl) rather than the Pascal calling convention. As a result, the calling function must pop arguments off the stack. Also, arguments must be pushed on the stack from right to left. In C-language modules, the C compiler performs this task. (The wvsprintf function uses the Pascal calling convention.)
The format-control string contains format specifications that determine the output format for the arguments that follow the lpszFormat parameter. Format specifications always begin with a percent sign (%). If a percent sign is followed by a character that has no meaning as a format field, the character is not formatted. For example, %% produces a single percent-sign character.
The format-control string is read from left to right. When the first format specification is encountered, it causes the value of the first argument after the format-control string to be converted according to the format specification. The second format specification causes the second argument to be converted, and so on. If there are more arguments than there are format specifications, the extra arguments are ignored. The results are undefined if there are not enough arguments for all of the format specifications.
A format specification has the following form:
%[-][#][0][width][.precision]type
Each field of the format specification is a single character or number signifying a particular format option. The type characters, for example, determine whether the associated argument is interpreted as a character, a string, or a number. The simplest format specification contains only the percent sign and a type character (for example, %s). The optional fields (in brackets) control other aspects of the formatting. Following are the optional and required fields and their meanings:
| Field | Meaning |
| - | Pad the output value with blanks or zeros to the right to fill the field width, aligning the output value to the left. If this field is omitted, the output value is padded to the left, aligning it to the right. |
| # | Prefix hexadecimal values with 0x (lowercase) or 0X (uppercase). |
| 0 | Pad the output value with zeros to fill the field width. If this field is omitted, the output value is padded with blank spaces. |
| width | Convert the specified minimum number of characters. The width field is a nonnegative integer. 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 the width field is not present, all characters of the value are printed, subject to the value of the precision field. |
| precision | Convert the specified minimum number of digits. If there are fewer digits in the argument than the specified value, the output value is padded on the left with zeros. The value is not truncated when the number of digits exceeds the specified precision. If the specified precision is zero or omitted entirely, or if the period (.) appears without a number following it, the precision is set to 1. |
| For strings, convert the specified maximum number of characters. | |
| type | Format the corresponding argument as a character, a string, or a number. This field may be any of the following character sequences: |
| Sequence | Meaning |
| c | Insert a single character argument. The wsprintf function ignores character arguments with a numeric value of zero. |
| d, i | Insert a signed decimal integer argument. |
| ld, li | Insert a long signed decimal integer argument. |
| u | Insert an unsigned integer argument. |
| lu | Insert a long unsigned integer argument. |
| lx, lX | Insert a long unsigned hexadecimal integer argument in lowercase or uppercase. |
| s | Insert a string. |