◆ PrintfW()

int Chusov::String::PrintfW	(	const wchar_t *restrict	pszFormat,
			...
	)

noexcept

Loads data from the locations, defined by a variable arguments, converts it to wide string equivalents and writes the results to stdout.

Parameters

[in]	pszFormat	is a pointer to a zero terminated wide string defining how to interpret data, passed as additional parameters, during the construction of the output. See remarks below.
	...	constitute an optional set of additional parameters to build the formatted output according to pszFormat.

Returns: On success the function returns a number of wide characters of the output not counting the terminating zero. If an error occurs the function returns a negative value. If the format string and arguments do not correspond to each other the behaviour is generally unpredicted and may cause memory access violations or stack corruptions. Although many of these cases are detected by the function which fails and sets errno to EINVAL.

The function implements the behaviour of the standard C wprintf function with full accordance to ISO/IEC 9899:1999 (aka C99) and ISO/IEC 9899:2011 (aka C11) with some standard-compatible extensions specific to the chsvlib library.

The format string consists on ordinary characters (except for '') and conversion specifications. The ordinary characters are copied to the output "as-is" while conversion specifications are replaced with some other strings formed according to the specific rules described below.

Each conversion specification has the following syntax:

"%[flags][width][.][precision][length]<type>"

Zero or more flags (in any order) modify a meaning of the conversion specification:

-	Left-justify within the given field width; Right justification is the default.
+	Forces to precede the result with a plus or minus sign (+ or -) even for nonnegative numbers. By default, only negative numbers are preceded with a - sign.
space	If no sign is going to be written, a blank space is inserted before the value. If both '+' and space flags are specified the last one is ignored.
#	For o type specifier the precision is incremented and '0' symbol is added on the left of the octal number to force the first digit of the printed number to be zero. If the written number has already the first '0' symbol (e.g. as a result of 0 flag) then these modifications are not performed. For x and X type specifiers nonzero values are prefixed with '0x' or '0X' respectively. For a, A, e, E, f, F it forces the written output to contain a decimal point even if no more digits follow. By default, if no digits follow, no decimal point is written. For g or G trailing zeros are not removed from the result.
0	For d, i, o, u, x, X, a, A, e, E, f, F, g and G conversions leading zeros are used to pad the string form of the corresponding parameter to a width (rather than performing space padding). The zeros follow any sign or base indication for the number. The flag is ignored for NaNs. If left alignment '-' flag is also specified, the '0' flag is ignored. For integer types d, i, u, o, x, X the flag is ignored if a precision is also specified.

An optional numeric width specifies a minimum space for the output, in wide characters, used in the resulting string. If the string, corresponding to the conversion specification has fewer characters than the width, the string is padded with spaces or zeros (see '0' flag) on the left or on the right (if the left alignment '-' flag is set). A number of padding symbols is determined as a difference between the width and the actual length of the string corresponding to the conversion specification. If the width is less than the length of the actual string the last one is not ever truncated. The width can take a form of a decimal integer or of an asterisk ('*'). In the latter case the numeric value of width is taken from an additional parameter of type int placed before the actual parameter to be converted to a string. If the precision is also of an asterisk form, the width parameter is placed before the precision parameter.

An optional precision field have context-depending meaning.

For d, i, u, o, x and X type specifications the precision gives a minimum number of digits to appear in the resulting string causing a converted number to be padded with zeros on the left. The default precision is 1.

For a, A, e, E, f and F type specifiers the precision gives a number of digits to appear after the decimal point character padding zeros to the end. For e, E, f and F type specifiers the default precision is 6. For a and A the default precision is calculated as \(\left\lceil \frac{LDBL\_MANT\_DIG}{\log_{FLT\_RADIX}{LDBL\_MANT\_DIG}} \right \rceil\)

For g and G the precision specifies a maximum number of significant digits. If the precision is zero it is taken as 1.

For s and S the precision specifies a maximum number of wide characters of the converted string to be written to the output. The default precision is INT_MAX.

The precision must be specified with the period ('.') symbol on its left. The numeric value of the precision is specified using decimal digits or by an asterisk ('*') with the corresponding int parameter preceding the data for conversion. If only the period symbol is specified for the precision in the conversion specification the precision is taken as zero.

