wchar.h@ 58453

Last change on this file since 58453 was 48674, checked in by vboxsync, 11 years ago
EFI: Export newly imported tinaocore UEFI sources to OSE.
Property svn:eol-style set to `native`
File size: 82.2 KB

Line
1	/** @file
2	Extended multibyte and wide character utilities.
3
4	Within this implementation, multibyte characters are represented using the
5	Unicode UTF-8 encoding and wide characters are represented using the
6	16-bit UCS-2 encoding.
7
8	Unless explicitly stated otherwise, if the execution of a function declared
9	in this file causes copying to take place between objects that overlap, the
10	behavior is undefined.
11
12	The following macros are defined in this file:<BR>
13	@verbatim
14	NULL Actually defined in <sys/EfiCdefs.h>
15	WCHAR_MIN Minimum value of a wide char.
16	WCHAR_MAX Maximum value of a wide char.
17	WEOF Wide char version of end-of-file.
18	@endverbatim
19
20	The following types are defined in this file:<BR>
21	@verbatim
22	size_t Unsigned integer type of the result of the sizeof operator.
23	wchar_t Type of wide characters.
24	wint_t Type capable of holding all wchar_t values and WEOF.
25	mbstate_t Type of object holding multibyte conversion state.
26	struct tm Incomplete declaration of the broken-down time structure.
27	@endverbatim
28
29	The following functions are declared in this file:<BR>
30	@verbatim
31	############### Formatted Input/Output Functions
32	int fwprintf (FILE * __restrict stream,
33	const wchar_t * __restrict format, ...);
34	int fwscanf (FILE * __restrict stream,
35	const wchar_t * __restrict format, ...);
36	int swprintf (wchar_t * __restrict s, size_t n,
37	const wchar_t * __restrict format, ...);
38	int swscanf (const wchar_t * __restrict s,
39	const wchar_t * __restrict format, ...);
40	int vfwprintf (FILE * __restrict stream,
41	const wchar_t * __restrict format, va_list arg);
42	int vfwscanf (FILE * __restrict stream,
43	const wchar_t * __restrict format, va_list arg);
44	int vswprintf (wchar_t * __restrict s, size_t n,
45	const wchar_t * __restrict format, va_list arg);
46	int vswscanf (const wchar_t * __restrict s,
47	const wchar_t * __restrict format, va_list arg);
48	int vwprintf (const wchar_t * __restrict format, va_list arg);
49	int vwscanf (const wchar_t * __restrict format, va_list arg);
50	int wprintf (const wchar_t * __restrict format, ...);
51	int wscanf (const wchar_t * __restrict format, ...);
52
53	################### Input/Output Functions
54	wint_t fgetwc (FILE *stream);
55	wchar_t fgetws (wchar_t __restrict S, int n,
56	FILE * __restrict stream);
57	wint_t fputwc (wchar_t c, FILE *stream);
58	int fputws (const wchar_t * __restrict S,
59	FILE * __restrict stream);
60	int fwide (FILE *stream, int mode);
61	wint_t getwc (FILE *stream);
62	wint_t getwchar (void);
63	wint_t putwc (wchar_t c, FILE *stream);
64	wint_t putwchar (wchar_t c);
65	wint_t ungetwc (wint_t c, FILE *stream);
66
67	################### Numeric Conversions
68	double wcstod (const wchar_t * __restrict nptr,
69	wchar_t ** __restrict endptr);
70	float wcstof (const wchar_t * __restrict nptr,
71	wchar_t ** __restrict endptr);
72	long double wcstold (const wchar_t * __restrict nptr,
73	wchar_t ** __restrict endptr);
74	long int wcstol (const wchar_t * __restrict nptr,
75	wchar_t ** __restrict endptr, int base);
76	long long int wcstoll (const wchar_t * __restrict nptr,
77	wchar_t ** __restrict endptr, int base);
78	unsigned long int wcstoul (const wchar_t * __restrict nptr,
79	wchar_t ** __restrict endptr, int base);
80	unsigned long long int wcstoull (const wchar_t * __restrict nptr,
81	wchar_t ** __restrict endptr, int base);
82
83	####################### String Copying
84	wchar_t wcscpy (wchar_t __restrict s1,
85	const wchar_t * __restrict s2);
86	wchar_t wcsncpy (wchar_t __restrict s1,
87	const wchar_t * __restrict s2, size_t n);
88	wchar_t wmemcpy (wchar_t __restrict s1,
89	const wchar_t * __restrict s2, size_t n);
90	wchar_t wmemmove (wchar_t s1, const wchar_t *s2, size_t n);
91
92	################### String Concatenation
93	wchar_t wcscat (wchar_t __restrict s1,
94	const wchar_t * __restrict s2);
95	wchar_t wcsncat (wchar_t __restrict s1,
96	const wchar_t * __restrict s2, size_t n);
97
98	##################### String Comparison
99	int wcscmp (const wchar_t s1, const wchar_t s2);
100	int wcscoll (const wchar_t s1, const wchar_t s2);
101	int wcsncmp (const wchar_t s1, const wchar_t s2, size_t n);
102	size_t wcsxfrm (wchar_t * __restrict s1,
103	const wchar_t * __restrict s2, size_t n);
104	int wmemcmp (const wchar_t s1, const wchar_t s2, size_t n);
105
106	##################### String Searching
107	wchar_t wcschr (const wchar_t S, wchar_t c);
108	size_t wcscspn (const wchar_t s1, const wchar_t s2);
109	wchar_t wcspbrk (const wchar_t s1, const wchar_t *s2);
110	wchar_t wcsrchr (const wchar_t S, wchar_t c);
111	size_t wcsspn (const wchar_t s1, const wchar_t s2);
112	wchar_t wcsstr (const wchar_t s1, const wchar_t *s2);
113	wchar_t wcstok (wchar_t __restrict s1,
114	const wchar_t * __restrict s2,
115	wchar_t ** __restrict ptr);
116	wchar_t wmemchr (const wchar_t S, wchar_t c, size_t n);
117
118	################### String Manipulation
119	size_t wcslen (const wchar_t *S);
120	wchar_t wmemset (wchar_t S, wchar_t c, size_t n);
121
122	################# Date and Time Conversion
123	size_t wcsftime (wchar_t * __restrict S, size_t maxsize,
124	const wchar_t * __restrict format,
125	const struct tm * __restrict timeptr);
126
127	############# Multibyte <--> Wide Character Conversion
128	wint_t btowc (int c);
129	int wctob (wint_t c);
130	int mbsinit (const mbstate_t *ps);
131
132	####### Restartable Multibyte <--> Wide Character Conversion
133	size_t mbrlen (const char * __restrict S, size_t n,
134	mbstate_t * __restrict ps);
135	size_t mbrtowc (wchar_t * __restrict pwc, const char * __restrict S,
136	size_t n, mbstate_t * __restrict ps);
137	size_t wcrtomb (char * __restrict S, wchar_t wc,
138	mbstate_t * __restrict ps);
139	size_t mbsrtowcs (wchar_t * __restrict dst,
140	const char ** __restrict src, size_t len,
141	mbstate_t * __restrict ps);
142	size_t wcsrtombs (char * __restrict dst,
143	const wchar_t ** __restrict src,
144	size_t len, mbstate_t * __restrict ps);
145	@endverbatim
146
147	@note Properly constructed programs will take the following into consideration:
148	- wchar_t and wint_t may be the same integer type.
149	- WEOF might be a different value than that of EOF.
150	- WEOF might not be negative.
151	- mbstate_t objects are not intended to be inspected by programs.
152
153	Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
154	This program and the accompanying materials are licensed and made available under
155	the terms and conditions of the BSD License that accompanies this distribution.
156	The full text of the license may be found at
157	http://opensource.org/licenses/bsd-license.
158
159	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
160	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
161	**/
162	#ifndef _WCHAR_H
163	#define _WCHAR_H
164	#include <sys/EfiCdefs.h>
165	#include <machine/ansi.h>
166	#include <machine/limits.h>
167	#include <stdarg.h>
168	#include <stdio.h>
169
170	#if defined(_MSC_VER)
171	#pragma warning ( disable : 4142 )
172	#endif
173
174	#ifdef _EFI_SIZE_T_
175	typedef _EFI_SIZE_T_ size_t; /*< Unsigned integer type of the result of the sizeof operator. /
176	#undef _BSD_SIZE_T_
177	#undef _EFI_SIZE_T_
178	#endif
179
180	#ifndef __cplusplus
181	#ifdef _EFI_WCHAR_T
182	/** An integer type capable of representing all distinct codes in the
183	UCS-2 encoding supported by UEFI.
184	**/
185	typedef _EFI_WCHAR_T wchar_t;
186	#undef _BSD_WCHAR_T_
187	#undef _EFI_WCHAR_T
188	#endif
189	#endif
190
191	#ifdef _BSD_MBSTATE_T_
192	/** mbstate_t is an opaque object, that is not an array type, used to keep
193	conversion state during multibyte stream conversions.
194	*/
195	typedef _BSD_MBSTATE_T_ mbstate_t;
196	#undef _BSD_MBSTATE_T_
197	#endif
198
199	#ifdef _EFI_WINT_T
200	/** wint_t is an integer type unchanged by default argument promotions that can
201	hold any value corresponding to members of the extended character set, as
202	well as at least one value that does not correspond to any member of the
203	extended character set: WEOF.
204	*/
205	typedef _EFI_WINT_T wint_t;
206	#undef _BSD_WINT_T_
207	#undef _EFI_WINT_T
208	#endif
209
210	#ifndef WCHAR_MIN
211	/** @{
212	Since wchar_t is an unsigned 16-bit value, it has a minimum value of 0, and
213	a maximum value defined by __USHRT_MAX (65535 on IA processors).
214	*/
215	#define WCHAR_MIN 0
216	#define WCHAR_MAX __USHRT_MAX
217	/@}/
218	#endif
219
220	#ifndef WEOF
221	/** WEOF expands to a constant expression of type wint_t whose value does not
222	correspond to any member of the extended character set. It is accepted
223	(and returned) by several functions, declared in this file, to indicate
224	end-of-file, that is, no more input from a stream. It is also used as a
225	wide character value that does not correspond to any member of the
226	extended character set.
227	*/
228	#define WEOF ((wint_t)-1)
229	#endif
230
231	/* limits of wint_t -- These are NOT specified by ISO/IEC 9899 */
232	#ifndef WINT_MIN
233	#define WINT_MIN _EFI_WINT_MIN /* wint_t */
234	#define WINT_MAX _EFI_WINT_MAX /* wint_t */
235	#endif
236
237	/** Type struct tm is declared here as an incomplete structure type for use as an argument
238	type by the wcsftime function. The full structure declaration is in <time.h>.
239	*/
240	struct tm;
241
242	/* ############### Formatted Input/Output Functions ##################### */
243
244	/** The fwprintf function writes output to the stream pointed to by stream,
245	under control of the wide string pointed to by format that specifies how
246	subsequent arguments are converted for output. If there are insufficient
247	arguments for the format, the behavior is undefined. If the format is
248	exhausted while arguments remain, the excess arguments are evaluated
249	(as always) but are otherwise ignored. The fwprintf function returns
250	when the end of the format string is encountered.
251
252	The format is composed of zero or more directives: ordinary wide characters
253	(not %), which are copied unchanged to the output stream; and conversion
254	specifications, each of which results in fetching zero or more subsequent
255	arguments, converting them, if applicable, according to the corresponding
256	conversion specifier, and then writing the result to the output stream.
257
258	Each conversion specification is introduced by the wide character %. After
259	the %, the following appear in sequence:
260	* Zero or more flags (in any order) that modify the meaning of the
261	conversion specification.
262	* An optional minimum field width. If the converted value has fewer wide
263	characters than the field width, it is padded with spaces (by default)
264	on the left (or right, if the left adjustment flag, described later,
265	has been given) to the field width. The field width takes the form of
266	an asterisk * (described later) or a nonnegative decimal integer.
267	* An optional precision that gives the minimum number of digits to appear
268	for the d, i, o, u, x, and X conversions, the number of digits to
269	appear after the decimal-point wide character for e, E, f, and F
270	conversions, the maximum number of significant digits for the g and G
271	conversions, or the maximum number of wide characters to be written
272	for s conversions. The precision takes the form of a period (.)
273	followed either by an asterisk * (described later) or by an optional
274	decimal integer; if only the period is specified, the precision is
275	taken as zero. If a precision appears with any other conversion
276	specifier, the behavior is undefined.
277	* An optional length modifier that specifies the size of the argument.
278	* A conversion specifier wide character that specifies the type of
279	conversion to be applied.
280
281	As noted above, a field width, or precision, or both, may be indicated by
282	an asterisk. In this case, an int argument supplies the field width or
283	precision. The arguments specifying field width, or precision, or both,
284	must appear (in that order) before the argument (if any) to be converted.
285	A negative field width argument is taken as a - flag followed by a positive
286	field width. A negative precision argument is taken as if the precision
287	were omitted.
288
289	The flag wide characters and their meanings are:<BR>
290	- The result of the conversion is left-justified within the field.
291	(It is right-justified if this flag is not specified.)
292	+ The result of a signed conversion always begins with a plus or minus
293	sign. (It begins with a sign only when a negative value is converted
294	if this flag is not specified.)
295	space If the first wide character of a signed conversion is not a sign, or
296	if a signed conversion results in no wide characters, a space is
297	prefixed to the result. If the space and + flags both appear, the
298	space flag is ignored.
299	# The result is converted to an "alternative form". For o conversion,
300	it increases the precision, if and only if necessary, to force the
301	first digit of the result to be a zero (if the value and precision
302	are both 0, a single 0 is printed). For x (or X) conversion, a
303	nonzero result has 0x (or 0X) prefixed to it. For e, E, f, F, g,
304	and G conversions, the result of converting a floating-point number
305	always contains a decimal-point wide character, even if no digits
306	follow it. (Normally, a decimal-point wide character appears in the
307	result of these conversions only if a digit follows it.) For g and G
308	conversions, trailing zeros are not removed from the result. For
309	other conversions, the behavior is undefined.
310	0 For d, i, o, u, x, X, e, E, f, F, g, and G conversions, leading zeros
311	(following any indication of sign or base) are used to pad to the
312	field width rather than performing space padding, except when
313	converting an infinity or NaN. If the 0 and - flags both appear,
314	the 0 flag is ignored. For d, i, o, u, x, and X conversions, if a
315	precision is specified, the 0 flag is ignored. For other conversions,
316	the behavior is undefined.
317
318	The length modifiers and their meanings are:<BR>
319	hh Specifies that a following d, i, o, u, x, or X conversion specifier
320	applies to a signed char or unsigned char argument (the argument
321	will have been promoted according to the integer promotions, but its
322	value shall be converted to signed char or unsigned char before
323	printing); or that a following n conversion specifier applies to a
324	pointer to a signed char argument.
325	h Specifies that a following d, i, o, u, x, or X conversion specifier
326	applies to a short int or unsigned short int argument (the argument
327	will have been promoted according to the integer promotions, but its
328	value shall be converted to short int or unsigned short int before
329	printing); or that a following n conversion specifier applies to a
330	pointer to a short int argument.
331	l (ell) Specifies that a following d, i, o, u, x, or X conversion
332	specifier applies to a long int or unsigned long int argument;
333	that a following n conversion specifier applies to a pointer to a
334	long int argument; that a following c conversion specifier
335	applies to a wint_t argument; that a following s conversion
336	specifier applies to a pointer to a wchar_t argument; or has no
337	effect on a following e, E, f, F, g, or G conversion specifier.
338	ll (ell-ell) Specifies that a following d, i, o, u, x, or X conversion
339	specifier applies to a long long int or unsigned long long int
340	argument; or that a following n conversion specifier applies
341	to a pointer to a long long int argument.
342	j Specifies that a following d, i, o, u, x, or X conversion specifier
343	applies to an intmax_t or uintmax_t argument; or that a following
344	n conversion specifier applies to a pointer to an intmax_t argument.
345	z Specifies that a following d, i, o, u, x, or X conversion specifier
346	applies to a size_t or the corresponding signed integer type
347	argument; or that a following n conversion specifier applies to a
348	pointer to a signed integer type corresponding to size_t argument.
349	t Specifies that a following d, i, o, u, x, or X conversion specifier
350	applies to a ptrdiff_t or the corresponding unsigned integer type
351	argument; or that a following n conversion specifier applies to a
352	pointer to a ptrdiff_t argument.
353	L Specifies that a following a, A, e, E, f, F, g, or G conversion
354	specifier applies to a long double argument.
355
356	If a length modifier appears with any conversion specifier other than as
357	specified above, the behavior is undefined.
358
359	The conversion specifiers and their meanings are:<BR>
360	d,i The int argument is converted to signed decimal in the
361	style [-]dddd. The precision specifies the minimum number of digits
362	to appear; if the value being converted can be represented in fewer
363	digits, it is expanded with leading zeros. The default precision
364	is 1. The result of converting a zero value with a precision of
365	zero is no wide characters.
366	o,u,x,X The unsigned int argument is converted to unsigned octal (o),
367	unsigned decimal (u), or unsigned hexadecimal notation (x or X) in
368	the style dddd; the letters abcdef are used for x conversion and
369	the letters ABCDEF for X conversion. The precision specifies the
370	minimum number of digits to appear; if the value being converted
371	can be represented in fewer digits, it is expanded with leading
372	zeros. The default precision is 1. The result of converting a zero
373	value with a precision of zero is no wide characters.
374	f,F A double argument representing a floating-point number is converted
375	to decimal notation in the style [-]ddd.ddd, where the number of
376	digits after the decimal-point wide character is equal to the
377	precision specification. If the precision is missing, it is taken
378	as 6; if the precision is zero and the # flag is not specified, no
379	decimal-point wide character appears. If a decimal-point wide
380	character appears, at least one digit appears before it. The value
381	is rounded to the appropriate number of digits.<BR>
382	A double argument representing an infinity is converted to [-]inf.
383	A double argument representing a NaN is converted to [-]nan.
384	The F conversion specifier produces INF or NAN instead
385	of inf or nan, respectively.
386	e,E A double argument representing a floating-point number is converted
387	in the style [-]d.ddd e +/- dd, where there is one digit (which is
388	nonzero if the argument is nonzero) before the decimal-point wide
389	character and the number of digits after it is equal to the
390	precision; if the precision is missing, it is taken as 6; if the
391	precision is zero and the # flag is not specified, no decimal-point
392	wide character appears. The value is rounded to the appropriate
393	number of digits. The E conversion specifier produces a number with
394	E instead of e introducing the exponent. The exponent always
395	contains at least two digits, and only as many more digits as
396	necessary to represent the exponent. If the value is zero, the
397	exponent is zero. A double argument representing an infinity or NaN
398	is converted in the style of an f or F conversion specifier.
399	g,G A double argument representing a floating-point number is converted
400	in style f or e (or in style F or E in the case of a G conversion
401	specifier), depending on the value converted and the precision.
402	Let P equal the precision if nonzero, 6 if the precision is
403	omitted, or 1 if the precision is zero. Then, if a conversion with
404	style E would have an exponent of X:
405	- if P > X = -4, the conversion is with style f (or F) and
406	precision P - (X + 1).
407	- otherwise, the conversion is with style e (or E) and
408	precision P - 1.
409	Finally, unless the # flag is used, any trailing zeros are removed
410	from the fractional portion of the result and the decimal-point
411	wide character is removed if there is no fractional portion
412	remaining. A double argument representing an infinity or NaN is
413	converted in the style of an f or F conversion specifier.
414	c If no l length modifier is present, the int argument is converted
415	to a wide character as if by calling btowc and the resulting wide
416	character is written. If an l length modifier is present, the
417	wint_t argument is converted to wchar_t and written.
418	s If no l length modifier is present, the argument shall be a pointer
419	to the initial element of a character array containing a multibyte
420	character sequence beginning in the initial shift state. Characters
421	from the array are converted as if by repeated calls to the mbrtowc
422	function, with the conversion state described by an mbstate_t
423	object initialized to zero before the first multibyte character is
424	converted, and written up to (but not including) the terminating
425	null wide character. If the precision is specified, no more than
426	that many wide characters are written. If the precision is not
427	specified or is greater than the size of the converted array, the
428	converted array shall contain a null wide character.<BR>
429	If an l length modifier is present, the argument shall be a pointer
430	to the initial element of an array of wchar_t type. Wide characters
431	from the array are written up to (but not including) a terminating
432	null wide character. If the precision is specified, no more than
433	that many wide characters are written. If the precision is not
434	specified or is greater than the size of the array, the array
435	shall contain a null wide character.
436	p The argument shall be a pointer to void. The value of the pointer
437	is converted to a sequence of printing wide characters, in an
438	implementation-defined manner.
439	n The argument shall be a pointer to signed integer into which is
440	written the number of wide characters written to the output stream
441	so far by this call to fwprintf. No argument is converted, but one
442	is consumed. If the conversion specification includes any flags, a
443	field width, or a precision, the behavior is undefined.
444	% A % wide character is written. No argument is converted. The
445	complete conversion specification is %%.
446
447
448	@param[in] stream An open File specifier to which the output is sent.
449	@param[in] format A wide character sequence containing characters
450	to be copied unchanged, and conversion specifiers
451	which convert their associated arguments.
452	@param ... Variable number of parameters as required by format.
453
454	@return The fwprintf function returns the number of wide characters
455	transmitted, or a negative value if an output or encoding error
456	occurred.
457	**/
458	int fwprintf(FILE * __restrict stream, const wchar_t * __restrict format, ...);
459
460	/** The fwscanf function reads input from the stream pointed to by stream,
461	under control of the wide string pointed to by format that specifies
462	the admissible input sequences and how they are to be converted for
463	assignment, using subsequent arguments as pointers to the objects to
464	receive the converted input. If there are insufficient arguments for
465	the format, the behavior is undefined. If the format is exhausted while
466	arguments remain, the excess arguments are evaluated (as always) but are
467	otherwise ignored.
468
469	The format is composed of zero or more directives: one or more white-space
470	wide characters, an ordinary wide character (neither % nor a white-space
471	wide character), or a conversion specification. Each conversion
472	specification is introduced by the wide character %. After the %, the
473	following appear in sequence:
474	- An optional assignment-suppressing wide character *.
475	- An optional decimal integer greater than zero that specifies the
476	maximum field width (in wide characters).
477	- An optional length modifier that specifies the size of the receiving object.
478	- A conversion specifier wide character that specifies the type of
479	conversion to be applied.
480
481	The fwscanf function executes each directive of the format in turn. If a
482	directive fails, as detailed below, the function returns. Failures are
483	described as input failures (due to the occurrence of an encoding error
484	or the unavailability of input characters), or matching failures
485	(due to inappropriate input).
486
487	A directive composed of white-space wide character(s) is executed by
488	reading input up to the first non-white-space wide character (which remains
489	unread), or until no more wide characters can be read.
490
491	A directive that is an ordinary wide character is executed by reading the
492	next wide character of the stream. If that wide character differs from the
493	directive, the directive fails and the differing and subsequent wide
494	characters remain unread. Similarly, if end-of-file, an encoding error, or
495	a read error prevents a wide character from being read, the directive fails.
496
497	A directive that is a conversion specification defines a set of matching
498	input sequences, as described below for each specifier. A conversion
499	specification is executed in the following steps:
500	- Input white-space wide characters (as specified by the iswspace
501	function) are skipped, unless the specification includes
502	a [, c, or n specifier.
503	- An input item is read from the stream, unless the specification
504	includes an n specifier. An input item is defined as the longest
505	sequence of input wide characters which does not exceed any specified
506	field width and which is, or is a prefix of, a matching input sequence.
507	The first wide character, if any, after the input item remains unread.
508	If the length of the input item is zero, the execution of the directive
509	fails; this condition is a matching failure unless end-of-file, an
510	encoding error, or a read error prevented input from the stream, in
511	which case it is an input failure.
512	- Except in the case of a % specifier, the input item (or, in the case of
513	a %n directive, the count of input wide characters) is converted to a
514	type appropriate to the conversion specifier. If the input item is not
515	a matching sequence, the execution of the directive fails: this
516	condition is a matching failure. Unless assignment suppression was
517	indicated by a *, the result of the conversion is placed in the object
518	pointed to by the first argument following the format argument that has
519	not already received a conversion result. If this object does not have
520	an appropriate type, or if the result of the conversion cannot be
521	represented in the object, the behavior is undefined.
522
523	The length modifiers and their meanings are:<BR>
524	hh Specifies that a following d, i, o, u, x, X, or n conversion
525	specifier applies to an argument with type pointer to signed char
526	or unsigned char.
527	h Specifies that a following d, i, o, u, x, X, or n conversion
528	specifier applies to an argument with type pointer to short int
529	or unsigned short int.
530	l (ell) Specifies that a following d, i, o, u, x, X, or n conversion
531	specifier applies to an argument with type pointer to long int or
532	unsigned long int; that a following e, E, f, F, g, or G conversion
533	specifier applies to an argument with type pointer to double; or
534	that a following c, s, or [ conversion specifier applies to an
535	argument with type pointer to wchar_t.
536	ll (ell-ell) Specifies that a following d, i, o, u, x, X, or n conversion
537	specifier applies to an argument with type
538	pointer to long long int or unsigned long long int.
539	j Specifies that a following d, i, o, u, x, X, or n conversion
540	specifier applies to an argument with type pointer to intmax_t
541	or uintmax_t.
542	z Specifies that a following d, i, o, u, x, X, or n conversion
543	specifier applies to an argument with type pointer to size_t or the
544	corresponding signed integer type.
545	t Specifies that a following d, i, o, u, x, X, or n conversion
546	specifier applies to an argument with type pointer to ptrdiff_t or
547	the corresponding unsigned integer type.
548	L Specifies that a following e, E, f, F, g, or G conversion specifier
549	applies to an argument with type pointer to long double.
550
551	If a length modifier appears with any conversion specifier other than as
552	specified above, the behavior is undefined.
553
554	The conversion specifiers and their meanings are:<BR>
555	d Matches an optionally signed decimal integer, whose format is the
556	same as expected for the subject sequence of the wcstol function
557	with the value 10 for the base argument. The corresponding argument
558	shall be a pointer to signed integer.
559	i Matches an optionally signed integer, whose format is the same as
560	expected for the subject sequence of the wcstol function with the
561	value 0 for the base argument. The corresponding argument shall be
562	a pointer to signed integer.
563	o Matches an optionally signed octal integer, whose format is the
564	same as expected for the subject sequence of the wcstoul function
565	with the value 8 for the base argument. The corresponding argument
566	shall be a pointer to unsigned integer.
567	u Matches an optionally signed decimal integer, whose format is the
568	same as expected for the subject sequence of the wcstoul function
569	with the value 10 for the base argument. The corresponding argument
570	shall be a pointer to unsigned integer.
571	x Matches an optionally signed hexadecimal integer, whose format is
572	the same as expected for the subject sequence of the wcstoul
573	function with the value 16 for the base argument. The corresponding
574	argument shall be a pointer to unsigned integer.
575	e,f,g Matches an optionally signed floating-point number, infinity, or
576	NaN, whose format is the same as expected for the subject sequence
577	of the wcstod function. The corresponding argument shall be a
578	pointer to float.
579	c Matches a sequence of wide characters of exactly the number
580	specified by the field width (1 if no field width is present in the
581	directive).<BR>
582	If no l length modifier is present, characters from the input field
583	are converted as if by repeated calls to the wcrtomb function, with
584	the conversion state described by an mbstate_t object initialized
585	to zero before the first wide character is converted. The
586	corresponding argument shall be a pointer to the initial element of
587	a character array large enough to accept the sequence. No null
588	character is added.<BR>
589	If an l length modifier is present, the corresponding argument
590	shall be a pointer to the initial element of an array of
591	wchar_t large enough to accept the sequence.
592	No null wide character is added.
593	s Matches a sequence of non-white-space wide characters.
594	If no l length modifier is present, characters from the input field
595	are converted as if by repeated calls to the wcrtomb function, with
596	the conversion state described by an mbstate_t object initialized
597	to zero before the first wide character is converted. The
598	corresponding argument shall be a pointer to the initial element of
599	a character array large enough to accept the sequence and a
600	terminating null character, which will be added automatically.<BR>
601	If an l length modifier is present, the corresponding argument
602	shall be a pointer to the initial element of an array of wchar_t
603	large enough to accept the sequence and the terminating null wide
604	character, which will be added automatically.
605	[ Matches a nonempty sequence of wide characters from a set of
606	expected characters (the scanset).<BR>
607	If no l length modifier is present, characters from the input field
608	are converted as if by repeated calls to the wcrtomb function, with
609	the conversion state described by an mbstate_t object initialized
610	to zero before the first wide character is converted. The
611	corresponding argument shall be a pointer to the initial element of
612	a character array large enough to accept the sequence and a
613	terminating null character, which will be added automatically.<BR>
614	If an l length modifier is present, the corresponding argument
615	shall be a pointer to the initial element of an array of wchar_t
616	large enough to accept the sequence and the terminating null wide
617	character, which will be added automatically.<BR>
618	The conversion specifier includes all subsequent wide characters
619	in the format string, up to and including the matching right
620	bracket (]). The wide characters between the brackets
621	(the scanlist) compose the scanset, unless the wide character after
622	the left bracket is a circumflex (^), in which case the scanset
623	contains all wide characters that do not appear in the scanlist
624	between the circumflex and the right bracket. If the conversion
625	specifier begins with [] or [^], the right bracket wide character
626	is in the scanlist and the next following right bracket wide
627	character is the matching right bracket that ends the specification;
628	otherwise the first following right bracket wide character is the
629	one that ends the specification. If a - wide character is in the
630	scanlist and is not the first, nor the second where the first wide
631	character is a ^, nor the last character,
632	the - is added to the scanset.
633	p Matches the set of sequences produced by the %p conversion of the
634	fwprintf function. The corresponding argument is a pointer to a
635	pointer to void. The input item is converted to a pointer value. If
636	the input item is a value converted earlier during the same program
637	execution, the pointer that results will compare equal to that
638	value.
639	n No input is consumed. The corresponding argument is a pointer to
640	signed integer into which is to be written the number of wide
641	characters read from the input stream so far by this call to the
642	fwscanf function. Execution of a %n directive does not increment
643	the assignment count returned at the completion of execution of the
644	fwscanf function. No argument is converted, but one is consumed.
645	% Matches a single % wide character; no conversion or assignment
646	occurs. The complete conversion specification shall be %%.
647
648	The conversion specifiers E, F, G, and X are also valid and behave the same
649	as, respectively, e, f, g, and x.
650
651	Trailing white space (including new-line wide characters) is left unread
652	unless matched by a directive. The success of literal matches and
653	suppressed assignments is not directly determinable other than via
654	the %n directive.
655
656	@param[in] stream An open File specifier from which the input is read.
657	@param[in] format A wide character sequence containing characters
658	to be matched against, and conversion specifiers
659	which convert their associated arguments. Converted
660	items are stored according to their associated arguments.
661	@param ... Variable number of parameters, as required by format,
662	specifying the objects to receive the converted input.
663
664	@return The fwscanf function returns the value of the macro EOF if an
665	input failure occurs before any conversion. Otherwise, the
666	function returns the number of input items assigned, which can be
667	fewer than provided for, or even zero, in the event of an early
668	matching failure.
669	**/
670	int fwscanf(FILE * __restrict stream, const wchar_t * __restrict format, ...);
671
672	/** Formatted wide-character output to a buffer.
673
674	The swprintf function is equivalent to fwprintf, except that the argument s
675	specifies an array of wide characters into which the generated output is to
676	be written, rather than written to a stream. No more than n wide characters
677	are written, including a terminating null wide character, which is always
678	added (unless n is zero).
679
680	@param[out] s A pointer to the array to receive the formatted output.
681	@param[in] n Maximum number of characters to write into buffer s.
682	@param[in] format A wide character sequence containing characters
683	to be copied unchanged, and conversion specifiers
684	which convert their associated arguments. Copied and
685	converted characters are written to the array pointed
686	to by s.
687	@param ... Variable number of parameters as required by format.
688
689	@return The swprintf function returns the number of wide characters
690	written in the array, not counting the terminating null wide
691	character, or a negative value if an encoding error occurred or
692	if n or more wide characters were requested to be written.
693	**/
694	int swprintf(wchar_t * __restrict s, size_t n, const wchar_t * __restrict format, ...);
695
696	/** Formatted wide input from a string.
697
698	The swscanf function is equivalent to fwscanf, except that the argument
699	Buff specifies a wide string from which the input is to be obtained, rather
700	than from a stream. Reaching the end of the wide string is equivalent to
701	encountering end-of-file for the fwscanf function.
702
703	@param[in] Buff Pointer to the string from which to obtain input.
704	@param[in] Format A wide character sequence containing characters
705	to be matched against, and conversion specifiers
706	which convert their associated arguments.
707	@param[out] ... Variable number of parameters, as required by format,
708	specifying the objects to receive the converted input.
709
710	@return The swscanf function returns the value of the macro EOF if an
711	input failure occurs before any conversion. Otherwise, the
712	swscanf function returns the number of input items assigned,
713	which can be fewer than provided for, or even zero, in the event
714	of an early matching failure.
715	**/
716	int swscanf(const wchar_t * __restrict Buff, const wchar_t * __restrict Format, ...);
717
718	/** Print formatted values from an argument list.
719
720	The vfwprintf function is equivalent to fwprintf, with the variable argument list
721	replaced by Args, which shall have been initialized by the va_start macro (and
722	possibly subsequent va_arg calls). The vfwprintf function does not invoke the
723	va_end macro.
724
725	@param[in] Stream The output stream to receive the formatted output.
726	@param[in] Format A wide character sequence containing characters
727	to be matched against, and conversion specifiers
728	which convert their associated arguments.
729	@param[in] Args A list of arguments, initialized by the va_start macro
730	and accessed using the va_arg macro, used to satisfy
731	the directives in the Format string.
732
733	@return The vfwprintf function returns the number of wide characters
734	transmitted, or a negative value if an output or encoding
735	error occurred.
736	**/
737	int vfwprintf(FILE * __restrict Stream, const wchar_t * __restrict Format, va_list Args);
738
739	/** Formatted input from a stream.
740
741	The vfwscanf function is equivalent to fwscanf, with the variable argument
742	list replaced by Args, which must have been initialized by the va_start
743	macro (and possibly subsequent va_arg calls). The vfwscanf function does
744	not invoke the va_end macro.
745
746	@param[in] Stream The input stream.
747	@param[in] Format A wide character sequence containing characters
748	to be matched against, and conversion specifiers
749	which convert their associated arguments.
750	@param[in] Args A list of arguments, initialized by the va_start macro
751	and accessed using the va_arg macro, used to satisfy
752	the directives in the Format string.
753
754	@return The vfwscanf function returns the value of the macro EOF if an
755	input failure occurs before any conversion. Otherwise, the
756	vfwscanf function returns the number of input items assigned,
757	which can be fewer than provided for, or even zero, in the event
758	of an early matching failure.
759	**/
760	int vfwscanf(FILE * __restrict Stream, const wchar_t * __restrict Format, va_list Args);
761
762	/** Formatted print, to a buffer, from an argument list.
763
764	The vswprintf function is equivalent to swprintf, with the variable
765	argument list replaced by Args, which must have been initialized by the
766	va_start macro (and possibly subsequent va_arg calls). The vswprintf
767	function does not invoke the va_end macro.
768
769	@param[in] S A pointer to the array to receive the formatted output.
770	@param[in] N Maximum number of characters to write into array S.
771	@param[in] Format A wide character sequence containing characters
772	to be matched against, and conversion specifiers
773	which convert their associated arguments.
774	@param[in] Args A list of arguments, initialized by the va_start macro
775	and accessed using the va_arg macro, used to satisfy
776	the directives in the Format string.
777
778	@return The vswprintf function returns the number of wide characters
779	written in the array, not counting the terminating null wide
780	character, or a neg ative value if an encoding error occurred or
781	if n or more wide characters were requested to be generated.
782	**/
783	int vswprintf(wchar_t * __restrict S, size_t N, const wchar_t * __restrict Format, va_list Args);
784
785	/** Formatted input from a string, using an argument list.
786
787	The vswscanf function is equivalent to swscanf, with the variable argument
788	list replaced by Args, which must have been initialized by the va_start
789	macro. The vswscanf function does not invoke the va_end macro.
790
791	@param[in] S Pointer to the string from which to obtain input.
792	@param[in] Format A wide character sequence containing characters
793	to be matched against, and conversion specifiers
794	which convert their associated arguments.
795	@param[out] Args A list of arguments, initialized by the va_start macro
796	and accessed using the va_arg macro, used to satisfy
797	the directives in the Format string.
798
799	@return The vswscanf function returns the value of the macro EOF if an
800	input failure occurs before any conversion. Otherwise, the
801	vswscanf function returns the number of input items assigned,
802	which can be fewer than provided for, or even zero, in the event
803	of an early matching failure.
804	**/
805	int vswscanf(const wchar_t * __restrict S, const wchar_t * __restrict Format, va_list Args);
806
807	/** Formatted print, to stdout, from an argument list.
808
809	The vwprintf function is equivalent to wprintf, with the variable argument
810	list replaced by Args, which must have been initialized by the va_start
811	macro. The vwprintf function does not invoke the va_end macro.
812
813	@param[in] Format A wide character sequence containing characters
814	to be matched against, and conversion specifiers
815	which convert their associated arguments.
816	@param[out] Args A list of arguments, initialized by the va_start macro
817	and accessed using the va_arg macro, used to satisfy
818	the directives in the Format string.
819
820	@return The vwprintf function returns the number of wide characters
821	transmitted, or a negative value if an output or encoding error
822	occurred.
823	**/
824	int vwprintf(const wchar_t * __restrict Format, va_list Args);
825
826	/** Formatted input, from stdin, to an argument list.
827
828	The vwscanf function is equivalent to wscanf, with the variable argument
829	list replaced by arg, which shall have been initialized by the va_start
830	macro. The vwscanf function does not invoke the va_end macro.
831
832	@param[in] Format A wide character sequence containing characters
833	to be matched against, and conversion specifiers
834	which convert their associated arguments.
835	@param[out] Args A list of arguments, initialized by the va_start macro
836	and accessed using the va_arg macro, used to satisfy
837	the directives in the Format string.
838
839	@return The vwscanf function returns the value of the macro EOF if an
840	input failure occurs before any conversion. Otherwise, the
841	vwscanf function returns the number of input items assigned,
842	which can be fewer than provided for, or even zero, in the event
843	of an early matching failure.
844	**/
845	int vwscanf(const wchar_t * __restrict Format, va_list Args);
846
847	/** Formatted print to stdout.
848
849	The wprintf function is equivalent to fwprintf with the argument stdout
850	specifying the output stream.
851
852	@param[in] format A wide character sequence containing characters
853	to be copied unchanged, and conversion specifiers
854	which convert their associated arguments.
855	@param ... Variable number of parameters as required by format.
856
857	@return The wprintf function returns the number of wide characters
858	transmitted, or a negative value if an output or encoding error
859	occurred.
860	**/
861	int wprintf(const wchar_t * __restrict Format, ...);
862
863	/** Formatted input from stdin.
864
865	The wscanf function is equivalent to fwscanf with the argument stdin
866	specifying the input stream.
867
868	@param[in] format A wide character sequence containing characters
869	to be matched against, and conversion specifiers
870	which convert their associated arguments. Converted
871	items are stored according to their associated arguments.
872	@param ... Variable number of parameters, as required by format,
873	specifying the objects to receive the converted input.
874
875	@return The wscanf function returns the value of the macro EOF if an
876	input failure occurs before any conversion. Otherwise, the
877	wscanf function returns the number of input items assigned,
878	which can be fewer than provided for, or even zero, in the event
879	of an early matching failure.
880	**/
881	int wscanf(const wchar_t * __restrict format, ...);
882
883	/* ################### Input/Output Functions ########################### */
884
885
886	/** Get a character from an input Stream.
887
888	If the end-of-file indicator for the input stream pointed to by stream is not set and a
889	next wide character is present, the fgetwc function obtains that wide character as a
890	wchar_t converted to a wint_t and advances the associated file position indicator for
891	the stream (if defined).
892
893	@param[in] Stream An input stream from which to obtain a character.
894
895	@return If the end-of-file indicator for the stream is set, or if the stream is at end-of-file, the endof-
896	file indicator for the stream is set and the fgetwc function returns WEOF. Otherwise,
897	the fgetwc function returns the next wide character from the input stream pointed to by
898	stream. If a read error occurs, the error indicator for the stream is set and the fgetwc
899	function returns WEOF. If an encoding error occurs (including too few bytes), the value of
900	the macro EILSEQ is stored in errno and the fgetwc function returns WEOF.
901	**/
902	wint_t fgetwc(FILE *Stream);
903
904	/** Read a string from an input stream into a buffer.
905
906	The fgetws function reads at most one less than the number of
907	wide characters specified by n from the stream pointed to by
908	stream into the array pointed to by s. No additional wide
909	characters are read after a new-line wide character (which is
910	retained) or after end-of-file. A null wide character is written
911	immediately after the last wide character read into the array.
912
913	@param[out] S A pointer to the array to receive the input string.
914	@param[in] Limit The maximum number of characters to put into Buff,
915	including the terminating null character.
916	@param[in] Stream An input stream from which to obtain a character.
917
918	@return The fgetws function returns S if successful. If end-of-file is
919	encountered and no characters have been read into the array, the
920	contents of the array remain unchanged and a null pointer is
921	returned. If a read or encoding error occurs during the
922	operation, the array contents are indeterminate and a
923	null pointer is returned.
924	**/
925	wchar_t fgetws(wchar_t __restrict S, int Limit, FILE * __restrict Stream);
926
927	/** Write a character to an output stream.
928
929	The fputwc function writes the wide character specified by c to the output stream
930	pointed to by stream, at the position indicated by the associated file position indicator
931	for the stream (if defined), and advances the indicator appropriately. If the file cannot
932	support positioning requests, or if the stream was opened with append mode, the
933	character is appended to the output stream.
934
935	@param[in] C The character to be written to Stream.
936	@param[in] Stream The output stream that C is to be written to.
937
938	@return The fputwc function returns the wide character written. If a write error occurs, the
939	error indicator for the stream is set and fputwc returns WEOF. If an encoding error
940	occurs, the value of the macro EILSEQ is stored in errno and fputwc returns WEOF.
941	**/
942	wint_t fputwc(wchar_t C, FILE *Stream);
943
944	/** Write a string to an output stream.
945
946	The fputws function writes the wide string pointed to by S to the stream pointed to by
947	Stream. The terminating null wide character is not written.
948
949	@param[in] String The character string to be written to Stream.
950	@param[in] Stream The output stream that String is to be written to.
951
952	@return The fputws function returns EOF if a write or encoding error occurs; otherwise, it
953	returns a nonnegative value.
954	**/
955	int fputws(const wchar_t * __restrict S, FILE * __restrict Stream);
956
957	/** Query or set a stream's orientation.
958
959	The fwide function determines the orientation of the stream pointed to by stream. If
960	Mode is greater than zero, the function first attempts to make the stream wide oriented. If
961	Mode is less than zero, the function first attempts to make the stream byte oriented.
962	Otherwise, Mode is zero and the function does not alter the orientation of the stream.
963
964	@param[in] Stream The stream to be queried.
965	@param[in] Mode Control value selecting between quering or setting
966	the Stream's orientation.
967	@return The fwide function returns a value greater than zero if, after the call, the stream has
968	wide orientation, a value less than zero if the stream has byte orientation, or zero if the
969	stream has no orientation.
970	**/
971	int fwide(FILE *Stream, int Mode);
972
973	/** Get a character from an input stream.
974
975	The getwc function is equivalent to fgetwc, except that if it is implemented as a
976	macro, it may evaluate Stream more than once, so the argument should never be an
977	expression with side effects.
978
979	@param[in] Stream The stream to be read.
980
981	@return The getwc function returns the next wide character from the input stream pointed to by
982	stream, or WEOF.
983	**/
984	wint_t getwc(FILE *Stream);
985
986	/** Get a character from stdin.
987
988	The getwchar function is equivalent to getwc with the argument stdin.
989
990	@return The getwchar function returns the next wide character from the
991	input stream pointed to by stdin, or WEOF.
992	**/
993	wint_t getwchar(void);
994
995	/** Write a character to an output stream.
996
997	The putwc function is equivalent to fputwc, except that if it is implemented as a
998	macro, it may evaluate Stream more than once, so the Stream argument should never be an
999	expression with side effects.
1000
1001	@param[in] C The wide character to be written to Stream.
1002	@param[in] Stream The output stream that C is to be written to.
1003
1004	@return The putwc function returns the wide character written, or WEOF.
1005	**/
1006	wint_t putwc(wchar_t C, FILE *Stream);
1007
1008	/** Write a character to stdout.
1009
1010	The putwchar function is equivalent to putwc with the second argument stdout.
1011
1012	@param[in] C The wide character to be written to stdout.
1013
1014	@return The putwchar function returns the character written, or WEOF.
1015	**/
1016	wint_t putwchar(wchar_t C);
1017
1018	/** Return a character to the input Stream as if it had not been read.
1019
1020	The ungetwc function pushes the wide character specified by C back onto the input
1021	stream pointed to by Stream. Pushed-back wide characters will be returned by
1022	subsequent reads on that stream in the reverse order of their pushing. A successful
1023	intervening call (with the stream pointed to by Stream) to a file positioning function
1024	(fseek, fsetpos, or rewind) discards any pushed-back wide characters for the
1025	stream. The external storage corresponding to the stream is unchanged.
1026
1027	One wide character of pushback is guaranteed, even if the call to the ungetwc function
1028	follows just after a call to a formatted wide character input function fwscanf,
1029	vfwscanf, vwscanf, or wscanf. If the ungetwc function is called too many times
1030	on the same stream without an intervening read or file positioning operation on that
1031	stream, the operation may fail.
1032
1033	If the value of C equals that of the macro WEOF, the operation fails and the input stream is
1034	unchanged.
1035
1036	A successful call to the ungetwc function clears the end-of-file indicator for the stream.
1037	The value of the file position indicator for the stream after reading or discarding all
1038	pushed-back wide characters is the same as it was before the wide characters were pushed
1039	back. For a text or binary stream, the value of its file position indicator after a successful
1040	call to the ungetwc function is unspecified until all pushed-back wide characters are
1041	read or discarded.
1042
1043	@param[in] C The wide character to push back onto the Stream.
1044	@param[in] Stream The output stream that C is to be pushed back onto.
1045
1046	@return The ungetwc function returns the character pushed back,
1047	or WEOF if the operation fails.
1048	**/
1049	wint_t ungetwc(wint_t C, FILE *Stream);
1050
1051	/* ################### Numeric Conversions ########################### */
1052
1053	/** @{
1054	The wcstod, wcstof, and wcstold functions convert the initial portion of the wide
1055	string pointed to by nptr to double, float, and long double representation,
1056	respectively. First, they decompose the input string into three parts: an initial, possibly
1057	empty, sequence of white-space wide characters (as specified by the iswspace
1058	function), a subject sequence resembling a floating-point constant or representing an
1059	infinity or NaN; and a final wide string of one or more unrecognized wide characters,
1060	including the terminating null wide character of the input wide string. Then, they attempt
1061	to convert the subject sequence to a floating-point number, and return the result.
1062
1063	@param[in] Nptr Pointer to the string to convert to a floating-point value.
1064	@param[in] EndPtr Optional pointer to an object in which to store a pointer
1065	to the final wide string.
1066
1067	The functions return the converted value, if any. If no conversion could be performed,
1068	zero is returned. If the correct value is outside the range of representable values, plus or
1069	minus HUGE_VAL, HUGE_VALF, or HUGE_VALL is returned (according to the return
1070	type and sign of the value), and the value of the macro ERANGE is stored in errno. If
1071	the result underflows (7.12.1), the functions return a value whose magnitude is no greater
1072	than the smallest normalized positive number in the return type. A pointer to the
1073	final wide string is stored in the object pointed to by endptr, provided that endptr is
1074	not a null pointer.
1075	**/
1076	double wcstod (const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr);
1077	float wcstof (const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr);
1078	long double wcstold (const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr);
1079	/@}/
1080
1081	/** @{
1082	The wcstol, wcstoll, wcstoul, and wcstoull functions convert the initial
1083	portion of the wide string pointed to by nptr to long int, long long int,
1084	unsigned long int, and unsigned long long int representation,
1085	respectively. First, they decompose the input string into three parts: an initial, possibly
1086	empty, sequence of white-space wide characters (as specified by the iswspace
1087	function), a subject sequence resembling an integer represented in some radix determined
1088	by the value of base, and a final wide string of one or more unrecognized wide
1089	characters, including the terminating null wide character of the input wide string. Then,
1090	they attempt to convert the subject sequence to an integer, and return the result.
1091
1092	@param[in] Nptr Pointer to the string to convert to a floating-point value.
1093	@param[in] EndPtr Optional pointer to an object in which to store a pointer
1094	to the final wide string.
1095	@param[in] Base Base, 0 to 36, of the value represented by the string
1096	pointed to by Nptr.
1097
1098	@return The wcstol, wcstoll, wcstoul, and wcstoull functions return the converted
1099	value, if any. If no conversion could be performed, zero is returned. If the correct value
1100	is outside the range of representable values, LONG_MIN, LONG_MAX, LLONG_MIN,
1101	LLONG_MAX, ULONG_MAX, or ULLONG_MAX is returned (according to the return type
1102	sign of the value, if any), and the value of the macro ERANGE is stored in errno.
1103	**/
1104	long int wcstol ( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base);
1105	long long int wcstoll ( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base);
1106	unsigned long int wcstoul ( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base);
1107	unsigned long long int wcstoull( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base);
1108	/@}/
1109
1110	/* ####################### String Copying ############################### */
1111
1112	/** The wcscpy function copies the wide string pointed to by Src (including the
1113	terminating null wide character) into the array pointed to by Dest.
1114
1115	@return The wcscpy function returns the value of Dest.
1116	**/
1117	wchar_t wcscpy(wchar_t __restrict Dest, const wchar_t * __restrict Src);
1118
1119	/** The wcsncpy function copies not more than n wide characters (those that
1120	follow a null wide character are not copied) from the array pointed to by
1121	Src to the array pointed to by Dest.
1122
1123	If the array pointed to by Src is a wide string that is shorter than n wide
1124	characters, null wide characters are appended to the copy in the array
1125	pointed to by Dest, until n wide characters in all have been written.
1126
1127	@return The wcsncpy function returns the value of Dest.
1128	**/
1129	wchar_t wcsncpy(wchar_t __restrict Dest, const wchar_t * __restrict Src, size_t n);
1130
1131	/** The wmemcpy function copies n wide characters from the object pointed to by
1132	Src to the object pointed to by Dest.
1133
1134	Use this function if you know that Dest and Src DO NOT Overlap. Otherwise,
1135	use wmemmove.
1136
1137	@return The wmemcpy function returns the value of Dest.
1138	**/
1139	wchar_t wmemcpy(wchar_t __restrict Dest, const wchar_t * __restrict Src, size_t n);
1140
1141	/** The wmemmove function copies n wide characters from the object pointed to by
1142	Src to the object pointed to by Dest. The objects pointed to by Dest and Src are
1143	allowed to overlap.
1144
1145	Because the UEFI BaseMemoryLib function CopyMem explicitly handles
1146	overlapping source and destination objects, this function and wmemcpy are
1147	implemented identically.
1148
1149	For programming clarity, it is recommended that you use wmemcpy if you know
1150	that Dest and Src DO NOT Overlap. If Dest and Src might possibly overlap, then
1151	use wmemmove.
1152
1153	@return The wmemmove function returns the value of Dest.
1154	**/
1155	wchar_t wmemmove(wchar_t Dest, const wchar_t *Src, size_t n);
1156
1157	/* ################### String Concatenation ########################## */
1158
1159	/** The wcscat function appends a copy of the wide string pointed to by Src
1160	(including the terminating null wide character) to the end of the wide
1161	string pointed to by Dest. The initial wide character of Src overwrites the
1162	null wide character at the end of Dest.
1163
1164	@return The wcscat function returns the value of Dest.
1165	**/
1166	wchar_t wcscat(wchar_t __restrict Dest, const wchar_t * __restrict Src);
1167
1168	/** The wcsncat function appends not more than n wide characters (a null wide
1169	character and those that follow it are not appended) from the array pointed
1170	to by Src to the end of the wide string pointed to by Dest. The initial wide
1171	character of Src overwrites the null wide character at the end of Dest.
1172	A terminating null wide character is always appended to the result.
1173
1174	@return The wcsncat function returns the value of Dest.
1175	**/
1176	wchar_t wcsncat(wchar_t __restrict Dest, const wchar_t * __restrict Src, size_t n);
1177
1178	/* ##################### String Comparison ############################# */
1179
1180	/** The wcscmp function compares the wide string pointed to by s1 to the wide
1181	string pointed to by s2.
1182
1183	@return The wcscmp function returns an integer greater than, equal to, or
1184	less than zero, accordingly as the wide string pointed to by s1
1185	is greater than, equal to, or less than the wide string
1186	pointed to by s2.
1187	**/
1188	int wcscmp(const wchar_t s1, const wchar_t s2);
1189
1190	/** The wcscoll function compares the wide string pointed to by s1 to the wide
1191	string pointed to by s2, both interpreted as appropriate to the LC_COLLATE
1192	category of the current locale.
1193
1194	@return The wcscoll function returns an integer greater than, equal to,
1195	or less than zero, accordingly as the wide string pointed to by
1196	s1 is greater than, equal to, or less than the wide string
1197	pointed to by s2 when both are interpreted as appropriate to
1198	the current locale.
1199	**/
1200	int wcscoll(const wchar_t s1, const wchar_t s2);
1201
1202	/** The wcsncmp function compares not more than n wide characters (those that
1203	follow a null wide character are not compared) from the array pointed to by
1204	s1 to the array pointed to by s2.
1205
1206	@return The wcsncmp function returns an integer greater than, equal to,
1207	or less than zero, accordingly as the possibly null-terminated
1208	array pointed to by s1 is greater than, equal to, or less than
1209	the possibly null-terminated array pointed to by s2.
1210	**/
1211	int wcsncmp(const wchar_t s1, const wchar_t s2, size_t n);
1212
1213	/** The wcsxfrm function transforms the wide string pointed to by s2 and places
1214	the resulting wide string into the array pointed to by s1. The
1215	transformation is such that if the wcscmp function is applied to two
1216	transformed wide strings, it returns a value greater than, equal to, or
1217	less than zero, corresponding to the result of the wcscoll function applied
1218	to the same two original wide strings. No more than n wide characters are
1219	placed into the resulting array pointed to by s1, including the terminating
1220	null wide character. If n is zero, s1 is permitted to be a null pointer.
1221
1222	@return The wcsxfrm function returns the length of the transformed wide
1223	string (not including the terminating null wide character). If
1224	the value returned is n or greater, the contents of the array
1225	pointed to by s1 are indeterminate.
1226	**/
1227	size_t wcsxfrm(wchar_t * __restrict s1, const wchar_t * __restrict s2, size_t n);
1228
1229	/** The wmemcmp function compares the first n wide characters of the object
1230	pointed to by s1 to the first n wide characters of the object pointed to
1231	by s2.
1232
1233	@return The wmemcmp function returns an integer greater than, equal to,
1234	or less than zero, accordingly as the object pointed to by s1 is
1235	greater than, equal to, or less than the object pointed to by s2.
1236	**/
1237	int wmemcmp(const wchar_t s1, const wchar_t s2, size_t n);
1238
1239	/* ##################### String Searching ############################## */
1240
1241	/** The wcschr function locates the first occurrence of C in the wide string
1242	pointed to by S. The terminating null wide character is considered to be
1243	part of the wide string.
1244
1245	@return The wcschr function returns a pointer to the located wide
1246	character, or a null pointer if the wide character does not occur
1247	in the wide string.
1248	**/
1249	wchar_t wcschr(const wchar_t S, wchar_t C);
1250
1251	/** The wcscspn function computes the length of the maximum initial segment of
1252	the wide string pointed to by s1 which consists entirely of wide characters
1253	not from the wide string pointed to by s2.
1254
1255	@return The wcscspn function returns the length of the segment.
1256	**/
1257	size_t wcscspn(const wchar_t s1, const wchar_t s2);
1258
1259	/** The wcspbrk function locates the first occurrence in the wide string
1260	pointed to by s1 of any wide character from the wide string
1261	pointed to by s2.
1262
1263	@return The wcspbrk function returns a pointer to the wide character
1264	in s1, or a null pointer if no wide character from s2 occurs
1265	in s1.
1266	**/
1267	wchar_t wcspbrk(const wchar_t s1, const wchar_t *s2);
1268
1269	/** The wcsrchr function locates the last occurrence of C in the wide string
1270	pointed to by S. The terminating null wide character is considered to be
1271	part of the wide string.
1272
1273	@return The wcsrchr function returns a pointer to the wide character,
1274	or a null pointer if C does not occur in the wide string.
1275	**/
1276	wchar_t wcsrchr(const wchar_t S, wchar_t C);
1277
1278	/** The wcsspn function computes the length of the maximum initial segment of
1279	the wide string pointed to by s1 which consists entirely of wide characters
1280	from the wide string pointed to by s2.
1281
1282	@return The wcsspn function returns the length of the segment.
1283	**/
1284	size_t wcsspn(const wchar_t s1, const wchar_t s2);
1285
1286	/** The wcsstr function locates the first occurrence in the wide string pointed
1287	to by s1 of the sequence of wide characters (excluding the terminating null
1288	wide character) in the wide string pointed to by s2.
1289
1290	@return The wcsstr function returns a pointer to the located wide string,
1291	or a null pointer if the wide string is not found. If s2 points
1292	to a wide string with zero length, the function returns s1.
1293	**/
1294	wchar_t wcsstr(const wchar_t s1, const wchar_t *s2);
1295
1296	/** A sequence of calls to the wcstok function breaks the wide string pointed
1297	to by s1 into a sequence of tokens, each of which is delimited by a wide
1298	character from the wide string pointed to by s2. The third argument points
1299	to a caller-provided wchar_t pointer into which the wcstok function stores
1300	information necessary for it to continue scanning the same wide string.
1301
1302	The first call in a sequence has a non-null first argument and stores an
1303	initial value in the object pointed to by ptr. Subsequent calls in the
1304	sequence have a null first argument and the object pointed to by ptr is
1305	required to have the value stored by the previous call in the sequence,
1306	which is then updated. The separator wide string pointed to by s2 may be
1307	different from call to call.
1308
1309	The first call in the sequence searches the wide string pointed to by s1
1310	for the first wide character that is not contained in the current separator
1311	wide string pointed to by s2. If no such wide character is found, then
1312	there are no tokens in the wide string pointed to by s1 and the wcstok
1313	function returns a null pointer. If such a wide character is found, it is
1314	the start of the first token.
1315
1316	The wcstok function then searches from there for a wide character that is
1317	contained in the current separator wide string. If no such wide character
1318	is found, the current token extends to the end of the wide string pointed
1319	to by s1, and subsequent searches in the same wide string for a token
1320	return a null pointer. If such a wide character is found, it is overwritten
1321	by a null wide character, which terminates the current token.
1322
1323	In all cases, the wcstok function stores sufficient information in the
1324	pointer pointed to by ptr so that subsequent calls, with a null pointer for
1325	s1 and the unmodified pointer value for ptr, shall start searching just
1326	past the element overwritten by a null wide character (if any).
1327
1328	@return The wcstok function returns a pointer to the first wide character
1329	of a token, or a null pointer if there is no token.
1330	**/
1331	wchar_t wcstok(wchar_t __restrict s1, const wchar_t * __restrict s2, wchar_t ** __restrict ptr);
1332
1333	/** The wmemchr function locates the first occurrence of C in the initial n
1334	wide characters of the object pointed to by S.
1335
1336	@return The wmemchr function returns a pointer to the located wide
1337	character, or a null pointer if the wide character does not occur
1338	in the object.
1339	**/
1340	wchar_t wmemchr(const wchar_t S, wchar_t C, size_t n);
1341
1342	/* ################### String Manipulation ############################# */
1343
1344	/** The wcslen function computes the length of the wide string pointed to by S.
1345
1346	@return The wcslen function returns the number of wide characters that
1347	precede the terminating null wide character.
1348	**/
1349	size_t wcslen(const wchar_t *S);
1350
1351	/** The wmemset function copies the value of C into each of the first n wide
1352	characters of the object pointed to by S.
1353
1354	@return The wmemset function returns the value of S.
1355	**/
1356	wchar_t wmemset(wchar_t S, wchar_t C, size_t n);
1357
1358	/* ################# Date and Time Conversion ########################### */
1359
1360	/**
1361	The wcsftime function is equivalent to the strftime function, except that:
1362	- The argument s points to the initial element of an array of wide characters into which
1363	the generated output is to be placed.
1364	- The argument maxsize indicates the limiting number of wide characters.
1365	- The argument format is a wide string and the conversion specifiers are replaced by
1366	corresponding sequences of wide characters.
1367	- The return value indicates the number of wide characters.
1368
1369	If the total number of resulting wide characters including the terminating null wide
1370	character is not more than maxsize, the wcsftime function returns the number of
1371	wide characters placed into the array pointed to by s not including the terminating null
1372	wide character. Otherwise, zero is returned and the contents of the array are
1373	indeterminate.
1374	**/
1375	size_t wcsftime(wchar_t * __restrict S, size_t maxsize, const wchar_t * __restrict format, const struct tm * __restrict timeptr);
1376
1377	/* ############# Multibyte <--> Wide Character Conversion ############### */
1378
1379	/** The btowc function determines whether C constitutes a valid single-byte
1380	character in the initial shift state.
1381
1382	@return The btowc function returns WEOF if c has the value EOF or if
1383	(unsigned char)C does not constitute a valid single-byte
1384	character in the initial shift state. Otherwise, it returns the
1385	wide character representation of that character.
1386	**/
1387	wint_t btowc(int C);
1388
1389	/** The wctob function determines whether C corresponds to a member of the extended
1390	character set whose multibyte character representation is a single byte when in the initial
1391	shift state.
1392
1393	@return The wctob function returns EOF if C does not correspond to a multibyte
1394	character with length one in the initial shift state. Otherwise, it
1395	returns the single-byte representation of that character as an
1396	unsigned char converted to an int.
1397	**/
1398	int wctob(wint_t C);
1399
1400	/** If ps is not a null pointer, the mbsinit function determines whether the
1401	pointed-to mbstate_t object describes an initial conversion state.
1402
1403	@return The mbsinit function returns nonzero if ps is a null pointer
1404	or if the pointed-to object describes an initial conversion
1405	state; otherwise, it returns zero.
1406	**/
1407	int mbsinit(const mbstate_t *ps);
1408
1409	/* ####### Restartable Multibyte <--> Wide Character Conversion ######### */
1410
1411	/** The mbrlen function is equivalent to the call:<BR>
1412	@verbatim
1413	mbrtowc(NULL, s, n, ps != NULL ? ps : &internal)
1414	@endverbatim
1415	where internal is the mbstate_t object for the mbrlen function, except that
1416	the expression designated by ps is evaluated only once.
1417
1418	@return The mbrlen function returns a value between zero and n,
1419	inclusive, (size_t)(-2), or (size_t)(-1).
1420	**/
1421	size_t mbrlen(const char * __restrict S, size_t n, mbstate_t * __restrict ps);
1422
1423	/**
1424	If S is a null pointer, the mbrtowc function is equivalent to the call:<BR>
1425	@verbatim
1426	mbrtowc(NULL, "", 1, ps)
1427	@endverbatim
1428
1429	In this case, the values of the parameters pwc and n are ignored.
1430
1431	If S is not a null pointer, the mbrtowc function inspects at most n bytes beginning with
1432	the byte pointed to by S to determine the number of bytes needed to complete the next
1433	multibyte character (including any shift sequences). If the function determines that the
1434	next multibyte character is complete and valid, it determines the value of the
1435	corresponding wide character and then, if pwc is not a null pointer, stores that value in
1436	the object pointed to by pwc. If the corresponding wide character is the null wide
1437	character, the resulting state described is the initial conversion state.
1438
1439	@retval 0 if the next n or fewer bytes complete the multibyte
1440	character that corresponds to the null wide
1441	character (which is the value stored).
1442	@retval between_1_and_n_inclusive if the next n or fewer bytes complete
1443	a valid multibyte character (which is the value
1444	stored); the value returned is the number of bytes
1445	that complete the multibyte character.
1446	@retval (size_t)(-2) if the next n bytes contribute to an incomplete
1447	(but potentially valid) multibyte character, and
1448	all n bytes have been processed (no value is stored).
1449	@retval (size_t)(-1) if an encoding error occurs, in which case the next
1450	n or fewer bytes do not contribute to a complete and
1451	valid multibyte character (no value is stored); the
1452	value of the macro EILSEQ is stored in errno, and
1453	the conversion state is unspecified.
1454	**/
1455	size_t mbrtowc(wchar_t * __restrict pwc, const char * __restrict S, size_t n, mbstate_t * __restrict ps);
1456
1457	/**
1458	If S is a null pointer, the wcrtomb function is equivalent to the call:<BR>
1459	@verbatim
1460	wcrtomb(buf, L'\0', ps)
1461	@endverbatim
1462	where buf is an internal buffer.
1463
1464	If S is not a null pointer, the wcrtomb function determines the number of bytes needed
1465	to represent the multibyte character that corresponds to the wide character given by wc
1466	(including any shift sequences), and stores the multibyte character representation in the
1467	array whose first element is pointed to by S. At most MB_CUR_MAX bytes are stored. If
1468	wc is a null wide character, a null byte is stored, preceded by any shift sequence needed
1469	to restore the initial shift state; the resulting state described is the initial conversion state.
1470
1471	@return The wcrtomb function returns the number of bytes stored in the
1472	array object (including any shift sequences). When wc is not a
1473	valid wide character, an encoding error occurs: the function
1474	stores the value of the macro EILSEQ in errno and
1475	returns (size_t)(-1); the conversion state is unspecified.
1476	**/
1477	size_t wcrtomb(char * __restrict S, wchar_t wc, mbstate_t * __restrict ps);
1478
1479	/**
1480	The mbsrtowcs function converts a sequence of multibyte characters that begins in the
1481	conversion state described by the object pointed to by ps, from the array indirectly
1482	pointed to by src into a sequence of corresponding wide characters. If dst is not a null
1483	pointer, the converted characters are stored into the array pointed to by dst. Conversion
1484	continues up to and including a terminating null character, which is also stored.
1485	Conversion stops earlier in two cases: when a sequence of bytes is encountered that does
1486	not form a valid multibyte character, or (if dst is not a null pointer) when len wide
1487	characters have been stored into the array pointed to by dst. Each conversion takes
1488	place as if by a call to the mbrtowc function.
1489
1490	If dst is not a null pointer, the pointer object pointed to by src is assigned either a null
1491	pointer (if conversion stopped due to reaching a terminating null character) or the address
1492	just past the last multibyte character converted (if any). If conversion stopped due to
1493	reaching a terminating null character and if dst is not a null pointer, the resulting state
1494	described is the initial conversion state.
1495
1496	@return If the input conversion encounters a sequence of bytes that do
1497	not form a valid multibyte character, an encoding error occurs:
1498	the mbsrtowcs function stores the value of the macro EILSEQ in
1499	errno and returns (size_t)(-1); the conversion state is
1500	unspecified. Otherwise, it returns the number of multibyte
1501	characters successfully converted, not including the terminating
1502	null character (if any).
1503	**/
1504	size_t mbsrtowcs(wchar_t * __restrict dst, const char ** __restrict src, size_t len, mbstate_t * __restrict ps);
1505
1506	/** The wcsrtombs function converts a sequence of wide characters from the array
1507	indirectly pointed to by src into a sequence of corresponding multibyte
1508	characters that begins in the conversion state described by the object
1509	pointed to by ps. If dst is not a null pointer, the converted characters
1510	are then stored into the array pointed to by dst. Conversion continues
1511	up to and including a terminating null wide character, which is also
1512	stored. Conversion stops earlier in two cases: when a wide character is
1513	reached that does not correspond to a valid multibyte character, or
1514	(if dst is not a null pointer) when the next multibyte character would
1515	exceed the limit of len total bytes to be stored into the array pointed
1516	to by dst. Each conversion takes place as if by a call to the wcrtomb
1517	function.)
1518
1519	If dst is not a null pointer, the pointer object pointed to by src is
1520	assigned either a null pointer (if conversion stopped due to reaching
1521	a terminating null wide character) or the address just past the last wide
1522	character converted (if any). If conversion stopped due to reaching a
1523	terminating null wide character, the resulting state described is the
1524	initial conversion state.
1525
1526	@return If conversion stops because a wide character is reached that
1527	does not correspond to a valid multibyte character, an
1528	encoding error occurs: the wcsrtombs function stores the
1529	value of the macro EILSEQ in errno and returns (size_t)(-1);
1530	the conversion state is unspecified. Otherwise, it returns
1531	the number of bytes in the resulting multibyte character
1532	sequence, not including the terminating null character (if any).
1533	**/
1534	size_t wcsrtombs(char * __restrict dst, const wchar_t ** __restrict src, size_t len, mbstate_t * __restrict ps);
1535
1536	#endif /* _WCHAR_H */

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/VBox/Devices/EFI/FirmwareOld/StdLib/Include/wchar.h@ 58453

Download in other formats: