C++ vswprintf()

The vswprintf() function in C++ is used to write a formatted wide string to a wide string buffer.

The vswprintf() function is defined in <cwchar> header file.

vswprintf() prototype

int vswprintf( wchar_t* buffer, size_t buf_size, const wchar_t* format, va_list vlist );

The vswprintf() function writes the wide string pointed to by format to the wide string buffer. A maximum of (buf_size-1) wide characters are written to buffer which is followed by a null wide character.

The wide string format may contain format specifiers starting with % which are replaced by the values of variables that are passed as a list vlist.


vswprintf() Parameters

  • buffer: Pointer to a wide string buffer to write the result.
  • buf_size: Maximum number of wide characters to write including the terminating null wide character.
  • format: A pointer to a null terminated wide string that is written to buffer. It consists of characters along with optional format specifiers starting with %. The format specifiers are replaced by the values of respective variables that follows format.
    The format specifier has the following parts:
    • A leading % sign
    • Flags: Optional one or more flags that modifies the conversion behavior.
      • - : Left justify the result within the field. By default it is right justified.
      • + : The sign of the result is attached to the beginning of the value, even for positive results.
      • Space: If there is no sign, a space is attached to the beginning of the result.
      • # : An alternative form of the conversion is performed.
      • 0 : It is used for integer and floating point number. Leading zeros are used to pad the numbers instead of space.
    • Width: An optional * or integer value used to specify minimum width field.
    • Precision : An optional field consisting of a . followed by * or integer or nothing to specify the precision.
    • Length : An optional length modifier that specifies the size of the argument.
    • Specifier: A conversion format specifier. The available format specifiers are as follows:
    Format specifiers
    Format Specifier Description
    % Prints %
    c Writes a single character
    s Writes a character string
    d or i Converts a signed integer to decimal representation
    o Converts an unsigned integer to octal representation
    X or x Converts an unsigned integer to hexadecimal representation
    u Converts an unsigned integer to decimal representation
    F or f Converts floating-point number to the decimal representation
    E or e Converts floating-point number to the decimal exponent notation
    A or a Converts floating-point number to the hexadecimal exponent
    G or g Converts floating-point number to either decimal or decimal exponent notation
    n Returns the number of characters written so far by this call to the function. The result is written to the value pointed to by the argument
    p Writes an implementation defined character sequence defining a pointer.

    So the general format of format specifier is:
    %[flags][width][.precision][length]specifier
  • vlist: A list of arguments containing the data to write.

vswprintf() Return value

  • If successful, the vswprintf() function returns number of wide characters written excluding the terminating null wide character.
  • A negative value is returned if any encoding error occurs or if the number of characters to be generated was equal or greater than buf_size.

Example: How vswprintf() function works?

#include <cwchar>
#include <cstdarg>
#include <clocale>

void write(wchar_t* buffer, size_t buf_size, const wchar_t *fmt, ...)
{
	va_list args;
	va_start(args, fmt);
	vswprintf(buffer, buf_size, fmt, args);
	va_end(args);
}

int main ()
{
	wchar_t str[] = L"\u0684 \u06b1 \u06aa \u06a3 \u0684";
	wchar_t buffer[50];

	setlocale(LC_ALL, "en_US.UTF-8");

	write(buffer, 50, L"Arabic Letters: %ls\n", str);
	wprintf(L"%ls", buffer);

	return 0;
}

When you run the program, the following will be written to example.txt:

Arabic Letters: ڄ ڱ ڪ ڣ ڄ