]>
git.proxmox.com Git - mirror_edk2.git/blob - StdLib/Include/wchar.h
2 Extended multibyte and wide character utilities.
4 Within this implementation, multibyte characters are represented using the
5 Unicode UTF-8 encoding and wide characters are represented using the
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.
12 The following macros are defined in this file:<BR>
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.
20 The following types are defined in this file:<BR>
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.
29 The following functions are declared in this file:<BR>
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, ...);
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);
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);
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);
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);
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);
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);
118 ################### String Manipulation
119 size_t wcslen (const wchar_t *S);
120 wchar_t *wmemset (wchar_t *S, wchar_t c, size_t n);
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);
127 ############# Multibyte <--> Wide Character Conversion
128 wint_t btowc (int c);
129 int wctob (wint_t c);
130 int mbsinit (const mbstate_t *ps);
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);
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.
153 Copyright (c) 2010 - 2012, 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.
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.
164 #include <sys/EfiCdefs.h>
165 #include <machine/ansi.h>
166 #include <machine/limits.h>
170 #if defined(_MSC_VER)
171 #pragma warning ( disable : 4142 )
175 typedef _EFI_SIZE_T_
size_t; /**< Unsigned integer type of the result of the sizeof operator. */
182 /** An integer type capable of representing all distinct codes in the
183 UCS-2 encoding supported by UEFI.
185 typedef _EFI_WCHAR_T
wchar_t;
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.
195 typedef _BSD_MBSTATE_T_
mbstate_t;
196 #undef _BSD_MBSTATE_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.
205 typedef _EFI_WINT_T
wint_t;
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).
216 #define WCHAR_MAX __USHRT_MAX
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.
228 #define WEOF ((wint_t)-1)
231 /* limits of wint_t -- These are NOT specified by ISO/IEC 9899 */
233 #define WINT_MIN _EFI_WINT_MIN /* wint_t */
234 #define WINT_MAX _EFI_WINT_MAX /* wint_t */
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>.
242 /* ############### Formatted Input/Output Functions ##################### */
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.
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.
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.
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
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.
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.
356 If a length modifier appears with any conversion specifier other than as
357 specified above, the behavior is undefined.
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
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 %%.
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.
454 @return The fwprintf function returns the number of wide characters
455 transmitted, or a negative value if an output or encoding error
458 int fwprintf(FILE * __restrict stream
, const wchar_t * __restrict format
, ...);
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
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.
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).
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.
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.
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.
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
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
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.
551 If a length modifier appears with any conversion specifier other than as
552 specified above, the behavior is undefined.
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
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
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
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 %%.
648 The conversion specifiers E, F, G, and X are also valid and behave the same
649 as, respectively, e, f, g, and x.
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
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.
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
670 int fwscanf(FILE * __restrict stream
, const wchar_t * __restrict format
, ...);
672 /** Formatted wide-character output to a buffer.
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).
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
687 @param ... Variable number of parameters as required by format.
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.
694 int swprintf(wchar_t * __restrict s
, size_t n
, const wchar_t * __restrict format
, ...);
696 /** Formatted wide input from a string.
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.
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.
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.
716 int swscanf(const wchar_t * __restrict Buff
, const wchar_t * __restrict Format
, ...);
718 /** Print formatted values from an argument list.
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
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.
733 @return The vfwprintf function returns the number of wide characters
734 transmitted, or a negative value if an output or encoding
737 int vfwprintf(FILE * __restrict Stream
, const wchar_t * __restrict Format
, va_list Args
);
739 /** Formatted input from a stream.
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.
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.
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.
760 int vfwscanf(FILE * __restrict Stream
, const wchar_t * __restrict Format
, va_list Args
);
762 /** Formatted print, to a buffer, from an argument list.
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.
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.
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.
783 int vswprintf(wchar_t * __restrict S
, size_t N
, const wchar_t * __restrict Format
, va_list Args
);
785 /** Formatted input from a string, using an argument list.
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.
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.
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.
805 int vswscanf(const wchar_t * __restrict S
, const wchar_t * __restrict Format
, va_list Args
);
807 /** Formatted print, to stdout, from an argument list.
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.
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.
820 @return The vwprintf function returns the number of wide characters
821 transmitted, or a negative value if an output or encoding error
824 int vwprintf(const wchar_t * __restrict Format
, va_list Args
);
826 /** Formatted input, from stdin, to an argument list.
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.
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.
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.
845 int vwscanf(const wchar_t * __restrict Format
, va_list Args
);
847 /** Formatted print to stdout.
849 The wprintf function is equivalent to fwprintf with the argument stdout
850 specifying the output stream.
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.
857 @return The wprintf function returns the number of wide characters
858 transmitted, or a negative value if an output or encoding error
861 int wprintf(const wchar_t * __restrict Format
, ...);
863 /** Formatted input from stdin.
865 The wscanf function is equivalent to fwscanf with the argument stdin
866 specifying the input stream.
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.
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.
881 int wscanf(const wchar_t * __restrict format
, ...);
883 /* ################### Input/Output Functions ########################### */
886 /** Get a character from an input Stream.
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).
893 @param[in] Stream An input stream from which to obtain a character.
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.
902 wint_t fgetwc(FILE *Stream
);
904 /** Read a string from an input stream into a buffer.
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.
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.
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.
925 wchar_t *fgetws(wchar_t * __restrict S
, int Limit
, FILE * __restrict Stream
);
927 /** Write a character to an output stream.
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.
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.
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.
942 wint_t fputwc(wchar_t C
, FILE *Stream
);
944 /** Write a string to an output stream.
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.
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.
952 @return The fputws function returns EOF if a write or encoding error occurs; otherwise, it
953 returns a nonnegative value.
955 int fputws(const wchar_t * __restrict S
, FILE * __restrict Stream
);
957 /** Query or set a stream's orientation.
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.
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.
971 int fwide(FILE *Stream
, int Mode
);
973 /** Get a character from an input stream.
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.
979 @param[in] Stream The stream to be read.
981 @return The getwc function returns the next wide character from the input stream pointed to by
984 wint_t getwc(FILE *Stream
);
986 /** Get a character from stdin.
988 The getwchar function is equivalent to getwc with the argument stdin.
990 @return The getwchar function returns the next wide character from the
991 input stream pointed to by stdin, or WEOF.
993 wint_t getwchar(void);
995 /** Write a character to an output stream.
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.
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.
1004 @return The putwc function returns the wide character written, or WEOF.
1006 wint_t putwc(wchar_t C
, FILE *Stream
);
1008 /** Write a character to stdout.
1010 The putwchar function is equivalent to putwc with the second argument stdout.
1012 @param[in] C The wide character to be written to stdout.
1014 @return The putwchar function returns the character written, or WEOF.
1016 wint_t putwchar(wchar_t C
);
1018 /** Return a character to the input Stream as if it had not been read.
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.
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.
1033 If the value of C equals that of the macro WEOF, the operation fails and the input stream is
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
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.
1046 @return The ungetwc function returns the character pushed back,
1047 or WEOF if the operation fails.
1049 wint_t ungetwc(wint_t C
, FILE *Stream
);
1051 /* ################### Numeric Conversions ########################### */
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.
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.
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
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
);
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.
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
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.
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
);
1110 /* ####################### String Copying ############################### */
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.
1115 @return The wcscpy function returns the value of Dest.
1117 wchar_t *wcscpy(wchar_t * __restrict Dest
, const wchar_t * __restrict Src
);
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.
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.
1127 @return The wcsncpy function returns the value of Dest.
1129 wchar_t *wcsncpy(wchar_t * __restrict Dest
, const wchar_t * __restrict Src
, size_t n
);
1131 /** The wmemcpy function copies n wide characters from the object pointed to by
1132 Src to the object pointed to by Dest.
1134 Use this function if you know that Dest and Src DO NOT Overlap. Otherwise,
1137 @return The wmemcpy function returns the value of Dest.
1139 wchar_t *wmemcpy(wchar_t * __restrict Dest
, const wchar_t * __restrict Src
, size_t n
);
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
1145 Because the UEFI BaseMemoryLib function CopyMem explicitly handles
1146 overlapping source and destination objects, this function and wmemcpy are
1147 implemented identically.
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
1153 @return The wmemmove function returns the value of Dest.
1155 wchar_t *wmemmove(wchar_t *Dest
, const wchar_t *Src
, size_t n
);
1157 /* ################### String Concatenation ########################## */
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.
1164 @return The wcscat function returns the value of Dest.
1166 wchar_t *wcscat(wchar_t * __restrict Dest
, const wchar_t * __restrict Src
);
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.
1174 @return The wcsncat function returns the value of Dest.
1176 wchar_t *wcsncat(wchar_t * __restrict Dest
, const wchar_t * __restrict Src
, size_t n
);
1178 /* ##################### String Comparison ############################# */
1180 /** The wcscmp function compares the wide string pointed to by s1 to the wide
1181 string pointed to by s2.
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
1188 int wcscmp(const wchar_t *s1
, const wchar_t *s2
);
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.
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
1200 int wcscoll(const wchar_t *s1
, const wchar_t *s2
);
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.
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.
1211 int wcsncmp(const wchar_t *s1
, const wchar_t *s2
, size_t n
);
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.
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.
1227 size_t wcsxfrm(wchar_t * __restrict s1
, const wchar_t * __restrict s2
, size_t n
);
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
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.
1237 int wmemcmp(const wchar_t *s1
, const wchar_t *s2
, size_t n
);
1239 /* ##################### String Searching ############################## */
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.
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
1249 wchar_t *wcschr(const wchar_t *S
, wchar_t C
);
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.
1255 @return The wcscspn function returns the length of the segment.
1257 size_t wcscspn(const wchar_t *s1
, const wchar_t *s2
);
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
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
1267 wchar_t *wcspbrk(const wchar_t *s1
, const wchar_t *s2
);
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.
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.
1276 wchar_t *wcsrchr(const wchar_t *S
, wchar_t C
);
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.
1282 @return The wcsspn function returns the length of the segment.
1284 size_t wcsspn(const wchar_t *s1
, const wchar_t *s2
);
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.
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.
1294 wchar_t *wcsstr(const wchar_t *s1
, const wchar_t *s2
);
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.
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.
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.
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.
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).
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.
1331 wchar_t *wcstok(wchar_t * __restrict s1
, const wchar_t * __restrict s2
, wchar_t ** __restrict ptr
);
1333 /** The wmemchr function locates the first occurrence of C in the initial n
1334 wide characters of the object pointed to by S.
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
1340 wchar_t *wmemchr(const wchar_t *S
, wchar_t C
, size_t n
);
1342 /* ################### String Manipulation ############################# */
1344 /** The wcslen function computes the length of the wide string pointed to by S.
1346 @return The wcslen function returns the number of wide characters that
1347 precede the terminating null wide character.
1349 size_t wcslen(const wchar_t *S
);
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.
1354 @return The wmemset function returns the value of S.
1356 wchar_t *wmemset(wchar_t *S
, wchar_t C
, size_t n
);
1358 /* ################# Date and Time Conversion ########################### */
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.
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
1375 size_t wcsftime(wchar_t * __restrict S
, size_t maxsize
, const wchar_t * __restrict format
, const struct tm
* __restrict timeptr
);
1377 /* ############# Multibyte <--> Wide Character Conversion ############### */
1379 /** The btowc function determines whether C constitutes a valid single-byte
1380 character in the initial shift state.
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.
1387 wint_t btowc(int C
);
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
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.
1398 int wctob(wint_t C
);
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.
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.
1407 int mbsinit(const mbstate_t *ps
);
1409 /* ####### Restartable Multibyte <--> Wide Character Conversion ######### */
1411 /** The mbrlen function is equivalent to the call:<BR>
1413 mbrtowc(NULL, s, n, ps != NULL ? ps : &internal)
1415 where internal is the mbstate_t object for the mbrlen function, except that
1416 the expression designated by ps is evaluated only once.
1418 @return The mbrlen function returns a value between zero and n,
1419 inclusive, (size_t)(-2), or (size_t)(-1).
1421 size_t mbrlen(const char * __restrict S
, size_t n
, mbstate_t * __restrict ps
);
1423 /** Restartable Multibyte to Wide character conversion.
1424 If S is a null pointer, the mbrtowc function is equivalent to the call:<BR>
1426 mbrtowc(NULL, "", 1, ps)
1429 In this case, the values of the parameters pwc and n are ignored.
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.
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.
1455 size_t mbrtowc(wchar_t * __restrict pwc
, const char * __restrict S
, size_t n
, mbstate_t * __restrict ps
);
1458 If S is a null pointer, the wcrtomb function is equivalent to the call:<BR>
1460 wcrtomb(buf, L'\0', ps)
1462 where buf is an internal buffer.
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.
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.
1477 size_t wcrtomb(char * __restrict S
, wchar_t wc
, mbstate_t * __restrict ps
);
1479 /** Convert a sequence of multibyte characters into a sequence of wide characters.
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.
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.
1496 @param[in] dst Destination for the Wide character sequence.
1497 @param[in] src Pointer to Pointer to MBCS char. sequence to convert.
1498 @param[in] len Length of dest, in WIDE characters.
1499 @param[in] ps Pointer to the conversion state object to be used for this conversion.
1501 @return If the input conversion encounters a sequence of bytes that do
1502 not form a valid multibyte character, an encoding error occurs:
1503 the mbsrtowcs function stores the value of the macro EILSEQ in
1504 errno and returns (size_t)(-1); the conversion state is
1505 unspecified. Otherwise, it returns the number of multibyte
1506 characters successfully converted, not including the terminating
1507 null character (if any).
1509 size_t mbsrtowcs(wchar_t * __restrict dst
, const char ** __restrict src
, size_t len
, mbstate_t * __restrict ps
);
1511 /** The wcsrtombs function converts a sequence of wide characters from the array
1512 indirectly pointed to by src into a sequence of corresponding multibyte
1513 characters that begins in the conversion state described by the object
1514 pointed to by ps. If dst is not a null pointer, the converted characters
1515 are then stored into the array pointed to by dst. Conversion continues
1516 up to and including a terminating null wide character, which is also
1517 stored. Conversion stops earlier in two cases: when a wide character is
1518 reached that does not correspond to a valid multibyte character, or
1519 (if dst is not a null pointer) when the next multibyte character would
1520 exceed the limit of len total bytes to be stored into the array pointed
1521 to by dst. Each conversion takes place as if by a call to the wcrtomb
1524 If dst is not a null pointer, the pointer object pointed to by src is
1525 assigned either a null pointer (if conversion stopped due to reaching
1526 a terminating null wide character) or the address just past the last wide
1527 character converted (if any). If conversion stopped due to reaching a
1528 terminating null wide character, the resulting state described is the
1529 initial conversion state.
1531 @param[in] dst Destination for the MBCS sequence.
1532 @param[in] src Pointer to Pointer to wide char. sequence to convert.
1533 @param[in] len Length of dest, in bytes.
1534 @param[in] ps Pointer to the conversion state object to be used for this conversion.
1536 @return If conversion stops because a wide character is reached that
1537 does not correspond to a valid multibyte character, an
1538 encoding error occurs: the wcsrtombs function stores the
1539 value of the macro EILSEQ in errno and returns (size_t)(-1);
1540 the conversion state is unspecified. Otherwise, it returns
1541 the number of bytes in the resulting multibyte character
1542 sequence, not including the terminating null character (if any).
1544 size_t wcsrtombs(char * __restrict dst
, const wchar_t ** __restrict src
, size_t len
, mbstate_t * __restrict ps
);
1546 #endif /* _WCHAR_H */
projects / mirror_edk2.git / blob