6.23.63 wprintf Function

Prints formatted text to the stdout stream, using a wide format string.

Attention: This function is implemented only by MPLAB XC32 C compilers.

Include

<wchar.h>

Prototype

int wprintf(const wchar_t * restrict format, ...);

Arguments

format
format control wide string
...
optional arguments; see “Remarks”

Return Value

Returns number of characters generated or a negative number if an error occurs.

Remarks

The function writes formatted output to the stdout stream. The arg argument must be initialized by the va_start macro.

The format string is composed of text, which is copied unchanged to the output stream, and conversion specifications, which begin with the % wide character and which fetch zero or more of the optional arguments, converting them according to the corresponding conversion specifier when required, and then writing the result to the output stream. If the are less arguments than required by the conversion specifications, the output is undefined. If there are more arguments than required by the conversion specifications, the additional arguments are unused.

Each conversion specification begins with a percent sign followed by optional fields and a required type as shown here:

%[flags][width][.precision][length]specifier

The flags modify the meaning of the conversion specification. The are described in the following table.

Flag Meaning
- Left justify the conversion result within a given field width.
0 Use 0 for the pad character instead of space (which is the default) for d, i, o, u, x, X, a, A, e, E, f, F, g, and G conversions, except when converting an infinity or NaN. If the 0 and - flags both appear, the 0 flag is ignored. For d, i, o, u, x, andX conversions, if a precision is specified, the 0 flag is ignored. For other conversions, the behavior is undefined.
+ Write a plus sign for positive signed conversion results.
space Prefix a space when the first wide character of a conversion result does not include a sign (+ or -) or if a signed conversion results in no wide characters. If the space and + flags both appear, the space flag is ignored.
# Convert the result to an alternative form. Specifically, for o conversions, it increases the precision, ensuring the first digit of the result is a zero, if and only if necessary. (If the value and precision are both 0, a single 0 is printed). For x (or X) conversions, 0x (or 0X) is prefixed to nonzero results. For a, A, e, E, f, F, g, and G conversions, the result of converting a floating-point number always contains a decimal-point wide character, even if no digits follow it. For g and G conversions, trailing zeros are not removed from the result. For other conversions, the behavior is undefined.

The width field indicated how many characters the value should consume. If the converted value has fewer characters than the field width, it is padded with spaces on the left, unless the left adjustment flag - has been used.

If the asterisk, *, is used instead of a decimal number, the int argument before the argument to be converted will be used for the field width. If the result is less than the field width, pad characters will be used on the left to fill the field. If the result is greater than the field width, the field is expanded to accommodate the value without padding.

The precision field indicates:
  • the minimum number of digits to appear for the d, i, o, u, x, and X conversions
  • the number of digits to appear after the decimal-point character for a, A, e, E, f, and F conversions
  • the maximum number of significant digits for the g and G conversions
  • the maximum number of bytes to be written for s conversions
The precision takes the form of a period, ., followed either by an asterisk, * or by an optional decimal integer. If neither the * or integer is specified, the precision is assumed to be zero. If the asterisk, *, is used instead of a decimal number, the int argument before the argument to be converted will be used for the precision. If a precision appears with any other conversion specifier, the behavior is undefined.

The length modifier specifies the size of the argument as described in the following table. Their use with other conversion specifiers results in undefined behavior.

Modifier Meaning
h  When used with d, i, o, u, x, or X conversion specifiers, converts the argument value to a short int or unsigned short int.
h When used with the n conversion specifier, indicates that the pointer argument points to a short int.
hh When used with d, i, o, u, x, or X conversion specifiers, converts the argument value to a signed char or unsigned char.
j When used with d, i, o, u, x, or X conversion specifiers, indicates that the argument value is aintmax_t or uintmax_t.
j When used with the n conversion specifier, indicates that the pointer points to a intmax_t.
l When used with d, i, o, u, x, or X conversion specifiers, converts the argument value to a long int or unsigned long int.
l When used with the n conversion specifier, indicates that the pointer points to a long int.
l When used with the c conversion specifier, indicates that the argument value is a wide character (wint_t type).
l When used with the s conversion specifier, indicates that the argument value is a wide string (wchar_t type).
l When used the e, E, f, F, g, G, has no effect.
ll When used with d, i, o, u, x, or X conversion specifiers, indicates that the argument value is a long long int or unsigned long long int.
ll When used with the n conversion specifier, indicates that the pointer points to a long long int.
ll

