C++ <cwchar> - swprintf() Function
The C++ <cwchar> swprintf() function writes the C wide string pointed by format to a wide string buffer. If format includes format specifiers (sub-sequences beginning with %), the additional arguments following format are formatted and inserted in the resulting string replacing their respective specifiers.
After the format parameter, the function expects additional arguments at least as many as the number of format specifiers in the format string.
The size of the buffer should be large enough to contain the resulting string. A terminating null character is automatically appended after the content.
Syntax
int swprintf ( wchar_t* buffer, size_t size, const wchar_t* format, ... );
Parameters
buffer |
Specify pointer to a wide character string to write to. It should be large enough to contain the resulting string. | ||||||||||||||||||||||||||||||||||||||||
size |
Specify maximum number of wide characters to fill in the buffer. Up to size - 1 characters may be written, plus the null terminator. size_t is an unsigned integral type. | ||||||||||||||||||||||||||||||||||||||||
format |
Specify the format wide string. The possible values of %specifier are:
Additional format values can be placed between the % and the specifier (e.g. %.3f) also known as sub-specifier. These sub-specifier are:
Note: If multiple additional format values are provided, they must be in %[flags][width][.precision][length]specifier order. | ||||||||||||||||||||||||||||||||||||||||
... (additional arguments) |
Depending on the format string, a sequence of additional arguments should be passed in the function, each containing a value to replace a format specifiers in the format string. Number of arguments should be at least equal to the number of format specifiers in the format string. Additional arguments will be ignored by this function. |
Return Value
Returns the total number of characters written on success (not including the terminating null character). On failure (including when the resulting string to be written to buffer is longer than size), a negative number is returned.
Example: Different specifiers
In the example below, the swprintf() function is used to return the formatted string.
#include <cwchar> int main (){ wchar_t buffer [100]; swprintf(buffer, 100, L"Characters: %c %c \n", 'b', 66); wprintf(L"1. %ls", buffer); swprintf(buffer, 100, L"Decimals: %d %i \n", 200, 300); wprintf(L"2. %ls", buffer); swprintf(buffer, 100, L"More Decimals: %ld %li \n", 20000L, 30000L); wprintf(L"3. %ls", buffer); swprintf(buffer, 100, L"Octals: %o %#o \n", 100, 100); wprintf(L"4. %ls", buffer); swprintf(buffer, 100, L"Hexadecimals: %x %#x %X %#X \n", 100, 100, 100, 100); wprintf(L"5. %ls", buffer); swprintf(buffer, 100, L"Strings: %s \n", "Hello"); wprintf(L"6. %ls", buffer); swprintf(buffer, 100, L"Scientific notation: %e %E \n", 123.45, 123.45); wprintf(L"7. %ls", buffer); swprintf(buffer, 100, L"Floats: %2.0f %2.2f %2.4f \n", 3.1416, 3.1416, 3.1416); wprintf(L"8. %ls", buffer); swprintf(buffer, 100, L"Positive signed number = %+.2f \n", 3.1416); wprintf(L"9. %ls", buffer); swprintf(buffer, 100, L"Padded number = %05d \n", 89); wprintf(L"10. %ls", buffer); swprintf(buffer, 100, L"Number with Width = %*d \n", 5, 89); wprintf(L"11. %ls", buffer); return 0; }
The output of the above code will be:
1. Characters: b B 2. Decimals: 200 300 3. More Decimals: 20000 30000 4. Octals: 144 0144 5. Hexadecimals: 64 0x64 64 0X64 6. Strings: Hello 7. Scientific notation: 1.234500e+02 1.234500E+02 8. Floats: 3 3.14 3.1416 9. Positive signed number = +3.14 10. Padded number = 00089 11. Number with Width = 89
Example: Format date string
In the example below, this function is used to return formatted date string .
#include <cwchar> int main (){ int year = 2015; int month = 5; int day = 1; wchar_t buffer [100]; //each format specifier specifies padding //with 0 and width of the field swprintf(buffer, 100, L"%04d-%02d-%02d", year, month, day); wprintf(L"Date is: %ls", buffer); return 0; }
The output of the above code will be:
Date is: 2015-05-01
Example: String specifiers
Consider one more example to see how to use string specifiers with a given character/wide string.
#include <cwchar> int main (){ char x[] = "catfish"; wchar_t y[] = L"many catfishes"; wchar_t buffer [100]; swprintf(buffer, 100, L"[%s]\n", x); //standard string wprintf(L"1. %ls", buffer); swprintf(buffer, 100, L"[%10s]\n", x); //right-justified with spaces wprintf(L"2. %ls", buffer); swprintf(buffer, 100, L"[%*s]\n", 10, x); //right-justified with spaces wprintf(L"3. %ls", buffer); swprintf(buffer, 100, L"[%-10s]\n", x); //left-justified with spaces wprintf(L"4. %ls", buffer); swprintf(buffer, 100, L"[%-*s]\n", 10, x); //left-justified with spaces wprintf(L"5. %ls", buffer); swprintf(buffer, 100, L"[%10.8ls]\n", y); //right-justified (8 characters cutoff) wprintf(L"6. %ls", buffer); swprintf(buffer, 100, L"[%-10.8ls]\n", y); //left-justified (8 characters cutoff) wprintf(L"7. %ls", buffer); swprintf(buffer, 100, L"[%-*.*ls]\n", 10, 8, y);//left-justified (8 characters cutoff) wprintf(L"8. %ls", buffer); return 0; }
The output of the above code will be:
1. [catfish] 2. [ catfish] 3. [ catfish] 4. [catfish ] 5. [catfish ] 6. [ many cat] 7. [many cat ] 8. [many cat ]
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.
❮ C++ <cwchar> Library