• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 - 2014, 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 the string.
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.
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     @param[in]  s     Pointer to a multibyte character sequence.
1419     @param[in]  n     Maximum number of bytes to examine.
1420     @param[in]  pS    Pointer to the conversion state object.
1421 
1422     @retval   0       The next n or fewer characters complete a NUL.
1423     @retval   1..n    The number of bytes that complete the multibyte character.
1424     @retval   -2      The next n bytes contribute to an incomplete (but potentially valid) multibyte character.
1425     @retval   -1      An encoding error occurred.
1426 **/
1427 size_t mbrlen(const char * __restrict S, size_t n, mbstate_t * __restrict pS);
1428 
1429 /** Restartable Multibyte to Wide character conversion.
1430 If S is a null pointer, the mbrtowc function is equivalent to the call:<BR>
1431 @verbatim
1432         mbrtowc(NULL, "", 1, ps)
1433 @endverbatim
1434 
1435 In this case, the values of the parameters pwc and n are ignored.
1436 
1437 If S is not a null pointer, the mbrtowc function inspects at most n bytes beginning with
1438 the byte pointed to by S to determine the number of bytes needed to complete the next
1439 multibyte character (including any shift sequences). If the function determines that the
1440 next multibyte character is complete and valid, it determines the value of the
1441 corresponding wide character and then, if pwc is not a null pointer, stores that value in
1442 the object pointed to by pwc. If the corresponding wide character is the null wide
1443 character, the resulting state described is the initial conversion state.
1444 
1445     @retval   0             if the next n or fewer bytes complete the multibyte
1446                             character that corresponds to the null wide
1447                             character (which is the value stored).
1448     @retval   between_1_and_n_inclusive   if the next n or fewer bytes complete
1449                             a valid multibyte character (which is the value
1450                             stored); the value returned is the number of bytes
1451                             that complete the multibyte character.
1452     @retval   (size_t)(-2)  if the next n bytes contribute to an incomplete
1453                             (but potentially valid) multibyte character, and
1454                             all n bytes have been processed (no value is stored).
1455     @retval   (size_t)(-1)  if an encoding error occurs, in which case the next
1456                             n or fewer bytes do not contribute to a complete and
1457                             valid multibyte character (no value is stored); the
1458                             value of the macro EILSEQ is stored in errno, and
1459                             the conversion state is unspecified.
1460 **/
1461 size_t mbrtowc(wchar_t * __restrict pwc, const char * __restrict S, size_t n, mbstate_t * __restrict ps);
1462 
1463 /**
1464 If S is a null pointer, the wcrtomb function is equivalent to the call:<BR>
1465 @verbatim
1466         wcrtomb(buf, L'\0', ps)
1467 @endverbatim
1468 where buf is an internal buffer.
1469 
1470 If S is not a null pointer, the wcrtomb function determines the number of bytes needed
1471 to represent the multibyte character that corresponds to the wide character given by wc
1472 (including any shift sequences), and stores the multibyte character representation in the
1473 array whose first element is pointed to by S. At most MB_CUR_MAX bytes are stored. If
1474 wc is a null wide character, a null byte is stored, preceded by any shift sequence needed
1475 to restore the initial shift state; the resulting state described is the initial conversion state.
1476 
1477     @return   The wcrtomb function returns the number of bytes stored in the
1478               array object (including any shift sequences). When wc is not a
1479               valid wide character, an encoding error occurs: the function
1480               stores the value of the macro EILSEQ in errno and
1481               returns (size_t)(-1); the conversion state is unspecified.
1482 **/
1483 size_t wcrtomb(char * __restrict S, wchar_t wc, mbstate_t * __restrict ps);
1484 
1485 /** Convert a sequence of multibyte characters into a sequence of wide characters.
1486     The mbsrtowcs function converts a sequence of multibyte characters that begins in the
1487     conversion state described by the object pointed to by ps, from the array indirectly
1488     pointed to by src into a sequence of corresponding wide characters. If dst is not a null
1489     pointer, the converted characters are stored into the array pointed to by dst. Conversion
1490     continues up to and including a terminating null character, which is also stored.
1491     Conversion stops earlier in two cases: when a sequence of bytes is encountered that does
1492     not form a valid multibyte character, or (if dst is not a null pointer) when len wide
1493     characters have been stored into the array pointed to by dst. Each conversion takes
1494     place as if by a call to the mbrtowc function.
1495 
1496     If dst is not a null pointer, the pointer object pointed to by src is assigned either a null
1497     pointer (if conversion stopped due to reaching a terminating null character) or the address
1498     just past the last multibyte character converted (if any). If conversion stopped due to
1499     reaching a terminating null character and if dst is not a null pointer, the resulting state
1500     described is the initial conversion state.
1501 
1502     @param[in]    dst   Destination for the Wide character sequence.
1503     @param[in]    src   Pointer to Pointer to MBCS char. sequence to convert.
1504     @param[in]    len   Length of dest, in WIDE characters.
1505     @param[in]    ps    Pointer to the conversion state object to be used for this conversion.
1506 
1507     @return   If the input conversion encounters a sequence of bytes that do
1508               not form a valid multibyte character, an encoding error occurs:
1509               the mbsrtowcs function stores the value of the macro EILSEQ in
1510               errno and returns (size_t)(-1); the conversion state is
1511               unspecified. Otherwise, it returns the number of multibyte
1512               characters successfully converted, not including the terminating
1513               null character (if any).
1514 **/
1515 size_t mbsrtowcs(wchar_t * __restrict dst, const char ** __restrict src, size_t len, mbstate_t * __restrict ps);
1516 
1517 /** The wcsrtombs function converts a sequence of wide characters from the array
1518     indirectly pointed to by src into a sequence of corresponding multibyte
1519     characters that begins in the conversion state described by the object
1520     pointed to by ps. If dst is not a null pointer, the converted characters
1521     are then stored into the array pointed to by dst.  Conversion continues
1522     up to and including a terminating null wide character, which is also
1523     stored. Conversion stops earlier in two cases: when a wide character is
1524     reached that does not correspond to a valid multibyte character, or
1525     (if dst is not a null pointer) when the next multibyte character would
1526     exceed the limit of len total bytes to be stored into the array pointed
1527     to by dst. Each conversion takes place as if by a call to the wcrtomb
1528     function.)
1529 
1530     If dst is not a null pointer, the pointer object pointed to by src is
1531     assigned either a null pointer (if conversion stopped due to reaching
1532     a terminating null wide character) or the address just past the last wide
1533     character converted (if any). If conversion stopped due to reaching a
1534     terminating null wide character, the resulting state described is the
1535     initial conversion state.
1536 
1537     @param[in]    dst   Destination for the MBCS sequence.
1538     @param[in]    src   Pointer to Pointer to wide char. sequence to convert.
1539     @param[in]    len   Length of dest, in bytes.
1540     @param[in]    ps    Pointer to the conversion state object to be used for this conversion.
1541 
1542     @return     If conversion stops because a wide character is reached that
1543                 does not correspond to a valid multibyte character, an
1544                 encoding error occurs: the wcsrtombs function stores the
1545                 value of the macro EILSEQ in errno and returns (size_t)(-1);
1546                 the conversion state is unspecified. Otherwise, it returns
1547                 the number of bytes in the resulting multibyte character
1548                 sequence, not including the terminating null character (if any).
1549 **/
1550 size_t wcsrtombs(char * __restrict dst, const wchar_t ** __restrict src, size_t len, mbstate_t * __restrict ps);
1551 
1552 #endif  /* _WCHAR_H */
1553