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