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 that uses swprintf()

This example uses the 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"
   ***************************************************************/
}

Related Information

[ Top of Page | Previous Page | Next Page | Contents | Index ]