The C++ <cwchar> vwprintf() function writes the C wide string pointed by format to the standard output (stdout). If format includes format specifiers (sub-sequences beginning with %), the variable argument list identified by vlist are formatted and inserted in the resulting string replacing their respective specifiers.
Internally, the function retrieves arguments from the list identified by vlist as if va_start was used on it, and thus the state of vlist is likely altered by the call.
In any case, vlist 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.
The multibyte characters of stdout are interpreted as wide characters as if wcrtomb() function is called to convert each wide character (using the stream's internal mbstate_t object).
Note: This function is wide character equivalent of vprintf() function.
Syntax
int vwprintf ( const wchar_t* format, va_list vlist );
Parameters
format
Specify the format wide string. The possible values of %specifier are:
%specifier
Description
%%
Returns a percent sign
%c
Character
%d
Signed decimal integer (negative, zero or positive)
%i
Signed decimal integer (negative, zero or positive)
%u
Unsigned decimal number (zero or positive)
%e
Scientific notation using a lowercase (e.g. 1.2e+3)
%E
Scientific notation using a uppercase (e.g. 1.2E+3)
%f
Decimal floating point, lowercase
%F
Decimal floating point, uppercase
%g
Shorter of %e and %f
%G
Shorter of %E and %f
%p
Pointer address
%o
Unsigned octal
%s
String of characters
%x
Unsigned hexadecimal integer (lowercase letters)
%X
Unsigned hexadecimal integer (uppercase letters)
%a
Hexadecimal floating point (lowercase letters)
%A
Hexadecimal floating point (uppercase letters)
%n
Nothing is printed. Returns the number of characters written so far by this call to the function. The result is written to the value pointed to by the argument. The corresponding argument must be a pointer to a signed int. The specification may not contain any flag, width, or precision. See the example below.
Additional format values can be placed between the % and the specifier (e.g. %.3f) also known as sub-specifier. These sub-specifier are:
Flags:
- : Left-justify within the given field width. Right justify is the default.
+ : Prefix positive numbers with a plus sign +. By default only negative are prefixed with a negative sign.
(space) : If no sign is going to be written, a blank space is inserted before the value.
# : When used with o, x or X specifiers the value is preceded with 0, 0x or 0X respectively for values different than zero. When used with a, A, e, E, f, F, g or G specifiers, it forces the written output to contain a decimal point even if no more digits follow. By default, no decimal point is written if no digits follow.
0 : Only left-pads numbers with zeros instead of spaces when padding is specified.
Width: An integer or * that specifies minimum field width. In the case when * is used, the width is not specified in the format string, but as an additional integer value argument preceding the argument that has to be formatted. If the value to be printed is shorter than the width, the result is padded with blank spaces. (Note: This is the minimum width: The value is never truncated.)
Precision: Period . followed by an integer or *. In the case when * is used, the precision is not specified in the format string, but as an additional integer value argument preceding the argument that has to be converted. If the value of this argument is negative, it is ignored. If neither a number nor * is used, the precision is taken as zero.
For d, i, o, u, x and X specifiers: It signifies the minimum number of digits.
For a, A, e, E, f and F specifiers: It signifies the number of decimal digits.
For g and G specifiers: It signifies the maximum number of significant digits.
For s specifier: It specifies a cutoff point, setting maximum number of characters.
Length: Modifies the length of the data type. For example - %i is used for signed decimal integer, with ll length sub-specifier it becomes %lli which can be used for long long int data type. Here is the complete list of length sub-specifier.
Note: If multiple additional format values are provided, they must be in %[flags][width][.precision][length]specifier order.
vlist
Specify a variable argument list containing the data to print initialized with va_start.
Return Value
Returns the total number of characters written on success (not including the terminating null character). If a writing error occurs, sets the error indicator ferror() and a negative number is returned. If a multibyte character encoding error occurs while writing wide characters, errno is set to EILSEQ and a negative number is returned.
Example: vwprintf() example
In the example below shows the usage of vwprintf() function.
#include <cwchar>
#include <cstdarg>
void PrintWideFormatted ( const wchar_t * format, ... ) {
va_list args;
va_start(args, format);
vwprintf(format, args);
va_end(args);
}
int main () {
PrintWideFormatted(L"Calling with %d variable argument.\n", 1);
PrintWideFormatted(L"Calling with %d variable %ls.\n", 2, L"arguments");
PrintWideFormatted(L"Calling with %d %ls %ls.\n", 3, L"variable", L"arguments");
return 0;
}
The output of the above code will be:
Calling with 1 variable argument.
Calling with 2 variable arguments.
Calling with 3 variable arguments.
Length sub-specifier
Specifiers
length
d i
u o x X
f F e E g G a A
c
s
p
n
(none)
int
unsigned int
double
int
char*
void*
int*
hh
signed char
unsigned char
signed char*
h
short int
unsigned short int
short int*
l
long int
unsigned long int
double
wint_t
wchar_t*
long int*
ll
long long int
unsigned long long int
long long int*
j
intmax_t
uintmax_t
intmax_t*
z
size_t
size_t
size_t*
t
ptrdiff_t
ptrdiff_t
ptrdiff_t*
L
long double
See <cinttypes> for the specifiers for extended types.
