wsprintf
The wsprintf
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. The 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.
int wsprintf(
|
LPTSTR lpOut, |
// pointer to
buffer for output |
|
LPCTSTR lpFmt, |
// pointer to
format-control string |
|
... |
// optional
arguments |
|
); |
|
Parameters
lpOut
Points to a
buffer to receive the formatted output.
lpFmt
Points 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. For more information about the format specification,
see the Remarks section.
...
Specifies one
or more optional arguments. The number and type of argument parameters depend
on the corresponding format-control specifications in the lpFmt parameter.
Return Values
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 the format-control string.
To get extended error information, call GetLastError.
Remarks
The
format-control string contains format specifications that determine the output
format for the arguments following 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 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
argument 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 argument to be converted and copied, and so on. If there are
more arguments than format specifications, the extra arguments are ignored. If
there are not enough arguments 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 particular format option. The type
characters that 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. Following are the optional and required fields and their
meanings:
|
Field |
Meaning |
|
- |
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 the width field 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 argument as a character, a string, or a number. This field can
be any of the following character sequences: |
|
Sequence |
Insert |
|
c |
A single
character. The wsprintf function ignores character arguments with a
numeric value of zero. This sequence is interpreted as type WCHAR when
the calling application uses the #define UNICODE compile flag
and as type CHAR otherwise. |
|
C |
A single
character. This sequence is interpreted as type CHAR when the calling
application uses the #define UNICODE compile flag and as type WCHAR
otherwise. |
|
d |
A signed
decimal integer argument. This sequence is equivalent to the i
sequence. |
|
hc, hC |
A single
character. The wsprintf function ignores character arguments with a
numeric value of zero. This sequence is always interpreted as type CHAR,
even when the calling application uses the #define UNICODE
compile flag. |
|
hs, hS |
A string.
This sequence is always interpreted as type LPSTR, even when the
calling application uses the #define UNICODE compile flag. |
|
i |
A signed
decimal integer. This sequence is equivalent to the d sequence. |
|
lc, lC |
A single
character. The wsprintf function ignores character arguments with a
numeric value of zero. This sequence is always interpreted as type WCHAR,
even when the calling application does not use the #define UNICODE
compile flag. |
|
ld |
A long
signed decimal integer. This sequence is equivalent to the li
sequence. |
|
li |
A long signed
decimal integer. This sequence is equivalent to the ld sequence. |
|
ls, lS |
A string.
This sequence is always interpreted as type LPWSTR, even when the
calling application does not use the #define UNICODE compile
flag. This sequence is equivalent to the ws sequence. |
|
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 when the calling
application uses the #define UNICODE compile flag and as type LPSTR
otherwise. |
|
S |
A string.
This sequence is interpreted as type LPSTR when the calling
application uses the #define UNICODE compile flag and as type LPWSTR
otherwise. |
|
u |
An unsigned
integer argument. |
|
x, X |
An unsigned
hexadecimal integer in lowercase or uppercase. |
Note Unlike other
Windows functions, wsprintf uses the C calling convention (_cdecl),
rather than the Pascal calling convention. As a result, it is the
responsibility of the calling process 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.
See Also