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