diff options
Diffstat (limited to 'StdLib/Include/wchar.h')
| -rw-r--r-- | StdLib/Include/wchar.h | 1552 |
1 files changed, 0 insertions, 1552 deletions
diff --git a/StdLib/Include/wchar.h b/StdLib/Include/wchar.h deleted file mode 100644 index 3acc2a4b8d..0000000000 --- a/StdLib/Include/wchar.h +++ /dev/null @@ -1,1552 +0,0 @@ -/** @file
- Extended multibyte and wide character utilities.
-
- Within this implementation, multibyte characters are represented using the
- Unicode UTF-8 encoding and wide characters are represented using the
- 16-bit UCS-2 encoding.
-
- Unless explicitly stated otherwise, if the execution of a function declared
- in this file causes copying to take place between objects that overlap, the
- behavior is undefined.
-
- The following macros are defined in this file:<BR>
- @verbatim
- NULL Actually defined in <sys/EfiCdefs.h>
- WCHAR_MIN Minimum value of a wide char.
- WCHAR_MAX Maximum value of a wide char.
- WEOF Wide char version of end-of-file.
- @endverbatim
-
- The following types are defined in this file:<BR>
- @verbatim
- size_t Unsigned integer type of the result of the sizeof operator.
- wchar_t Type of wide characters.
- wint_t Type capable of holding all wchar_t values and WEOF.
- mbstate_t Type of object holding multibyte conversion state.
- struct tm Incomplete declaration of the broken-down time structure.
- @endverbatim
-
- The following functions are declared in this file:<BR>
-@verbatim
- ############### Formatted Input/Output Functions
- int fwprintf (FILE * __restrict stream,
- const wchar_t * __restrict format, ...);
- int fwscanf (FILE * __restrict stream,
- const wchar_t * __restrict format, ...);
- int swprintf (wchar_t * __restrict s, size_t n,
- const wchar_t * __restrict format, ...);
- int swscanf (const wchar_t * __restrict s,
- const wchar_t * __restrict format, ...);
- int vfwprintf (FILE * __restrict stream,
- const wchar_t * __restrict format, va_list arg);
- int vfwscanf (FILE * __restrict stream,
- const wchar_t * __restrict format, va_list arg);
- int vswprintf (wchar_t * __restrict s, size_t n,
- const wchar_t * __restrict format, va_list arg);
- int vswscanf (const wchar_t * __restrict s,
- const wchar_t * __restrict format, va_list arg);
- int vwprintf (const wchar_t * __restrict format, va_list arg);
- int vwscanf (const wchar_t * __restrict format, va_list arg);
- int wprintf (const wchar_t * __restrict format, ...);
- int wscanf (const wchar_t * __restrict format, ...);
-
- ################### Input/Output Functions
- wint_t fgetwc (FILE *stream);
- wchar_t *fgetws (wchar_t * __restrict S, int n,
- FILE * __restrict stream);
- wint_t fputwc (wchar_t c, FILE *stream);
- int fputws (const wchar_t * __restrict S,
- FILE * __restrict stream);
- int fwide (FILE *stream, int mode);
- wint_t getwc (FILE *stream);
- wint_t getwchar (void);
- wint_t putwc (wchar_t c, FILE *stream);
- wint_t putwchar (wchar_t c);
- wint_t ungetwc (wint_t c, FILE *stream);
-
- ################### Numeric Conversions
- double wcstod (const wchar_t * __restrict nptr,
- wchar_t ** __restrict endptr);
- float wcstof (const wchar_t * __restrict nptr,
- wchar_t ** __restrict endptr);
- long double wcstold (const wchar_t * __restrict nptr,
- wchar_t ** __restrict endptr);
- long int wcstol (const wchar_t * __restrict nptr,
- wchar_t ** __restrict endptr, int base);
- long long int wcstoll (const wchar_t * __restrict nptr,
- wchar_t ** __restrict endptr, int base);
- unsigned long int wcstoul (const wchar_t * __restrict nptr,
- wchar_t ** __restrict endptr, int base);
- unsigned long long int wcstoull (const wchar_t * __restrict nptr,
- wchar_t ** __restrict endptr, int base);
-
- ####################### String Copying
- wchar_t *wcscpy (wchar_t * __restrict s1,
- const wchar_t * __restrict s2);
- wchar_t *wcsncpy (wchar_t * __restrict s1,
- const wchar_t * __restrict s2, size_t n);
- wchar_t *wmemcpy (wchar_t * __restrict s1,
- const wchar_t * __restrict s2, size_t n);
- wchar_t *wmemmove (wchar_t *s1, const wchar_t *s2, size_t n);
-
- ################### String Concatenation
- wchar_t *wcscat (wchar_t * __restrict s1,
- const wchar_t * __restrict s2);
- wchar_t *wcsncat (wchar_t * __restrict s1,
- const wchar_t * __restrict s2, size_t n);
-
- ##################### String Comparison
- int wcscmp (const wchar_t *s1, const wchar_t *s2);
- int wcscoll (const wchar_t *s1, const wchar_t *s2);
- int wcsncmp (const wchar_t *s1, const wchar_t *s2, size_t n);
- size_t wcsxfrm (wchar_t * __restrict s1,
- const wchar_t * __restrict s2, size_t n);
- int wmemcmp (const wchar_t *s1, const wchar_t *s2, size_t n);
-
- ##################### String Searching
- wchar_t *wcschr (const wchar_t *S, wchar_t c);
- size_t wcscspn (const wchar_t *s1, const wchar_t *s2);
- wchar_t *wcspbrk (const wchar_t *s1, const wchar_t *s2);
- wchar_t *wcsrchr (const wchar_t *S, wchar_t c);
- size_t wcsspn (const wchar_t *s1, const wchar_t *s2);
- wchar_t *wcsstr (const wchar_t *s1, const wchar_t *s2);
- wchar_t *wcstok (wchar_t * __restrict s1,
- const wchar_t * __restrict s2,
- wchar_t ** __restrict ptr);
- wchar_t *wmemchr (const wchar_t *S, wchar_t c, size_t n);
-
- ################### String Manipulation
- size_t wcslen (const wchar_t *S);
- wchar_t *wmemset (wchar_t *S, wchar_t c, size_t n);
-
- ################# Date and Time Conversion
- size_t wcsftime (wchar_t * __restrict S, size_t maxsize,
- const wchar_t * __restrict format,
- const struct tm * __restrict timeptr);
-
- ############# Multibyte <--> Wide Character Conversion
- wint_t btowc (int c);
- int wctob (wint_t c);
- int mbsinit (const mbstate_t *ps);
-
- ####### Restartable Multibyte <--> Wide Character Conversion
- size_t mbrlen (const char * __restrict S, size_t n,
- mbstate_t * __restrict ps);
- size_t mbrtowc (wchar_t * __restrict pwc, const char * __restrict S,
- size_t n, mbstate_t * __restrict ps);
- size_t wcrtomb (char * __restrict S, wchar_t wc,
- mbstate_t * __restrict ps);
- size_t mbsrtowcs (wchar_t * __restrict dst,
- const char ** __restrict src, size_t len,
- mbstate_t * __restrict ps);
- size_t wcsrtombs (char * __restrict dst,
- const wchar_t ** __restrict src,
- size_t len, mbstate_t * __restrict ps);
-@endverbatim
-
- @note Properly constructed programs will take the following into consideration:
- - wchar_t and wint_t may be the same integer type.
- - WEOF might be a different value than that of EOF.
- - WEOF might not be negative.
- - mbstate_t objects are not intended to be inspected by programs.
-
- Copyright (c) 2010 - 2014, Intel Corporation. All rights reserved.<BR>
- This program and the accompanying materials are licensed and made available under
- the terms and conditions of the BSD License that accompanies this distribution.
- The full text of the license may be found at
- http://opensource.org/licenses/bsd-license.
-
- THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
- WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
-**/
-#ifndef _WCHAR_H
-#define _WCHAR_H
-#include <sys/EfiCdefs.h>
-#include <machine/ansi.h>
-#include <machine/limits.h>
-#include <stdarg.h>
-#include <stdio.h>
-
-#if defined(_MSC_VER)
- #pragma warning ( disable : 4142 )
-#endif
-
-#ifdef _EFI_SIZE_T_
- typedef _EFI_SIZE_T_ size_t; /**< Unsigned integer type of the result of the sizeof operator. */
- #undef _BSD_SIZE_T_
- #undef _EFI_SIZE_T_
-#endif
-
-#ifndef __cplusplus
- #ifdef _EFI_WCHAR_T
- /** An integer type capable of representing all distinct codes in the
- UCS-2 encoding supported by UEFI.
- **/
- typedef _EFI_WCHAR_T wchar_t;
- #undef _BSD_WCHAR_T_
- #undef _EFI_WCHAR_T
- #endif
-#endif
-
-#ifdef _BSD_MBSTATE_T_
- /** mbstate_t is an opaque object, that is not an array type, used to keep
- conversion state during multibyte stream conversions.
- */
- typedef _BSD_MBSTATE_T_ mbstate_t;
- #undef _BSD_MBSTATE_T_
-#endif
-
-#ifdef _EFI_WINT_T
- /** wint_t is an integer type unchanged by default argument promotions that can
- hold any value corresponding to members of the extended character set, as
- well as at least one value that does not correspond to any member of the
- extended character set: WEOF.
- */
- typedef _EFI_WINT_T wint_t;
- #undef _BSD_WINT_T_
- #undef _EFI_WINT_T
-#endif
-
-#ifndef WCHAR_MIN
- /** @{
- Since wchar_t is an unsigned 16-bit value, it has a minimum value of 0, and
- a maximum value defined by __USHRT_MAX (65535 on IA processors).
- */
- #define WCHAR_MIN 0
- #define WCHAR_MAX __USHRT_MAX
- /*@}*/
-#endif
-
-#ifndef WEOF
- /** WEOF expands to a constant expression of type wint_t whose value does not
- correspond to any member of the extended character set. It is accepted
- (and returned) by several functions, declared in this file, to indicate
- end-of-file, that is, no more input from a stream. It is also used as a
- wide character value that does not correspond to any member of the
- extended character set.
- */
- #define WEOF ((wint_t)-1)
-#endif
-
-/* limits of wint_t -- These are NOT specified by ISO/IEC 9899 */
-#ifndef WINT_MIN
- #define WINT_MIN _EFI_WINT_MIN /* wint_t */
- #define WINT_MAX _EFI_WINT_MAX /* wint_t */
-#endif
-
-/** Type struct tm is declared here as an incomplete structure type for use as an argument
- type by the wcsftime function. The full structure declaration is in <time.h>.
-*/
-struct tm;
-
-/* ############### Formatted Input/Output Functions ##################### */
-
-/** The fwprintf function writes output to the stream pointed to by stream,
- under control of the wide string pointed to by format that specifies how
- subsequent arguments are converted for output. If there are insufficient
- arguments for the format, the behavior is undefined. If the format is
- exhausted while arguments remain, the excess arguments are evaluated
- (as always) but are otherwise ignored. The fwprintf function returns
- when the end of the format string is encountered.
-
- The format is composed of zero or more directives: ordinary wide characters
- (not %), which are copied unchanged to the output stream; and conversion
- specifications, each of which results in fetching zero or more subsequent
- arguments, converting them, if applicable, according to the corresponding
- conversion specifier, and then writing the result to the output stream.
-
- Each conversion specification is introduced by the wide character %. After
- the %, the following appear in sequence:
- * Zero or more flags (in any order) that modify the meaning of the
- conversion specification.
- * An optional minimum field width. If the converted value has fewer wide
- characters than the field width, it is padded with spaces (by default)
- on the left (or right, if the left adjustment flag, described later,
- has been given) to the field width. The field width takes the form of
- an asterisk * (described later) or a nonnegative decimal integer.
- * An optional precision that gives the minimum number of digits to appear
- for the d, i, o, u, x, and X conversions, the number of digits to
- appear after the decimal-point wide character for e, E, f, and F
- conversions, the maximum number of significant digits for the g and G
- conversions, or the maximum number of wide characters to be written
- for s conversions. The precision takes the form of a period (.)
- followed either by an asterisk * (described later) or by an optional
- decimal integer; if only the period is specified, the precision is
- taken as zero. If a precision appears with any other conversion
- specifier, the behavior is undefined.
- * An optional length modifier that specifies the size of the argument.
- * A conversion specifier wide character that specifies the type of
- conversion to be applied.
-
- As noted above, a field width, or precision, or both, may be indicated by
- an asterisk. In this case, an int argument supplies the field width or
- precision. The arguments specifying field width, or precision, or both,
- must appear (in that order) before the argument (if any) to be converted.
- A negative field width argument is taken as a - flag followed by a positive
- field width. A negative precision argument is taken as if the precision
- were omitted.
-
- The flag wide characters and their meanings are:<BR>
- - The result of the conversion is left-justified within the field.
- (It is right-justified if this flag is not specified.)
- + The result of a signed conversion always begins with a plus or minus
- sign. (It begins with a sign only when a negative value is converted
- if this flag is not specified.)
- space If the first wide character of a signed conversion is not a sign, or
- if a signed conversion results in no wide characters, a space is
- prefixed to the result. If the space and + flags both appear, the
- space flag is ignored.
- # The result is converted to an "alternative form". For o conversion,
- it increases the precision, if and only if necessary, to force the
- first digit of the result to be a zero (if the value and precision
- are both 0, a single 0 is printed). For x (or X) conversion, a
- nonzero result has 0x (or 0X) prefixed to it. For e, E, f, F, g,
- and G conversions, the result of converting a floating-point number
- always contains a decimal-point wide character, even if no digits
- follow it. (Normally, a decimal-point wide character appears in the
- result of these conversions only if a digit follows it.) For g and G
- conversions, trailing zeros are not removed from the result. For
- other conversions, the behavior is undefined.
- 0 For d, i, o, u, x, X, e, E, f, F, g, and G conversions, leading zeros
- (following any indication of sign or base) are used to pad to the
- field width rather than performing space padding, except when
- converting an infinity or NaN. If the 0 and - flags both appear,
- the 0 flag is ignored. For d, i, o, u, x, and X conversions, if a
- precision is specified, the 0 flag is ignored. For other conversions,
- the behavior is undefined.
-
- The length modifiers and their meanings are:<BR>
- hh Specifies that a following d, i, o, u, x, or X conversion specifier
- applies to a signed char or unsigned char argument (the argument
- will have been promoted according to the integer promotions, but its
- value shall be converted to signed char or unsigned char before
- printing); or that a following n conversion specifier applies to a
- pointer to a signed char argument.
- h Specifies that a following d, i, o, u, x, or X conversion specifier
- applies to a short int or unsigned short int argument (the argument
- will have been promoted according to the integer promotions, but its
- value shall be converted to short int or unsigned short int before
- printing); or that a following n conversion specifier applies to a
- pointer to a short int argument.
- l (ell) Specifies that a following d, i, o, u, x, or X conversion
- specifier applies to a long int or unsigned long int argument;
- that a following n conversion specifier applies to a pointer to a
- long int argument; that a following c conversion specifier
- applies to a wint_t argument; that a following s conversion
- specifier applies to a pointer to a wchar_t argument; or has no
- effect on a following e, E, f, F, g, or G conversion specifier.
- ll (ell-ell) Specifies that a following d, i, o, u, x, or X conversion
- specifier applies to a long long int or unsigned long long int
- argument; or that a following n conversion specifier applies
- to a pointer to a long long int argument.
- j Specifies that a following d, i, o, u, x, or X conversion specifier
- applies to an intmax_t or uintmax_t argument; or that a following
- n conversion specifier applies to a pointer to an intmax_t argument.
- z Specifies that a following d, i, o, u, x, or X conversion specifier
- applies to a size_t or the corresponding signed integer type
- argument; or that a following n conversion specifier applies to a
- pointer to a signed integer type corresponding to size_t argument.
- t Specifies that a following d, i, o, u, x, or X conversion specifier
- applies to a ptrdiff_t or the corresponding unsigned integer type
- argument; or that a following n conversion specifier applies to a
- pointer to a ptrdiff_t argument.
- L Specifies that a following a, A, e, E, f, F, g, or G conversion
- specifier applies to a long double argument.
-
- If a length modifier appears with any conversion specifier other than as
- specified above, the behavior is undefined.
-
- The conversion specifiers and their meanings are:<BR>
- d,i The int argument is converted to signed decimal in the
- style [-]dddd. The precision specifies the minimum number of digits
- to appear; if the value being converted can be represented in fewer
- digits, it is expanded with leading zeros. The default precision
- is 1. The result of converting a zero value with a precision of
- zero is no wide characters.
- o,u,x,X The unsigned int argument is converted to unsigned octal (o),
- unsigned decimal (u), or unsigned hexadecimal notation (x or X) in
- the style dddd; the letters abcdef are used for x conversion and
- the letters ABCDEF for X conversion. The precision specifies the
- minimum number of digits to appear; if the value being converted
- can be represented in fewer digits, it is expanded with leading
- zeros. The default precision is 1. The result of converting a zero
- value with a precision of zero is no wide characters.
- f,F A double argument representing a floating-point number is converted
- to decimal notation in the style [-]ddd.ddd, where the number of
- digits after the decimal-point wide character is equal to the
- precision specification. If the precision is missing, it is taken
- as 6; if the precision is zero and the # flag is not specified, no
- decimal-point wide character appears. If a decimal-point wide
- character appears, at least one digit appears before it. The value
- is rounded to the appropriate number of digits.<BR>
- A double argument representing an infinity is converted to [-]inf.
- A double argument representing a NaN is converted to [-]nan.
- The F conversion specifier produces INF or NAN instead
- of inf or nan, respectively.
- e,E A double argument representing a floating-point number is converted
- in the style [-]d.ddd e +/- dd, where there is one digit (which is
- nonzero if the argument is nonzero) before the decimal-point wide
- character and the number of digits after it is equal to the
- precision; if the precision is missing, it is taken as 6; if the
- precision is zero and the # flag is not specified, no decimal-point
- wide character appears. The value is rounded to the appropriate
- number of digits. The E conversion specifier produces a number with
- E instead of e introducing the exponent. The exponent always
- contains at least two digits, and only as many more digits as
- necessary to represent the exponent. If the value is zero, the
- exponent is zero. A double argument representing an infinity or NaN
- is converted in the style of an f or F conversion specifier.
- g,G A double argument representing a floating-point number is converted
- in style f or e (or in style F or E in the case of a G conversion
- specifier), depending on the value converted and the precision.
- Let P equal the precision if nonzero, 6 if the precision is
- omitted, or 1 if the precision is zero. Then, if a conversion with
- style E would have an exponent of X:
- - if P > X = -4, the conversion is with style f (or F) and
- precision P - (X + 1).
- - otherwise, the conversion is with style e (or E) and
- precision P - 1.
- Finally, unless the # flag is used, any trailing zeros are removed
- from the fractional portion of the result and the decimal-point
- wide character is removed if there is no fractional portion
- remaining. A double argument representing an infinity or NaN is
- converted in the style of an f or F conversion specifier.
- c If no l length modifier is present, the int argument is converted
- to a wide character as if by calling btowc and the resulting wide
- character is written. If an l length modifier is present, the
- wint_t argument is converted to wchar_t and written.
- s If no l length modifier is present, the argument shall be a pointer
- to the initial element of a character array containing a multibyte
- character sequence beginning in the initial shift state. Characters
- from the array are converted as if by repeated calls to the mbrtowc
- function, with the conversion state described by an mbstate_t
- object initialized to zero before the first multibyte character is
- converted, and written up to (but not including) the terminating
- null wide character. If the precision is specified, no more than
- that many wide characters are written. If the precision is not
- specified or is greater than the size of the converted array, the
- converted array shall contain a null wide character.<BR>
- If an l length modifier is present, the argument shall be a pointer
- to the initial element of an array of wchar_t type. Wide characters
- from the array are written up to (but not including) a terminating
- null wide character. If the precision is specified, no more than
- that many wide characters are written. If the precision is not
- specified or is greater than the size of the array, the array
- shall contain a null wide character.
- p The argument shall be a pointer to void. The value of the pointer
- is converted to a sequence of printing wide characters, in an
- implementation-defined manner.
- n The argument shall be a pointer to signed integer into which is
- written the number of wide characters written to the output stream
- so far by this call to fwprintf. No argument is converted, but one
- is consumed. If the conversion specification includes any flags, a
- field width, or a precision, the behavior is undefined.
- % A % wide character is written. No argument is converted. The
- complete conversion specification is %%.
-
-
- @param[in] stream An open File specifier to which the output is sent.
- @param[in] format A wide character sequence containing characters
- to be copied unchanged, and conversion specifiers
- which convert their associated arguments.
- @param ... Variable number of parameters as required by format.
-
- @return The fwprintf function returns the number of wide characters
- transmitted, or a negative value if an output or encoding error
- occurred.
-**/
-int fwprintf(FILE * __restrict stream, const wchar_t * __restrict format, ...);
-
-/** The fwscanf function reads input from the stream pointed to by stream,
- under control of the wide string pointed to by format that specifies
- the admissible input sequences and how they are to be converted for
- assignment, using subsequent arguments as pointers to the objects to
- receive the converted input. If there are insufficient arguments for
- the format, the behavior is undefined. If the format is exhausted while
- arguments remain, the excess arguments are evaluated (as always) but are
- otherwise ignored.
-
- The format is composed of zero or more directives: one or more white-space
- wide characters, an ordinary wide character (neither % nor a white-space
- wide character), or a conversion specification. Each conversion
- specification is introduced by the wide character %. After the %, the
- following appear in sequence:
- - An optional assignment-suppressing wide character *.
- - An optional decimal integer greater than zero that specifies the
- maximum field width (in wide characters).
- - An optional length modifier that specifies the size of the receiving object.
- - A conversion specifier wide character that specifies the type of
- conversion to be applied.
-
- The fwscanf function executes each directive of the format in turn. If a
- directive fails, as detailed below, the function returns. Failures are
- described as input failures (due to the occurrence of an encoding error
- or the unavailability of input characters), or matching failures
- (due to inappropriate input).
-
- A directive composed of white-space wide character(s) is executed by
- reading input up to the first non-white-space wide character (which remains
- unread), or until no more wide characters can be read.
-
- A directive that is an ordinary wide character is executed by reading the
- next wide character of the stream. If that wide character differs from the
- directive, the directive fails and the differing and subsequent wide
- characters remain unread. Similarly, if end-of-file, an encoding error, or
- a read error prevents a wide character from being read, the directive fails.
-
- A directive that is a conversion specification defines a set of matching
- input sequences, as described below for each specifier. A conversion
- specification is executed in the following steps:
- - Input white-space wide characters (as specified by the iswspace
- function) are skipped, unless the specification includes
- a [, c, or n specifier.
- - An input item is read from the stream, unless the specification
- includes an n specifier. An input item is defined as the longest
- sequence of input wide characters which does not exceed any specified
- field width and which is, or is a prefix of, a matching input sequence.
- The first wide character, if any, after the input item remains unread.
- If the length of the input item is zero, the execution of the directive
- fails; this condition is a matching failure unless end-of-file, an
- encoding error, or a read error prevented input from the stream, in
- which case it is an input failure.
- - Except in the case of a % specifier, the input item (or, in the case of
- a %n directive, the count of input wide characters) is converted to a
- type appropriate to the conversion specifier. If the input item is not
- a matching sequence, the execution of the directive fails: this
- condition is a matching failure. Unless assignment suppression was
- indicated by a *, the result of the conversion is placed in the object
- pointed to by the first argument following the format argument that has
- not already received a conversion result. If this object does not have
- an appropriate type, or if the result of the conversion cannot be
- represented in the object, the behavior is undefined.
-
- The length modifiers and their meanings are:<BR>
- hh Specifies that a following d, i, o, u, x, X, or n conversion
- specifier applies to an argument with type pointer to signed char
- or unsigned char.
- h Specifies that a following d, i, o, u, x, X, or n conversion
- specifier applies to an argument with type pointer to short int
- or unsigned short int.
- l (ell) Specifies that a following d, i, o, u, x, X, or n conversion
- specifier applies to an argument with type pointer to long int or
- unsigned long int; that a following e, E, f, F, g, or G conversion
- specifier applies to an argument with type pointer to double; or
- that a following c, s, or [ conversion specifier applies to an
- argument with type pointer to wchar_t.
- ll (ell-ell) Specifies that a following d, i, o, u, x, X, or n conversion
- specifier applies to an argument with type
- pointer to long long int or unsigned long long int.
- j Specifies that a following d, i, o, u, x, X, or n conversion
- specifier applies to an argument with type pointer to intmax_t
- or uintmax_t.
- z Specifies that a following d, i, o, u, x, X, or n conversion
- specifier applies to an argument with type pointer to size_t or the
- corresponding signed integer type.
- t Specifies that a following d, i, o, u, x, X, or n conversion
- specifier applies to an argument with type pointer to ptrdiff_t or
- the corresponding unsigned integer type.
- L Specifies that a following e, E, f, F, g, or G conversion specifier
- applies to an argument with type pointer to long double.
-
- If a length modifier appears with any conversion specifier other than as
- specified above, the behavior is undefined.
-
- The conversion specifiers and their meanings are:<BR>
- d Matches an optionally signed decimal integer, whose format is the
- same as expected for the subject sequence of the wcstol function
- with the value 10 for the base argument. The corresponding argument
- shall be a pointer to signed integer.
- i Matches an optionally signed integer, whose format is the same as
- expected for the subject sequence of the wcstol function with the
- value 0 for the base argument. The corresponding argument shall be
- a pointer to signed integer.
- o Matches an optionally signed octal integer, whose format is the
- same as expected for the subject sequence of the wcstoul function
- with the value 8 for the base argument. The corresponding argument
- shall be a pointer to unsigned integer.
- u Matches an optionally signed decimal integer, whose format is the
- same as expected for the subject sequence of the wcstoul function
- with the value 10 for the base argument. The corresponding argument
- shall be a pointer to unsigned integer.
- x Matches an optionally signed hexadecimal integer, whose format is
- the same as expected for the subject sequence of the wcstoul
- function with the value 16 for the base argument. The corresponding
- argument shall be a pointer to unsigned integer.
- e,f,g Matches an optionally signed floating-point number, infinity, or
- NaN, whose format is the same as expected for the subject sequence
- of the wcstod function. The corresponding argument shall be a
- pointer to float.
- c Matches a sequence of wide characters of exactly the number
- specified by the field width (1 if no field width is present in the
- directive).<BR>
- If no l length modifier is present, characters from the input field
- are converted as if by repeated calls to the wcrtomb function, with
- the conversion state described by an mbstate_t object initialized
- to zero before the first wide character is converted. The
- corresponding argument shall be a pointer to the initial element of
- a character array large enough to accept the sequence. No null
- character is added.<BR>
- If an l length modifier is present, the corresponding argument
- shall be a pointer to the initial element of an array of
- wchar_t large enough to accept the sequence.
- No null wide character is added.
- s Matches a sequence of non-white-space wide characters.
- If no l length modifier is present, characters from the input field
- are converted as if by repeated calls to the wcrtomb function, with
- the conversion state described by an mbstate_t object initialized
- to zero before the first wide character is converted. The
- corresponding argument shall be a pointer to the initial element of
- a character array large enough to accept the sequence and a
- terminating null character, which will be added automatically.<BR>
- If an l length modifier is present, the corresponding argument
- shall be a pointer to the initial element of an array of wchar_t
- large enough to accept the sequence and the terminating null wide
- character, which will be added automatically.
- [ Matches a nonempty sequence of wide characters from a set of
- expected characters (the scanset).<BR>
- If no l length modifier is present, characters from the input field
- are converted as if by repeated calls to the wcrtomb function, with
- the conversion state described by an mbstate_t object initialized
- to zero before the first wide character is converted. The
- corresponding argument shall be a pointer to the initial element of
- a character array large enough to accept the sequence and a
- terminating null character, which will be added automatically.<BR>
- If an l length modifier is present, the corresponding argument
- shall be a pointer to the initial element of an array of wchar_t
- large enough to accept the sequence and the terminating null wide
- character, which will be added automatically.<BR>
- The conversion specifier includes all subsequent wide characters
- in the format string, up to and including the matching right
- bracket (]). The wide characters between the brackets
- (the scanlist) compose the scanset, unless the wide character after
- the left bracket is a circumflex (^), in which case the scanset
- contains all wide characters that do not appear in the scanlist
- between the circumflex and the right bracket. If the conversion
- specifier begins with [] or [^], the right bracket wide character
- is in the scanlist and the next following right bracket wide
- character is the matching right bracket that ends the specification;
- otherwise the first following right bracket wide character is the
- one that ends the specification. If a - wide character is in the
- scanlist and is not the first, nor the second where the first wide
- character is a ^, nor the last character,
- the - is added to the scanset.
- p Matches the set of sequences produced by the %p conversion of the
- fwprintf function. The corresponding argument is a pointer to a
- pointer to void. The input item is converted to a pointer value. If
- the input item is a value converted earlier during the same program
- execution, the pointer that results will compare equal to that
- value.
- n No input is consumed. The corresponding argument is a pointer to
- signed integer into which is to be written the number of wide
- characters read from the input stream so far by this call to the
- fwscanf function. Execution of a %n directive does not increment
- the assignment count returned at the completion of execution of the
- fwscanf function. No argument is converted, but one is consumed.
- % Matches a single % wide character; no conversion or assignment
- occurs. The complete conversion specification shall be %%.
-
- The conversion specifiers E, F, G, and X are also valid and behave the same
- as, respectively, e, f, g, and x.
-
- Trailing white space (including new-line wide characters) is left unread
- unless matched by a directive. The success of literal matches and
- suppressed assignments is not directly determinable other than via
- the %n directive.
-
- @param[in] stream An open File specifier from which the input is read.
- @param[in] format A wide character sequence containing characters
- to be matched against, and conversion specifiers
- which convert their associated arguments. Converted
- items are stored according to their associated arguments.
- @param ... Variable number of parameters, as required by format,
- specifying the objects to receive the converted input.
-
- @return The fwscanf function returns the value of the macro EOF if an
- input failure occurs before any conversion. Otherwise, the
- function returns the number of input items assigned, which can be
- fewer than provided for, or even zero, in the event of an early
- matching failure.
-**/
-int fwscanf(FILE * __restrict stream, const wchar_t * __restrict format, ...);
-
-/** Formatted wide-character output to a buffer.
-
- The swprintf function is equivalent to fwprintf, except that the argument s
- specifies an array of wide characters into which the generated output is to
- be written, rather than written to a stream. No more than n wide characters
- are written, including a terminating null wide character, which is always
- added (unless n is zero).
-
- @param[out] s A pointer to the array to receive the formatted output.
- @param[in] n Maximum number of characters to write into buffer s.
- @param[in] format A wide character sequence containing characters
- to be copied unchanged, and conversion specifiers
- which convert their associated arguments. Copied and
- converted characters are written to the array pointed
- to by s.
- @param ... Variable number of parameters as required by format.
-
- @return The swprintf function returns the number of wide characters
- written in the array, not counting the terminating null wide
- character, or a negative value if an encoding error occurred or
- if n or more wide characters were requested to be written.
-**/
-int swprintf(wchar_t * __restrict s, size_t n, const wchar_t * __restrict format, ...);
-
-/** Formatted wide input from a string.
-
- The swscanf function is equivalent to fwscanf, except that the argument
- Buff specifies a wide string from which the input is to be obtained, rather
- than from a stream. Reaching the end of the wide string is equivalent to
- encountering end-of-file for the fwscanf function.
-
- @param[in] Buff Pointer to the string from which to obtain input.
- @param[in] Format A wide character sequence containing characters
- to be matched against, and conversion specifiers
- which convert their associated arguments.
- @param[out] ... Variable number of parameters, as required by format,
- specifying the objects to receive the converted input.
-
- @return The swscanf function returns the value of the macro EOF if an
- input failure occurs before any conversion. Otherwise, the
- swscanf function returns the number of input items assigned,
- which can be fewer than provided for, or even zero, in the event
- of an early matching failure.
-**/
-int swscanf(const wchar_t * __restrict Buff, const wchar_t * __restrict Format, ...);
-
-/** Print formatted values from an argument list.
-
-The vfwprintf function is equivalent to fwprintf, with the variable argument list
-replaced by Args, which shall have been initialized by the va_start macro (and
-possibly subsequent va_arg calls). The vfwprintf function does not invoke the
-va_end macro.
-
- @param[in] Stream The output stream to receive the formatted output.
- @param[in] Format A wide character sequence containing characters
- to be matched against, and conversion specifiers
- which convert their associated arguments.
- @param[in] Args A list of arguments, initialized by the va_start macro
- and accessed using the va_arg macro, used to satisfy
- the directives in the Format string.
-
- @return The vfwprintf function returns the number of wide characters
- transmitted, or a negative value if an output or encoding
- error occurred.
-**/
-int vfwprintf(FILE * __restrict Stream, const wchar_t * __restrict Format, va_list Args);
-
-/** Formatted input from a stream.
-
- The vfwscanf function is equivalent to fwscanf, with the variable argument
- list replaced by Args, which must have been initialized by the va_start
- macro (and possibly subsequent va_arg calls). The vfwscanf function does
- not invoke the va_end macro.
-
- @param[in] Stream The input stream.
- @param[in] Format A wide character sequence containing characters
- to be matched against, and conversion specifiers
- which convert their associated arguments.
- @param[in] Args A list of arguments, initialized by the va_start macro
- and accessed using the va_arg macro, used to satisfy
- the directives in the Format string.
-
- @return The vfwscanf function returns the value of the macro EOF if an
- input failure occurs before any conversion. Otherwise, the
- vfwscanf function returns the number of input items assigned,
- which can be fewer than provided for, or even zero, in the event
- of an early matching failure.
-**/
-int vfwscanf(FILE * __restrict Stream, const wchar_t * __restrict Format, va_list Args);
-
-/** Formatted print, to a buffer, from an argument list.
-
- The vswprintf function is equivalent to swprintf, with the variable
- argument list replaced by Args, which must have been initialized by the
- va_start macro (and possibly subsequent va_arg calls). The vswprintf
- function does not invoke the va_end macro.
-
- @param[in] S A pointer to the array to receive the formatted output.
- @param[in] N Maximum number of characters to write into array S.
- @param[in] Format A wide character sequence containing characters
- to be matched against, and conversion specifiers
- which convert their associated arguments.
- @param[in] Args A list of arguments, initialized by the va_start macro
- and accessed using the va_arg macro, used to satisfy
- the directives in the Format string.
-
- @return The vswprintf function returns the number of wide characters
- written in the array, not counting the terminating null wide
- character, or a neg ative value if an encoding error occurred or
- if n or more wide characters were requested to be generated.
-**/
-int vswprintf(wchar_t * __restrict S, size_t N, const wchar_t * __restrict Format, va_list Args);
-
-/** Formatted input from a string, using an argument list.
-
- The vswscanf function is equivalent to swscanf, with the variable argument
- list replaced by Args, which must have been initialized by the va_start
- macro. The vswscanf function does not invoke the va_end macro.
-
- @param[in] S Pointer to the string from which to obtain input.
- @param[in] Format A wide character sequence containing characters
- to be matched against, and conversion specifiers
- which convert their associated arguments.
- @param[out] Args A list of arguments, initialized by the va_start macro
- and accessed using the va_arg macro, used to satisfy
- the directives in the Format string.
-
- @return The vswscanf function returns the value of the macro EOF if an
- input failure occurs before any conversion. Otherwise, the
- vswscanf function returns the number of input items assigned,
- which can be fewer than provided for, or even zero, in the event
- of an early matching failure.
-**/
-int vswscanf(const wchar_t * __restrict S, const wchar_t * __restrict Format, va_list Args);
-
-/** Formatted print, to stdout, from an argument list.
-
- The vwprintf function is equivalent to wprintf, with the variable argument
- list replaced by Args, which must have been initialized by the va_start
- macro. The vwprintf function does not invoke the va_end macro.
-
- @param[in] Format A wide character sequence containing characters
- to be matched against, and conversion specifiers
- which convert their associated arguments.
- @param[out] Args A list of arguments, initialized by the va_start macro
- and accessed using the va_arg macro, used to satisfy
- the directives in the Format string.
-
- @return The vwprintf function returns the number of wide characters
- transmitted, or a negative value if an output or encoding error
- occurred.
-**/
-int vwprintf(const wchar_t * __restrict Format, va_list Args);
-
-/** Formatted input, from stdin, to an argument list.
-
- The vwscanf function is equivalent to wscanf, with the variable argument
- list replaced by arg, which shall have been initialized by the va_start
- macro. The vwscanf function does not invoke the va_end macro.
-
- @param[in] Format A wide character sequence containing characters
- to be matched against, and conversion specifiers
- which convert their associated arguments.
- @param[out] Args A list of arguments, initialized by the va_start macro
- and accessed using the va_arg macro, used to satisfy
- the directives in the Format string.
-
- @return The vwscanf function returns the value of the macro EOF if an
- input failure occurs before any conversion. Otherwise, the
- vwscanf function returns the number of input items assigned,
- which can be fewer than provided for, or even zero, in the event
- of an early matching failure.
-**/
-int vwscanf(const wchar_t * __restrict Format, va_list Args);
-
-/** Formatted print to stdout.
-
- The wprintf function is equivalent to fwprintf with the argument stdout
- specifying the output stream.
-
- @param[in] format A wide character sequence containing characters
- to be copied unchanged, and conversion specifiers
- which convert their associated arguments.
- @param ... Variable number of parameters as required by format.
-
- @return The wprintf function returns the number of wide characters
- transmitted, or a negative value if an output or encoding error
- occurred.
-**/
-int wprintf(const wchar_t * __restrict Format, ...);
-
-/** Formatted input from stdin.
-
- The wscanf function is equivalent to fwscanf with the argument stdin
- specifying the input stream.
-
- @param[in] format A wide character sequence containing characters
- to be matched against, and conversion specifiers
- which convert their associated arguments. Converted
- items are stored according to their associated arguments.
- @param ... Variable number of parameters, as required by format,
- specifying the objects to receive the converted input.
-
- @return The wscanf function returns the value of the macro EOF if an
- input failure occurs before any conversion. Otherwise, the
- wscanf function returns the number of input items assigned,
- which can be fewer than provided for, or even zero, in the event
- of an early matching failure.
-**/
-int wscanf(const wchar_t * __restrict format, ...);
-
-/* ################### Input/Output Functions ########################### */
-
-
-/** Get a character from an input Stream.
-
-If the end-of-file indicator for the input stream pointed to by stream is not set and a
-next wide character is present, the fgetwc function obtains that wide character as a
-wchar_t converted to a wint_t and advances the associated file position indicator for
-the stream (if defined).
-
- @param[in] Stream An input stream from which to obtain a character.
-
- @return If the end-of-file indicator for the stream is set, or if the stream is at end-of-file, the endof-
-file indicator for the stream is set and the fgetwc function returns WEOF. Otherwise,
-the fgetwc function returns the next wide character from the input stream pointed to by
-stream. If a read error occurs, the error indicator for the stream is set and the fgetwc
-function returns WEOF. If an encoding error occurs (including too few bytes), the value of
-the macro EILSEQ is stored in errno and the fgetwc function returns WEOF.
-**/
-wint_t fgetwc(FILE *Stream);
-
-/** Read a string from an input stream into a buffer.
-
- The fgetws function reads at most one less than the number of
- wide characters specified by n from the stream pointed to by
- stream into the array pointed to by s. No additional wide
- characters are read after a new-line wide character (which is
- retained) or after end-of-file. A null wide character is written
- immediately after the last wide character read into the array.
-
- @param[out] S A pointer to the array to receive the input string.
- @param[in] Limit The maximum number of characters to put into Buff,
- including the terminating null character.
- @param[in] Stream An input stream from which to obtain the string.
-
- @return The fgetws function returns S if successful. If end-of-file is
- encountered and no characters have been read into the array, the
- contents of the array remain unchanged and a null pointer is
- returned. If a read or encoding error occurs during the
- operation, the array contents are indeterminate and a
- null pointer is returned.
-**/
-wchar_t *fgetws(wchar_t * __restrict S, int Limit, FILE * __restrict Stream);
-
-/** Write a character to an output stream.
-
-The fputwc function writes the wide character specified by c to the output stream
-pointed to by stream, at the position indicated by the associated file position indicator
-for the stream (if defined), and advances the indicator appropriately. If the file cannot
-support positioning requests, or if the stream was opened with append mode, the
-character is appended to the output stream.
-
- @param[in] C The character to be written to Stream.
- @param[in] Stream The output stream that C is to be written to.
-
- @return The fputwc function returns the wide character written. If a write error occurs, the
-error indicator for the stream is set and fputwc returns WEOF. If an encoding error
-occurs, the value of the macro EILSEQ is stored in errno and fputwc returns WEOF.
-**/
-wint_t fputwc(wchar_t C, FILE *Stream);
-
-/** Write a string to an output stream.
-
-The fputws function writes the wide string pointed to by S to the stream pointed to by
-Stream. The terminating null wide character is not written.
-
- @param[in] String The character string to be written to Stream.
- @param[in] Stream The output stream that String is to be written to.
-
- @return The fputws function returns EOF if a write or encoding error occurs; otherwise, it
-returns a nonnegative value.
-**/
-int fputws(const wchar_t * __restrict S, FILE * __restrict Stream);
-
-/** Query or set a stream's orientation.
-
-The fwide function determines the orientation of the stream pointed to by stream. If
-Mode is greater than zero, the function first attempts to make the stream wide oriented. If
-Mode is less than zero, the function first attempts to make the stream byte oriented.
-Otherwise, Mode is zero and the function does not alter the orientation of the stream.
-
- @param[in] Stream The stream to be queried.
- @param[in] Mode Control value selecting between quering or setting
- the Stream's orientation.
- @return The fwide function returns a value greater than zero if, after the call, the stream has
-wide orientation, a value less than zero if the stream has byte orientation, or zero if the
-stream has no orientation.
-**/
-int fwide(FILE *Stream, int Mode);
-
-/** Get a character from an input stream.
-
-The getwc function is equivalent to fgetwc, except that if it is implemented as a
-macro, it may evaluate Stream more than once, so the argument should never be an
-expression with side effects.
-
- @param[in] Stream The stream to be read.
-
- @return The getwc function returns the next wide character from the input stream pointed to by
-stream, or WEOF.
-**/
-wint_t getwc(FILE *Stream);
-
-/** Get a character from stdin.
-
- The getwchar function is equivalent to getwc with the argument stdin.
-
- @return The getwchar function returns the next wide character from the
- input stream pointed to by stdin, or WEOF.
-**/
-wint_t getwchar(void);
-
-/** Write a character to an output stream.
-
-The putwc function is equivalent to fputwc, except that if it is implemented as a
-macro, it may evaluate Stream more than once, so the Stream argument should never be an
-expression with side effects.
-
- @param[in] C The wide character to be written to Stream.
- @param[in] Stream The output stream that C is to be written to.
-
- @return The putwc function returns the wide character written, or WEOF.
-**/
-wint_t putwc(wchar_t C, FILE *Stream);
-
-/** Write a character to stdout.
-
-The putwchar function is equivalent to putwc with the second argument stdout.
-
- @param[in] C The wide character to be written to stdout.
-
- @return The putwchar function returns the character written, or WEOF.
-**/
-wint_t putwchar(wchar_t C);
-
-/** Return a character to the input Stream as if it had not been read.
-
-The ungetwc function pushes the wide character specified by C back onto the input
-stream pointed to by Stream. Pushed-back wide characters will be returned by
-subsequent reads on that stream in the reverse order of their pushing. A successful
-intervening call (with the stream pointed to by Stream) to a file positioning function
-(fseek, fsetpos, or rewind) discards any pushed-back wide characters for the
-stream. The external storage corresponding to the stream is unchanged.
-
-One wide character of pushback is guaranteed, even if the call to the ungetwc function
-follows just after a call to a formatted wide character input function fwscanf,
-vfwscanf, vwscanf, or wscanf. If the ungetwc function is called too many times
-on the same stream without an intervening read or file positioning operation on that
-stream, the operation may fail.
-
-If the value of C equals that of the macro WEOF, the operation fails and the input stream is
-unchanged.
-
-A successful call to the ungetwc function clears the end-of-file indicator for the stream.
-The value of the file position indicator for the stream after reading or discarding all
-pushed-back wide characters is the same as it was before the wide characters were pushed
-back. For a text or binary stream, the value of its file position indicator after a successful
-call to the ungetwc function is unspecified until all pushed-back wide characters are
-read or discarded.
-
- @param[in] C The wide character to push back onto the Stream.
- @param[in] Stream The output stream that C is to be pushed back onto.
-
- @return The ungetwc function returns the character pushed back,
- or WEOF if the operation fails.
-**/
-wint_t ungetwc(wint_t C, FILE *Stream);
-
-/* ################### Numeric Conversions ########################### */
-
-/** @{
-The wcstod, wcstof, and wcstold functions convert the initial portion of the wide
-string pointed to by nptr to double, float, and long double representation,
-respectively. First, they decompose the input string into three parts: an initial, possibly
-empty, sequence of white-space wide characters (as specified by the iswspace
-function), a subject sequence resembling a floating-point constant or representing an
-infinity or NaN; and a final wide string of one or more unrecognized wide characters,
-including the terminating null wide character of the input wide string. Then, they attempt
-to convert the subject sequence to a floating-point number, and return the result.
-
- @param[in] Nptr Pointer to the string to convert to a floating-point value.
- @param[in] EndPtr Optional pointer to an object in which to store a pointer
- to the final wide string.
-
-The functions return the converted value, if any. If no conversion could be performed,
-zero is returned. If the correct value is outside the range of representable values, plus or
-minus HUGE_VAL, HUGE_VALF, or HUGE_VALL is returned (according to the return
-type and sign of the value), and the value of the macro ERANGE is stored in errno. If
-the result underflows (7.12.1), the functions return a value whose magnitude is no greater
-than the smallest normalized positive number in the return type. A pointer to the
-final wide string is stored in the object pointed to by endptr, provided that endptr is
-not a null pointer.
-**/
-double wcstod (const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr);
-float wcstof (const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr);
-long double wcstold (const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr);
-/*@}*/
-
-/** @{
-The wcstol, wcstoll, wcstoul, and wcstoull functions convert the initial
-portion of the wide string pointed to by nptr to long int, long long int,
-unsigned long int, and unsigned long long int representation,
-respectively. First, they decompose the input string into three parts: an initial, possibly
-empty, sequence of white-space wide characters (as specified by the iswspace
-function), a subject sequence resembling an integer represented in some radix determined
-by the value of base, and a final wide string of one or more unrecognized wide
-characters, including the terminating null wide character of the input wide string. Then,
-they attempt to convert the subject sequence to an integer, and return the result.
-
- @param[in] Nptr Pointer to the string to convert.
- @param[in] EndPtr Optional pointer to an object in which to store a pointer
- to the final wide string.
- @param[in] Base Base, 0 to 36, of the value represented by the string
- pointed to by Nptr.
-
- @return The wcstol, wcstoll, wcstoul, and wcstoull functions return the converted
-value, if any. If no conversion could be performed, zero is returned. If the correct value
-is outside the range of representable values, LONG_MIN, LONG_MAX, LLONG_MIN,
-LLONG_MAX, ULONG_MAX, or ULLONG_MAX is returned (according to the return type
-sign of the value, if any), and the value of the macro ERANGE is stored in errno.
-**/
-long int wcstol ( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base);
-long long int wcstoll ( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base);
-unsigned long int wcstoul ( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base);
-unsigned long long int wcstoull( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base);
-/*@}*/
-
-/* ####################### String Copying ############################### */
-
-/** The wcscpy function copies the wide string pointed to by Src (including the
- terminating null wide character) into the array pointed to by Dest.
-
- @return The wcscpy function returns the value of Dest.
-**/
-wchar_t *wcscpy(wchar_t * __restrict Dest, const wchar_t * __restrict Src);
-
-/** The wcsncpy function copies not more than n wide characters (those that
- follow a null wide character are not copied) from the array pointed to by
- Src to the array pointed to by Dest.
-
- If the array pointed to by Src is a wide string that is shorter than n wide
- characters, null wide characters are appended to the copy in the array
- pointed to by Dest, until n wide characters in all have been written.
-
- @return The wcsncpy function returns the value of Dest.
-**/
-wchar_t *wcsncpy(wchar_t * __restrict Dest, const wchar_t * __restrict Src, size_t n);
-
-/** The wmemcpy function copies n wide characters from the object pointed to by
- Src to the object pointed to by Dest.
-
- Use this function if you know that Dest and Src DO NOT Overlap. Otherwise,
- use wmemmove.
-
- @return The wmemcpy function returns the value of Dest.
-**/
-wchar_t *wmemcpy(wchar_t * __restrict Dest, const wchar_t * __restrict Src, size_t n);
-
-/** The wmemmove function copies n wide characters from the object pointed to by
- Src to the object pointed to by Dest. The objects pointed to by Dest and Src are
- allowed to overlap.
-
- Because the UEFI BaseMemoryLib function CopyMem explicitly handles
- overlapping source and destination objects, this function and wmemcpy are
- implemented identically.
-
- For programming clarity, it is recommended that you use wmemcpy if you know
- that Dest and Src DO NOT Overlap. If Dest and Src might possibly overlap, then
- use wmemmove.
-
- @return The wmemmove function returns the value of Dest.
-**/
-wchar_t *wmemmove(wchar_t *Dest, const wchar_t *Src, size_t n);
-
-/* ################### String Concatenation ########################## */
-
-/** The wcscat function appends a copy of the wide string pointed to by Src
- (including the terminating null wide character) to the end of the wide
- string pointed to by Dest. The initial wide character of Src overwrites the
- null wide character at the end of Dest.
-
- @return The wcscat function returns the value of Dest.
-**/
-wchar_t *wcscat(wchar_t * __restrict Dest, const wchar_t * __restrict Src);
-
-/** The wcsncat function appends not more than n wide characters (a null wide
- character and those that follow it are not appended) from the array pointed
- to by Src to the end of the wide string pointed to by Dest. The initial wide
- character of Src overwrites the null wide character at the end of Dest.
- A terminating null wide character is always appended to the result.
-
- @return The wcsncat function returns the value of Dest.
-**/
-wchar_t *wcsncat(wchar_t * __restrict Dest, const wchar_t * __restrict Src, size_t n);
-
-/* ##################### String Comparison ############################# */
-
-/** The wcscmp function compares the wide string pointed to by s1 to the wide
- string pointed to by s2.
-
- @return The wcscmp function returns an integer greater than, equal to, or
- less than zero, accordingly as the wide string pointed to by s1
- is greater than, equal to, or less than the wide string
- pointed to by s2.
-**/
-int wcscmp(const wchar_t *s1, const wchar_t *s2);
-
-/** The wcscoll function compares the wide string pointed to by s1 to the wide
- string pointed to by s2, both interpreted as appropriate to the LC_COLLATE
- category of the current locale.
-
- @return The wcscoll function returns an integer greater than, equal to,
- or less than zero, accordingly as the wide string pointed to by
- s1 is greater than, equal to, or less than the wide string
- pointed to by s2 when both are interpreted as appropriate to
- the current locale.
-**/
-int wcscoll(const wchar_t *s1, const wchar_t *s2);
-
-/** The wcsncmp function compares not more than n wide characters (those that
- follow a null wide character are not compared) from the array pointed to by
- s1 to the array pointed to by s2.
-
- @return The wcsncmp function returns an integer greater than, equal to,
- or less than zero, accordingly as the possibly null-terminated
- array pointed to by s1 is greater than, equal to, or less than
- the possibly null-terminated array pointed to by s2.
-**/
-int wcsncmp(const wchar_t *s1, const wchar_t *s2, size_t n);
-
-/** The wcsxfrm function transforms the wide string pointed to by s2 and places
- the resulting wide string into the array pointed to by s1. The
- transformation is such that if the wcscmp function is applied to two
- transformed wide strings, it returns a value greater than, equal to, or
- less than zero, corresponding to the result of the wcscoll function applied
- to the same two original wide strings. No more than n wide characters are
- placed into the resulting array pointed to by s1, including the terminating
- null wide character. If n is zero, s1 is permitted to be a null pointer.
-
- @return The wcsxfrm function returns the length of the transformed wide
- string (not including the terminating null wide character). If
- the value returned is n or greater, the contents of the array
- pointed to by s1 are indeterminate.
-**/
-size_t wcsxfrm(wchar_t * __restrict s1, const wchar_t * __restrict s2, size_t n);
-
-/** The wmemcmp function compares the first n wide characters of the object
- pointed to by s1 to the first n wide characters of the object pointed to
- by s2.
-
- @return The wmemcmp function returns an integer greater than, equal to,
- or less than zero, accordingly as the object pointed to by s1 is
- greater than, equal to, or less than the object pointed to by s2.
-**/
-int wmemcmp(const wchar_t *s1, const wchar_t *s2, size_t n);
-
-/* ##################### String Searching ############################## */
-
-/** The wcschr function locates the first occurrence of C in the wide string
- pointed to by S. The terminating null wide character is considered to be
- part of the wide string.
-
- @return The wcschr function returns a pointer to the located wide
- character, or a null pointer if the wide character does not occur
- in the wide string.
-**/
-wchar_t *wcschr(const wchar_t *S, wchar_t C);
-
-/** The wcscspn function computes the length of the maximum initial segment of
- the wide string pointed to by s1 which consists entirely of wide characters
- not from the wide string pointed to by s2.
-
- @return The wcscspn function returns the length of the segment.
-**/
-size_t wcscspn(const wchar_t *s1, const wchar_t *s2);
-
-/** The wcspbrk function locates the first occurrence in the wide string
- pointed to by s1 of any wide character from the wide string
- pointed to by s2.
-
- @return The wcspbrk function returns a pointer to the wide character
- in s1, or a null pointer if no wide character from s2 occurs
- in s1.
-**/
-wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2);
-
-/** The wcsrchr function locates the last occurrence of C in the wide string
- pointed to by S. The terminating null wide character is considered to be
- part of the wide string.
-
- @return The wcsrchr function returns a pointer to the wide character,
- or a null pointer if C does not occur in the wide string.
-**/
-wchar_t *wcsrchr(const wchar_t *S, wchar_t C);
-
-/** The wcsspn function computes the length of the maximum initial segment of
- the wide string pointed to by s1 which consists entirely of wide characters
- from the wide string pointed to by s2.
-
- @return The wcsspn function returns the length of the segment.
-**/
-size_t wcsspn(const wchar_t *s1, const wchar_t *s2);
-
-/** The wcsstr function locates the first occurrence in the wide string pointed
- to by s1 of the sequence of wide characters (excluding the terminating null
- wide character) in the wide string pointed to by s2.
-
- @return The wcsstr function returns a pointer to the located wide string,
- or a null pointer if the wide string is not found. If s2 points
- to a wide string with zero length, the function returns s1.
-**/
-wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2);
-
-/** A sequence of calls to the wcstok function breaks the wide string pointed
- to by s1 into a sequence of tokens, each of which is delimited by a wide
- character from the wide string pointed to by s2. The third argument points
- to a caller-provided wchar_t pointer into which the wcstok function stores
- information necessary for it to continue scanning the same wide string.
-
- The first call in a sequence has a non-null first argument and stores an
- initial value in the object pointed to by ptr. Subsequent calls in the
- sequence have a null first argument and the object pointed to by ptr is
- required to have the value stored by the previous call in the sequence,
- which is then updated. The separator wide string pointed to by s2 may be
- different from call to call.
-
- The first call in the sequence searches the wide string pointed to by s1
- for the first wide character that is not contained in the current separator
- wide string pointed to by s2. If no such wide character is found, then
- there are no tokens in the wide string pointed to by s1 and the wcstok
- function returns a null pointer. If such a wide character is found, it is
- the start of the first token.
-
- The wcstok function then searches from there for a wide character that is
- contained in the current separator wide string. If no such wide character
- is found, the current token extends to the end of the wide string pointed
- to by s1, and subsequent searches in the same wide string for a token
- return a null pointer. If such a wide character is found, it is overwritten
- by a null wide character, which terminates the current token.
-
- In all cases, the wcstok function stores sufficient information in the
- pointer pointed to by ptr so that subsequent calls, with a null pointer for
- s1 and the unmodified pointer value for ptr, shall start searching just
- past the element overwritten by a null wide character (if any).
-
- @return The wcstok function returns a pointer to the first wide character
- of a token, or a null pointer if there is no token.
-**/
-wchar_t *wcstok(wchar_t * __restrict s1, const wchar_t * __restrict s2, wchar_t ** __restrict ptr);
-
-/** The wmemchr function locates the first occurrence of C in the initial n
- wide characters of the object pointed to by S.
-
- @return The wmemchr function returns a pointer to the located wide
- character, or a null pointer if the wide character does not occur
- in the object.
-**/
-wchar_t *wmemchr(const wchar_t *S, wchar_t C, size_t n);
-
-/* ################### String Manipulation ############################# */
-
-/** The wcslen function computes the length of the wide string pointed to by S.
-
- @return The wcslen function returns the number of wide characters that
- precede the terminating null wide character.
-**/
-size_t wcslen(const wchar_t *S);
-
-/** The wmemset function copies the value of C into each of the first n wide
- characters of the object pointed to by S.
-
- @return The wmemset function returns the value of S.
-**/
-wchar_t *wmemset(wchar_t *S, wchar_t C, size_t n);
-
-/* ################# Date and Time Conversion ########################### */
-
-/**
-The wcsftime function is equivalent to the strftime function, except that:
- - The argument s points to the initial element of an array of wide characters into which
-the generated output is to be placed.
- - The argument maxsize indicates the limiting number of wide characters.
- - The argument format is a wide string and the conversion specifiers are replaced by
-corresponding sequences of wide characters.
- - The return value indicates the number of wide characters.
-
-If the total number of resulting wide characters including the terminating null wide
-character is not more than maxsize, the wcsftime function returns the number of
-wide characters placed into the array pointed to by s not including the terminating null
-wide character. Otherwise, zero is returned and the contents of the array are
-indeterminate.
-**/
-size_t wcsftime(wchar_t * __restrict S, size_t maxsize, const wchar_t * __restrict format, const struct tm * __restrict timeptr);
-
-/* ############# Multibyte <--> Wide Character Conversion ############### */
-
-/** The btowc function determines whether C constitutes a valid single-byte
- character in the initial shift state.
-
- @return The btowc function returns WEOF if c has the value EOF or if
- (unsigned char)C does not constitute a valid single-byte
- character in the initial shift state. Otherwise, it returns the
- wide character representation of that character.
-**/
-wint_t btowc(int C);
-
-/** The wctob function determines whether C corresponds to a member of the extended
- character set whose multibyte character representation is a single byte when in the initial
- shift state.
-
- @return The wctob function returns EOF if C does not correspond to a multibyte
- character with length one in the initial shift state. Otherwise, it
- returns the single-byte representation of that character as an
- unsigned char converted to an int.
-**/
-int wctob(wint_t C);
-
-/** If ps is not a null pointer, the mbsinit function determines whether the
- pointed-to mbstate_t object describes an initial conversion state.
-
- @return The mbsinit function returns nonzero if ps is a null pointer
- or if the pointed-to object describes an initial conversion
- state; otherwise, it returns zero.
-**/
-int mbsinit(const mbstate_t *ps);
-
-/* ####### Restartable Multibyte <--> Wide Character Conversion ######### */
-
-/** The mbrlen function is equivalent to the call:<BR>
-@verbatim
- mbrtowc(NULL, s, n, ps != NULL ? ps : &internal)
-@endverbatim
- where internal is the mbstate_t object for the mbrlen function, except that
- the expression designated by ps is evaluated only once.
-
- @param[in] s Pointer to a multibyte character sequence.
- @param[in] n Maximum number of bytes to examine.
- @param[in] pS Pointer to the conversion state object.
-
- @retval 0 The next n or fewer characters complete a NUL.
- @retval 1..n The number of bytes that complete the multibyte character.
- @retval -2 The next n bytes contribute to an incomplete (but potentially valid) multibyte character.
- @retval -1 An encoding error occurred.
-**/
-size_t mbrlen(const char * __restrict S, size_t n, mbstate_t * __restrict pS);
-
-/** Restartable Multibyte to Wide character conversion.
-If S is a null pointer, the mbrtowc function is equivalent to the call:<BR>
-@verbatim
- mbrtowc(NULL, "", 1, ps)
-@endverbatim
-
-In this case, the values of the parameters pwc and n are ignored.
-
-If S is not a null pointer, the mbrtowc function inspects at most n bytes beginning with
-the byte pointed to by S to determine the number of bytes needed to complete the next
-multibyte character (including any shift sequences). If the function determines that the
-next multibyte character is complete and valid, it determines the value of the
-corresponding wide character and then, if pwc is not a null pointer, stores that value in
-the object pointed to by pwc. If the corresponding wide character is the null wide
-character, the resulting state described is the initial conversion state.
-
- @retval 0 if the next n or fewer bytes complete the multibyte
- character that corresponds to the null wide
- character (which is the value stored).
- @retval between_1_and_n_inclusive if the next n or fewer bytes complete
- a valid multibyte character (which is the value
- stored); the value returned is the number of bytes
- that complete the multibyte character.
- @retval (size_t)(-2) if the next n bytes contribute to an incomplete
- (but potentially valid) multibyte character, and
- all n bytes have been processed (no value is stored).
- @retval (size_t)(-1) if an encoding error occurs, in which case the next
- n or fewer bytes do not contribute to a complete and
- valid multibyte character (no value is stored); the
- value of the macro EILSEQ is stored in errno, and
- the conversion state is unspecified.
-**/
-size_t mbrtowc(wchar_t * __restrict pwc, const char * __restrict S, size_t n, mbstate_t * __restrict ps);
-
-/**
-If S is a null pointer, the wcrtomb function is equivalent to the call:<BR>
-@verbatim
- wcrtomb(buf, L'\0', ps)
-@endverbatim
-where buf is an internal buffer.
-
-If S is not a null pointer, the wcrtomb function determines the number of bytes needed
-to represent the multibyte character that corresponds to the wide character given by wc
-(including any shift sequences), and stores the multibyte character representation in the
-array whose first element is pointed to by S. At most MB_CUR_MAX bytes are stored. If
-wc is a null wide character, a null byte is stored, preceded by any shift sequence needed
-to restore the initial shift state; the resulting state described is the initial conversion state.
-
- @return The wcrtomb function returns the number of bytes stored in the
- array object (including any shift sequences). When wc is not a
- valid wide character, an encoding error occurs: the function
- stores the value of the macro EILSEQ in errno and
- returns (size_t)(-1); the conversion state is unspecified.
-**/
-size_t wcrtomb(char * __restrict S, wchar_t wc, mbstate_t * __restrict ps);
-
-/** Convert a sequence of multibyte characters into a sequence of wide characters.
- The mbsrtowcs function converts a sequence of multibyte characters that begins in the
- conversion state described by the object pointed to by ps, from the array indirectly
- pointed to by src into a sequence of corresponding wide characters. If dst is not a null
- pointer, the converted characters are stored into the array pointed to by dst. Conversion
- continues up to and including a terminating null character, which is also stored.
- Conversion stops earlier in two cases: when a sequence of bytes is encountered that does
- not form a valid multibyte character, or (if dst is not a null pointer) when len wide
- characters have been stored into the array pointed to by dst. Each conversion takes
- place as if by a call to the mbrtowc function.
-
- If dst is not a null pointer, the pointer object pointed to by src is assigned either a null
- pointer (if conversion stopped due to reaching a terminating null character) or the address
- just past the last multibyte character converted (if any). If conversion stopped due to
- reaching a terminating null character and if dst is not a null pointer, the resulting state
- described is the initial conversion state.
-
- @param[in] dst Destination for the Wide character sequence.
- @param[in] src Pointer to Pointer to MBCS char. sequence to convert.
- @param[in] len Length of dest, in WIDE characters.
- @param[in] ps Pointer to the conversion state object to be used for this conversion.
-
- @return If the input conversion encounters a sequence of bytes that do
- not form a valid multibyte character, an encoding error occurs:
- the mbsrtowcs function stores the value of the macro EILSEQ in
- errno and returns (size_t)(-1); the conversion state is
- unspecified. Otherwise, it returns the number of multibyte
- characters successfully converted, not including the terminating
- null character (if any).
-**/
-size_t mbsrtowcs(wchar_t * __restrict dst, const char ** __restrict src, size_t len, mbstate_t * __restrict ps);
-
-/** The wcsrtombs function converts a sequence of wide characters from the array
- indirectly pointed to by src into a sequence of corresponding multibyte
- characters that begins in the conversion state described by the object
- pointed to by ps. If dst is not a null pointer, the converted characters
- are then stored into the array pointed to by dst. Conversion continues
- up to and including a terminating null wide character, which is also
- stored. Conversion stops earlier in two cases: when a wide character is
- reached that does not correspond to a valid multibyte character, or
- (if dst is not a null pointer) when the next multibyte character would
- exceed the limit of len total bytes to be stored into the array pointed
- to by dst. Each conversion takes place as if by a call to the wcrtomb
- function.)
-
- If dst is not a null pointer, the pointer object pointed to by src is
- assigned either a null pointer (if conversion stopped due to reaching
- a terminating null wide character) or the address just past the last wide
- character converted (if any). If conversion stopped due to reaching a
- terminating null wide character, the resulting state described is the
- initial conversion state.
-
- @param[in] dst Destination for the MBCS sequence.
- @param[in] src Pointer to Pointer to wide char. sequence to convert.
- @param[in] len Length of dest, in bytes.
- @param[in] ps Pointer to the conversion state object to be used for this conversion.
-
- @return If conversion stops because a wide character is reached that
- does not correspond to a valid multibyte character, an
- encoding error occurs: the wcsrtombs function stores the
- value of the macro EILSEQ in errno and returns (size_t)(-1);
- the conversion state is unspecified. Otherwise, it returns
- the number of bytes in the resulting multibyte character
- sequence, not including the terminating null character (if any).
-**/
-size_t wcsrtombs(char * __restrict dst, const wchar_t ** __restrict src, size_t len, mbstate_t * __restrict ps);
-
-#endif /* _WCHAR_H */
|