ILE C/C++ Run-Time Library Functions


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.

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:

Width and precision always are wide characters.

When the program is compiled with LOCALETYPE(*LOCALEUCS2) or LOCALETYPE(*LOCALEUTF), and SYSIFCOPT(*IFSIO), the wide characters that are written by this function are Unicode characters, and the inputs for %lc and %ls are assumed to be Unicode characters. To view Unicode examples, see fwprintf() -- Format Data as Wide Characters and Write to a Stream.

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.

In extended mode, the swprintf() function also converts floating-point values of NaN and infinity to the strings "NAN" or "nan" and "INFINITY" or "infinity". The case and sign of the string is determined by the format specifiers.

Note:
This function is not available when either LOCALETYPE(*CLD) or SYSIFCOPT(*NOIFSIO) is specified on the compilation command.

Return Value

The swprintf() function returns the number of wide characters that are written in the array, not counting the ending null wide character.

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 | Table of Contents | Index ]