swprintf() — Format and Write Wide Characters to Buffer
Format
#include <wchar.h>
int swprintf(wchar_t *wcsbuffer, size_t n,
const wchar_t *format, argument-list);
Language Level
ANSI
Threadsafe
Yes
Locale Sensitive
The behavior of this function might be affected by the LC_CTYPE and LC_NUMERIC categories of the current locale. The behavior might also be affected by the LC_UNI_CTYPE and LC_UNI_NUMERIC categories of the current locale if LOCALETYPE(*LOCALEUCS2) or LOCALETYPE(*LOCALEUTF) is specified on the compilation command. This function is not available when LOCALETYPE(*CLD) is specified on the compilation command. For more information, see Understanding CCSIDs and Locales.
Wide Character Function
See Wide Characters for more information.
Description
The swprintf()
function
formats and stores a series of wide characters and values into the
wide-character buffer wcsbuffer. The swprintf()
function
is equivalent to the sprintf()
function,
except that it operates on wide characters.
The value n specifies the maximum number of wide
characters to be written, including the ending null character. The swprintf()
function
converts each entry in the argument-list according to the corresponding
wide-character format specifier in format. The format has the same
form and function as the format string for the printf()
function,
with the following exceptions:
- %c (without an l prefix) converts a character argument to wchar_t,
as if by calling the
mbtowc()
function. - %lc and %C copy a wchar_t to wchar_t. %#lc and %#C are equivalent to %lc and %C, respectively.
- %s (without an l prefix) converts an array of multibyte characters
to an array of wchar_t, as if by calling the
mbstowcs()
function. The array is written up to, but not including, the ending null character, unless the precision specifies a shorter output. - %ls and %S copy an array of wchar_t (no conversion). The array is written up to, but not including, the ending NULL character, unless the precision specifies a shorter output. %#ls and %#S are equivalent to %ls and %S, respectively.
Width and precision always are wide characters.
A null wide character is added to the end of the wide characters written; the null wide character is not counted as part of the returned value. If copying takes place between objects that overlap, the behavior is undefined.
Return Value
The swprintf()
function
returns the number of wide characters that are written to the output
buffer, not counting the ending null wide character or a negative
value if an error is encountered. If n or more wide characters are
requested to be written, a negative value is returned.
The value of errno
may be set to EINVAL,
invalid argument.
Example
swprintf()
function
to format and print several values to buffer. #include <wchar.h>
#include <stdio.h>
#define BUF_SIZE 100
int main(void)
{
wchar_t wcsbuf[BUF_SIZE];
wchar_t wstring[] = L"ABCDE";
int num;
num = swprintf(wcsbuf, BUF_SIZE, L"%s", "xyz");
num += swprintf(wcsbuf + num, BUF_SIZE - num, L"%ls", wstring);
num += swprintf(wcsbuf + num, BUF_SIZE - num, L"%i", 100);
printf("The array wcsbuf contains: \"%ls\"\n", wcsbuf);
return 0;
/***************************************************************
The output should be similar to :
The array wcsbuf contains: "xyzABCDE100"
***************************************************************/
}