| int cdecl wsprintf(lpOut, lpFmt [[, argument]. . .) | |||
| LPTSTR lpOut; | |||
| LPCTSTR lpFmt; |
The wsprintf function formats and stores a series of characters and values in a buffer. Each argument (if any) is converted and output according to the corresponding format specification in the format string. The function appends a NULL to the end of the characters written, but the return value does not include the terminating null character in its character count.
lpOut
Points to a null-terminated string to receive the formatted output.
lpFmt
Points to a null-terminated string that contains the format-control string. In addition to ordinary ASCII characters, a format specification for each argument appears in this string. See the following Comments section for more information on the format specification.
argument
Specifies one or more optional arguments. The number and type of argument parameters depends on the corresponding format-control character sequences in lpFmt.
The return value is the number of characters stored in lpOut, not counting the terminating NULL. If an error occurs, the function returns a value less than the length of lpFmt.
The format-control string contains format specifications that determine the output format for the arguments which follow the lpFmt parameter. Format specifications, discussed below, always begin with a percent sign (%). If a percent sign is followed by a character that has no meaning, such as a format field, the character is output as is. For example, %% produces a single percent-sign character.
The format-control string is read from left to right. When the first format specification (if any) is encountered, it causes the value of the first argument after the format-control string to be converted and output according to the format specification. The second format specification causes the second argument to be converted and output, 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 a number signifying a particular format option. The type characters, which appear after the last optional format field, 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 control other aspects of the formatting. The following shows the optional and required fields and their meaning:
| Field | Description |
| – | Pad the output with blanks or zeroes to the right to fill the field width, justifying the output to the left. If this field is omitted, the output is padded to the left, justifying the output to the right. | ||
| # | Prefix hexadecimal values with 0x (lowercase) or OX (uppercase). | ||
| 0 | Pad the output value with zeroes to fill the field width. If this field is omitted, the output value is padded with blank spaces. | ||
| width | Output 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 precision specification. | ||
| precision | Output the specified minimum number of digits. If the number of digits in the argument is less than the specified precision, the output value is padded on the left with zeroes. The value is not truncated when the number of digits exceeds the specified precision. If the specified precision is 0, omitted entirely, or if the period ( . ) appears without a number following it, the precision is set to 1. | ||
| For strings, output the specified maximum number of characters. | |||
| type | Output the corresponding argument as a character, 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 numerical 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. |
| ts | Insert a generic string; that is, a Unicode character string if wsprintf was compiled with the #define UNICODE compile flag, or ANSI otherwise. |
| tc | Insert a generic character; that is, a single Unicode character if wsprintf was compiled with the #define UNICODE compile flag, or ANSI otherwise. |
| ws | Insert a Unicode string. |
| wc | Insert a Unicode character. |
wsprintf and wvsprintf vary in how they handle number sizing.
wsprintf is completely portable. It handles number sizes correctly based on the platform. For Windows32, therefore, %d prints long values.
wvsprintf, on the other hand, works the same way that it did in Windows 3.0. %d prints word-size values, %ld prints long values.
Unlike all other Windows functions, wsprintf uses the C calling convention (_cdecl), rather than the Pascal calling convention. As a result, it is the caller's responsibility to pop arguments off the stack, and arguments are pushed on the stack from right to left. In C-language modules, the C compiler performs this task.
wvsprintf