A length modifier specifies a byte size of an argument in context-depending way as shown in the following table.

A type specifier is mandatory and is used to specify the type of the conversion to be applied.

The following table shows how different length-size combinations affect on a type of a parameter the function expects on input. Notice that the standard C rules are applied when passing variable parameters. For instance char and short values are cast to int, although the function considers only those number of input bytes that correspond to the length specifier.

length\type	d,i	u, o, x, X	f, F, e, E, g,G, a, A	p	n¹	c	s	C³	S³
none	signed int	unsigned int	double	void*	int*	char	char*	char	char*
hh¹	signed char	unsigned char	N/A	N/A	signed char*	N/A	N/A	N/A	N/A
h	short int	unsigned short int	N/A	N/A	short int*	char	char*	char	char*
l	long int	unsigned long int	double (no effect of l)	N/A	long int*	wint_t	wchar_t*	wint_t	wchar_t*
L	N/A	N/A	long double	N/A	N/A	N/A	N/A	N/A	N/A
ll	long long int	unsigned long long int	N/A	N/A	long long int*	N/A	N/A	N/A	N/A
j¹	intmax_t	uintmax_t	N/A	N/A	intmax_t*	N/A	N/A	N/A	N/A
z¹	size_t	size_t	N/A	N/A	size_t*	N/A	N/A	N/A	N/A
t¹	ptrdiff_t	ptrdiff_t	N/A	N/A	ptrdiff_t*	N/A	N/A	N/A	N/A
I32²	int32_t	uint32_t	N/A	N/A	N/A	N/A	N/A	N/A	N/A
I64²	int64_t	uint64_t	N/A	N/A	N/A	N/A	N/A	N/A	N/A
I²	ptrdiff_t	size_t	N/A	N/A	N/A	N/A	N/A	N/A	N/A
w²	N/A	N/A	N/A	N/A	N/A	wint_t	wchar_t*	wint_t	wchar_t*
T³	N/A	N/A	N/A	N/A	N/A	wchar_t	wchar_t*	char	char*
TT³	N/A	N/A	N/A	N/A	N/A	char	char*	wint_t	wchar_t*

¹These conversions are specified by the ISO/IEC 9899:1999 (aka C99) and ISO/IEC 9899:2011 (aka C11) standards but not implemented in MS C libraries.

²These conversions are provided by MS C libraries but do not conform the standards.

³These conversions are chsvlib only extensions.

The following table shows how the function interprets input data when it is converted to a string:

Type specifier	Output
d or i	Signed decimal integer.
u	Unsigned decimal integer.
o	Unsigned octal integer.
x	Unsigned hexadecimal integer in lowercase.
X	Unsigned hexadecimal integer in uppercase.
f	Decimal floating point number according notation: [-]ddd.ddd, [-]inf, [-]nan.
F	Decimal floating point number according notation: [-]ddd.ddd, [-]INF, [-]NAN.
e	Floating point number in scientific notation: [-]d.ddde[ \(\pm\)]dd, [-]inf, [-]nan.
E	Floating point number in scientific notation: [-]d.dddE[ \(\pm\)]dd, [-]INF, [-]NAN.
g	Corresponds to f if -4 <= exp < precision, otherwise corresponds to e.¹
G	Corresponds to F if -4 <= exp < precision, otherwise corresponds to E.¹
a	Hexadecimal floating point number written in form [-]0xh.hhhhp \(\pm\) d.
A	Hexadecimal floating point number written in form [-]0xh.hhhhP \(\pm\) d.
c or C	Wide or multibyte character
s or S	Wide or multibyte string
p	A pointer. Parameter is interpreted as `uintptr_t` and converted to a string as for 'X' conversion specifier with 2sizeof(void) precision.
n	Nothing is passed as output. A parameter corresponding to the specifier is a pointer receiving a number of characters written so far.
%	A pair of percent symbols in the format string are replaced with a single percent symbol. No parameters are consumed.

See also: PrintfA;
PrintfW_s;
vPrintfW.

Examples: chsvmem\AllocateAndFormatStringByTagsW.c.