MPLAB XC16 or XC-DSC: When used with the s conversion specifier, indicates that the string pointer is an __eds__ pointer.

Other compilers: The modifier is silently ignored.
L When used the a, A, e, E, f, F, g, G conversion specifier, indicates the argument value is a long double.
t When used with d, i, o, u, x, or X conversion specifiers, indicates that the argument value is a ptrdiff_t or the corresponding unsigned integer type.
t When used with the n conversion specifier, indicates that the pointer points to a ptrdiff_t.
z When used with d, i, o, u, x, or X conversion specifiers, indicates that the argument value is a size_t_t or the corresponding signed integer type.
z When used with the n conversion specifier, indicates that the pointer points to a size_t_t.

The conversion specifiers specify the type of conversion to be applied to the argument and how that value should be printed, as described in the following table.

Specifier Argument value type Printing notes
a, A double Converted to the general form [−]0xh.hhhhp±d, where there is one hexadecimal digit before the decimal-point wide character and the number of hexadecimal digits after it is equal to the precision.
c char or wint_t

The integer argument value is converted to a wide character (as if by calling btowc) and the resulting wide character is written.

When the l modifier is present, the wint_t argument is converted to wchar_t and written.
d signed int Converted to signed decimal with the general form [−]dddd. The precision specifies the minimum number of digits to appear.
e, E double Converted to the general form [−]d.ddde±dd, where there is one digit before the decimal-point wide character and the number of digits after it is equal to the precision, which is 6 if that is missing. If the precision is zero and the # flag is not specified, no decimal-point wide character appears.
f, F double Converted to decimal notation using the general form [−]ddd.ddd, where the number of digits after the decimal-point character is equal to the precision specification, which is 6 if that is missing. If the precision is zero and the # flag is not specified, no decimal-point wide character appears.
g, G double takes the form of e, f, or E or F in the case of G, as appropriate
i signed int Converted to signed decimal with the general form [−]dddd. The precision specifies the minimum number of digits to appear.
n an integer pointer The number of wide characters written so far is written to the object pointed to by the pointer. No wide characters are printed.
o unsigned int Converted to unsigned octal with the general form dddd. The precision specifies the minimum number of digits to appear
p void * Printed as the value (address) held by the pointer.
s char array, or wchar_t array

A string contain multibyte characters that are converted to wide characters (as if by calling mbrtowc) and written. No more wide characters than the specified precision are printed. If no precision has been specified or is greater than the number of converted characters, a null wide character will be written.

When the l modifier is present, wide characters from the array are written. No more wide characters than the specified precision are printed. If no precision has been specified or is greater than the number of converted characters, a null wide character will be written.
u unsigned int Converted to unsigned decimal with the general form dddd. The precision specifies the minimum number of digits to appear
x unsigned int Converted to unsigned hexadecimal notation with the general form dddd. The letters abcdef are printed for digits above 9. The precision specifies the minimum number of digits to appear
X unsigned int Converted to unsigned hexadecimal notation with the general form dddd. The letters ABCDEF are printed for digits above 9. The precision specifies the minimum number of digits to appear
% No argument is converted and a % wide character is printed.

Example 

#include <wchar.h>
#include <stdio.h>

int main(void)
{
  int y;
  wchar_t s[]=L"Print this string";
  int x = 1;
  wchar_t a = L'\n';

  y = wprintf(L"%ls %d time%lc", s, x, a);

  printf("Number of characters printed to wide string buffer = %d\n", y);
}

Example Output 

Print this string 1 time
Number of characters printed to wide string buffer = 25