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