function
<cwchar>
vswprintf
int vswprintf (wchar_t * ws, size_t len, const wchar_t * format, va_list arg );
Write formatted data from variable argument list to sized buffer
Composes a string with the same text that would be printed if format was used on wprintf, but using the elements in the variable argument list identified by arg instead of additional function arguments and storing the resulting content as a C wide string in the buffer pointed by ws (taking len as the maximum buffer capacity to fill, expressed in wide characters).
If the resulting string would be longer than n-1 wide characters, the remaining characters are discarded and not stored.
Internally, the function retrieves arguments from the list identified by arg as if va_arg was used on it, and thus the state of arg is likely to be altered by the call.
In any case, arg should have been initialized by va_start at some point before the call, and it is expected to be released by va_end at some point after the call.
This is the wide character equivalent of vsnprintf (<cstdio>).
Parameters
- ws
- Pointer to a buffer where the resulting C wide string is stored.
The buffer should have a size of at least len wide characters.
- len
- Maximum number of wide characters to be written to the buffer.
The generated string has a length of at most n-1, leaving space for the additional terminating null wide character.
size_t is an unsigned integral type.
- format
- C wide string that contains a format string that follows the same specifications as format in printf (see printf for details).
Notice that all format specifiers have the same meaning as in printf; therefore, %lc shall be used to write a wide character (and not %c), as well as %ls shall be used for wide strings (and not %s).
- arg
- A value identifying a variable arguments list initialized with va_start.
va_list is a special type defined in <cstdarg>.
Return Value
On success, the total number of characters written is returned. This count does not include the additional null-character automatically appended at the end of the string.
A negative number is returned on failure, including when the resulting string to be written to ws would be longer than n characters.
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
|
/* vswprintf example */
#include <stdio.h>
#include <stdarg.h>
#include <wchar.h>
void PrintWide ( const wchar_t * format, ... )
{
wchar_t buffer[256];
va_list args;
va_start ( args, format );
vswprintf ( buffer, 256, format, args );
fputws ( buffer, stdout );
va_end ( args );
}
int main ()
{
wchar_t str[] = L"test string has %d wide characters.\n";
PrintWide ( str, wcslen(str) );
return 0;
}
|
Possible output:
test string has 36 wide characters.
|
See also
- printf
- Print formatted data to stdout (function)
- vsnprintf
- Write formatted data from variable argument list to sized buffer (function)
- vfwprintf
- Write formatted data from variable argument list to stream (function)
- vwprintf
- Print formatted data from variable argument list to stdout (function)
- swprintf
- Write formatted data to wide string (function)
- wprintf
- Print formatted data to stdout (function)