vswprintf() — Format and Write Wide Characters to Buffer

Format

#include <stdarg.h>
#include <wchar.h>
int vswprintf(wchar_t *wcsbuffer, size_t n, const wchar_t
              *format, va_list argptr);

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. It 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 vswprintf() function formats and stores a series of wide characters and values in the buffer wcsbuffer. The vswprintf() function works just like the swprintf() function, except that argptr points to a list of wide-character arguments whose number can vary from call to call. These arguments should be initialized by va_start for each call. In contrast, the swprintf() function can have a list of arguments, but the number of arguments in that list are fixed when you compile the program.

The value n specifies the maximum number of wide characters to be written, including the ending null character. The vswprintf() 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 an integer argument to wchar_t, as if by calling the mbtowc() function.
%lc converts a wint_t to wchar_t.
%s (without an l prefix) converts an array of multibyte characters to an array of wchar_t, as if by calling the mbrtowc() function. The array is written up to, but not including, the ending null character, unless the precision specifies a shorter output.
%ls writes an array of wchar_t. The array is written up to, but not including, the ending null character, unless the precision specifies a shorter output.

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 vswprintf() function returns the number of bytes written in the array, not counting the ending null wide character.

Example that uses vswprintf()

This example creates a function vout() that takes a variable number of wide-character arguments and uses vswprintf() to print them to wcstr.

#include <stdio.h>
#include <stdarg.h>
#include <wchar.h>
 
wchar_t *format3 = L"%ls  %d  %ls";
wchar_t *format5 = L"%ls  %d  %ls  %d  %ls";
 
void vout(wchar_t *wcs, size_t n, wchar_t *fmt, ...)
{
   va_list arg_ptr;
 
   va_start(arg_ptr, fmt);
   vswprintf(wcs, n, fmt, arg_ptr);
   va_end(arg_ptr);
   return;
}
 
int main(void)
{
   wchar_t wcstr[100];
 
   vout(wcstr, 100, format3, L"ONE", 2L, L"THREE");
   printf("%ls\n", wcstr);
   vout(wcstr, 100, format5, L"ONE", 2L, L"THREE", 4L, L"FIVE");
   printf("%ls\n", wcstr);
   return 0;
 
   /************************************************************
      The output should be similar to:
 
      ONE  2  THREE
      ONE  2  THREE  4  FIVE
   ************************************************************/
}

Related Information

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