wsprintf
A version of this page is also available for
4/8/2010
This function formats and stores a series of characters and values in a buffer. Any arguments are converted and copied to the output buffer according to the corresponding format specification in the format string. This function appends a terminating null character to the characters it writes, but the return value does not include the terminating null character in its character count.
Syntax
int wsprintf(
LPTSTR lpOut,
LPCTSTR lpFmt,
...
);
Parameters
- lpOut
[out] Pointer to a buffer to receive the formatted output. The maximum size of the buffer is 1024 characters.
- lpFmt
[in] Pointer to a null-terminated string that contains the format-control specifications. In addition to ordinary ASCII characters, a format specification for each argument appears in this string.
- optional parameters
[in] One or more optional parameters. The number and type of parameters depend on the corresponding format-control specifications in lpFmt.
Return Value
If the function succeeds, the return value is the number of characters stored in the output buffer, not counting the terminating null character. If the function fails, the return value is less than the length of expected output. To get extended error information, call GetLastError.
Remarks
Windows Embedded CE supports only the Unicode version of wsprintf.
The format-control string contains format specifications that determine the output format for the options following lpFmt. 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, if any, is encountered, it causes the value of the first option after the format-control string to be converted and copied to the output buffer according to the format specification. The second format specification causes the second option to be converted and copied, and so on. If there are more options than format specifications, the extra options are ignored. If there are not enough options for all of the format specifications, the results are undefined.
A format specification has the following form:
%[-][#][0][width][**.**precision]type
Each field is a single character or a number signifying a format option. The type characters that appear after the last optional format field determine whether the associated options 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 table describes the fields.
| Field | Description |
|---|---|
– |
Pad the output with blanks or zeros to the right to fill the field width, justifying output to the left. If this field is omitted, the output is padded to the left, justifying 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 |
Copy the specified minimum number of characters to the output buffer. 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 width is not present, all characters of the value are printed, subject to the precision specification. |
precision |
For numbers, copy the specified minimum number of digits to the output buffer. If the number of digits in the argument is less than the specified precision, 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 0 or omitted entirely, or if the period (.) appears without a number following it, the precision is set to 1. For strings, copy the specified maximum number of characters to the output buffer. |
type |
Output the corresponding parameter as a character, a string, or a number. The following table shows possible values.
Sequence Insert
c A single character. This value is interpreted as type WCHAR.
C A single character. This value is interpreted as type CHAR.
d A signed decimal integer parameter. This value is equivalent to a value of i.
hc, hC A single character. This function ignores character parameters with a numeric value of zero. This value is interpreted as type CHAR, even when the calling application uses the
#define UNICODE compile flag.
hd A signed short integer parameter.
hs, hS A string. This value is interpreted as type LPSTR, even when the calling application uses the
#define UNICODE compile flag.
hu An unsigned short integer.
i A signed decimal integer. This value is equivalent to a value of d.
lc, lC A single character. This function ignores character parameters with a numeric value of 0. This value is interpreted as type WCHAR, even when the calling application does not use the
#define UNICODE compile flag.
ld A long signed decimal integer. This value is equivalent to a value of li.
li A long signed decimal integer. This value is equivalent to a value of ld.
ls, lS A string. This sequence is interpreted as type LPWSTR, even when the calling application does not use the
#define UNICODE compile flag. This value is equivalent to a value of ws.
lu A long, unsigned integer.
lx, lX A long, unsigned hexadecimal integer in lowercase or uppercase.
s A string. This sequence is interpreted as type LPWSTR.
S A string. This sequence is interpreted as type LPSTR.
u An unsigned integer parameter.
x, X An unsigned hexadecimal integer in lowercase or uppercase.
|
Unlike other Win32 functions, this function uses the C calling convention (_cdecl), rather than the Pascal calling convention. As a result, the calling process must pop parameters off the stack, and parameters are pushed onto the stack from right to left. In C-language modules, the C compiler performs this task.
Requirements
| Header | winbase.h |
| Library | Coreloc.lib |
| Windows Embedded CE | Windows CE 1.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |