C++ <cwchar> - fwprintf() Function

The C++ <cwchar> fwprintf() function writes the C wide string pointed by format to the stream. If format includes format specifiers (sub-sequences beginning with %), the additional arguments following format are formatted and inserted in the resulting string replacing their respective specifiers.

After the format parameter, the function expects additional arguments at least as many as the number of format specifiers in the format string.

The multibyte characters in file are interpreted as wide characters as if wcrtomb() function is called to convert each wide character (using the stream's internal mbstate_t object).

Note: This function is wide character equivalent of fprintf() function.

Syntax

int fwprintf ( FILE * stream, const wchar_t* format, ... );

Parameters

stream Specify a pointer to a FILE object that specifies an output stream.

format

Specify the format wide string. The possible values of %specifier are:

%specifier	Description
%%	Returns a percent sign
%c	Character
%d	Signed decimal integer (negative, zero or positive)
%i	Signed decimal integer (negative, zero or positive)
%u	Unsigned decimal number (zero or positive)
%e	Scientific notation using a lowercase (e.g. 1.2e+3)
%E	Scientific notation using a uppercase (e.g. 1.2E+3)
%f	Decimal floating point, lowercase
%F	Decimal floating point, uppercase
%g	Shorter of %e and %f
%G	Shorter of %E and %f
%p	Pointer address
%o	Unsigned octal
%s	String of characters
%x	Unsigned hexadecimal integer (lowercase letters)
%X	Unsigned hexadecimal integer (uppercase letters)
%a	Hexadecimal floating point (lowercase letters)
%A	Hexadecimal floating point (uppercase letters)
%n	Nothing is printed. 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. The corresponding argument must be a pointer to a signed int. The specification may not contain any flag, width, or precision. See the example below.

Additional format values can be placed between the % and the specifier (e.g. %.3f) also known as sub-specifier. These sub-specifier are:

Flags:
- - : Left-justify within the given field width. Right justification is the default.
- + : Prefix positive numbers with a plus sign +. By default only negative are prefixed with a negative sign.
- (space) : If no sign is going to be written, a blank space is inserted before the value.
- # : When used with o, x or X specifiers the value is preceded with 0, 0x or 0X respectively for values different than zero.
  When used with a, A, e, E, f, F, g or G specifiers, it forces the written output to contain a decimal point even if no more digits follow. By default, no decimal point is written if no digits follow.
- 0 : Only left-pads numbers with zeros instead of spaces when padding is specified.
Width: An integer or * that specifies minimum field width. In the case when * is used, the width is not specified in the format string, but as an additional integer value argument preceding the argument that has to be formatted. If the value to be printed is shorter than the width, the result is padded with blank spaces. (Note: This is the minimum width: The value is never truncated.)
Precision: Period . followed by an integer or *. In the case when * is used, the precision is not specified in the format string, but as an additional integer value argument preceding the argument that has to be converted. If the value of this argument is negative, it is ignored. If neither a number nor * is used, the precision is taken as zero.
- For d, i, o, u, x and X specifiers: It signifies the minimum number of digits.
- For a, A, e, E, f and F specifiers: It signifies the number of decimal digits.
- For g and G specifiers: It signifies the maximum number of significant digits.
- For s specifier: It specifies a cutoff point, setting maximum number of characters.
Length: Modifies the length of the data type. For example - %i is used for signed decimal integer, with ll length sub-specifier it becomes %lli which can be used for long long int data type. Here is the complete list of length sub-specifier.

Note: If multiple additional format values are provided, they must be in %[flags][width][.precision][length]specifier order.

... (additional arguments) Depending on the format string, a sequence of additional arguments should be passed in the function, each containing a value to replace a format specifiers in the format string. Number of arguments should be at least equal to the number of format specifiers in the format string. Additional arguments will be ignored by this function.

Return Value

Returns the total number of characters written on success (not including the terminating null character). If a writing error occurs, sets the error indicator ferror() and a negative number is returned. If a multibyte character encoding error occurs while writing wide characters, errno is set to EILSEQ and a negative number is returned.

Example: Different specifiers

Lets assume that we have a file called test.txt in the current working directory. In the example below, the fwprintf() function is used to write the formatted string in this file.

#include <cstdio>
#include <cwchar>
 
int main (){
  //open the file in write and read mode
  FILE *pFile = fopen("test.txt", "w+");

  fwprintf(pFile, L"Characters: %c %c \n", 'b', 66);
  fwprintf(pFile, L"Decimals: %d %i \n", 200, 300);
  fwprintf(pFile, L"More Decimals: %ld %li \n", 20000L, 30000L);
  fwprintf(pFile, L"Octals: %o %#o \n", 100, 100);
  fwprintf(pFile, L"Hexadecimals: %x %#x %X %#X \n", 100, 100, 100, 100);
  fwprintf(pFile, L"Strings: %s \n", "Hello");
  fwprintf(pFile, L"Scientific notation: %e %E \n", 123.45, 123.45);
  fwprintf(pFile, L"Floats: %2.0f %2.2f %2.4f \n", 3.1416, 3.1416, 3.1416);
  fwprintf(pFile, L"Positive signed number = %+.2f \n", 3.1416);
  fwprintf(pFile, L"Padded number = %05d \n", 89);
  fwprintf(pFile, L"Number with Width = %*d \n", 5, 89);

  //set the position to the start
  rewind(pFile);

  //display the content of the file
  wint_t wc = fgetwc(pFile);
  while (wc != WEOF) {
    putwchar(wc);
    wc = fgetwc(pFile);
  }

  //close the file
  fclose (pFile);

  return 0;
}

The output of the above code will be:

Characters: b B 
Decimals: 200 300 
More Decimals: 20000 30000 
Octals: 144 0144 
Hexadecimals: 64 0x64 64 0X64 
Strings: Hello 
Scientific notation: 1.234500e+02 1.234500E+02 
Floats:  3 3.14 3.1416 
Positive signed number = +3.14 
Padded number = 00089 
Number with Width =    89

Example: Format date string

In the example below, this function is used to write the formatted date string in the stream.

#include <cstdio>
#include <cwchar>
 
int main (){
  //open the file in write and read mode
  FILE *pFile = fopen("test.txt", "w+");

  int year =  2015;
  int month = 5;
  int day = 1;
  
  //each format specifier specifies padding 
  //with 0 and width of the field
  fwprintf(pFile, L"Date is: %04d-%02d-%02d", year, month, day);
  
  //set the position to the start
  rewind(pFile);

  //display the content of the file
  wint_t wc = fgetwc(pFile);
  while (wc != WEOF) {
    putwchar(wc);
    wc = fgetwc(pFile);
  }

  //close the file
  fclose (pFile);

  return 0;
}

The output of the above code will be:

Date is: 2015-05-01

Example: String specifiers

Consider one more example to see how to use string specifiers with a given character/wide string.

#include <cstdio>
#include <cwchar>
 
int main (){
  //open the file in write and read mode
  FILE *pFile = fopen("test.txt", "w+");

  char x[] = "catfish";
  wchar_t y[] = L"many catfishes";

  fwprintf(pFile, L"[%s]\n", x);            //standard string
  fwprintf(pFile, L"[%10s]\n", x);          //right-justified with spaces
  fwprintf(pFile, L"[%*s]\n", 10, x);       //right-justified with spaces
  fwprintf(pFile, L"[%-10s]\n", x);         //left-justified with spaces
  fwprintf(pFile, L"[%-*s]\n", 10, x);      //left-justified with spaces
  fwprintf(pFile, L"[%10.8ls]\n",  y);      //right-justified (8 characters cutoff)
  fwprintf(pFile, L"[%-10.8ls]\n", y);      //left-justified (8 characters cutoff)
  fwprintf(pFile, L"[%-*.*ls]\n", 10, 8, y);//left-justified (8 characters cutoff)

  //set the position to the start
  rewind(pFile);

  //display the content of the file
  wint_t wc = fgetwc(pFile);
  while (wc != WEOF) {
    putwchar(wc);
    wc = fgetwc(pFile);
  }

  //close the file
  fclose (pFile);

  return 0;
}

The output of the above code will be:

[catfish]
[   catfish]
[   catfish]
[catfish   ]
[catfish   ]
[  many cat]
[many cat  ]
[many cat  ]

Length sub-specifier

	Specifiers
length	d i	u o x X	f F e E g G a A	c	s	p	n
(none)	int	unsigned int	double	int	char*	void*	int*
hh	signed char	unsigned char					signed char*
h	short int	unsigned short int					short int*
l	long int	unsigned long int	double	wint_t	wchar_t*		long int*
ll	long long int	unsigned long long int					long long int*
j	intmax_t	uintmax_t					intmax_t*
z	size_t	size_t					size_t*
t	ptrdiff_t	ptrdiff_t					ptrdiff_t*
L			long double

See <cinttypes> for the specifiers for extended types.

❮ C++ <cwchar> Library