]>
git.proxmox.com Git - mirror_edk2.git/blob - StdLib/Include/wchar.h
2 Extended multibyte and wide character utilities.
4 Within this implementation, multibyte characters are represented using the
5 Unicode UTF-8 encoding and wide characters are represented using the
8 Unless explicitly stated otherwise, if the execution of a function declared
9 in this file causes copying to take place between objects that overlap, the
10 behavior is undefined.
12 Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>
13 This program and the accompanying materials are licensed and made available under
14 the terms and conditions of the BSD License that accompanies this distribution.
15 The full text of the license may be found at
16 http://opensource.org/licenses/bsd-license.php.
18 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
19 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
24 #include <sys/EfiCdefs.h>
25 #include <machine/ansi.h>
26 #include <machine/limits.h>
31 #pragma warning ( disable : 4142 )
35 typedef _EFI_SIZE_T_
size_t;
42 typedef _EFI_WCHAR_T
wchar_t;
48 /* mbstate_t is an opaque object, that must not be an array type, used to keep
49 conversion state during multibyte stream conversions.
51 #ifdef _BSD_MBSTATE_T_
52 typedef _BSD_MBSTATE_T_
mbstate_t;
53 #undef _BSD_MBSTATE_T_
56 /* wint_t is an integer type unchanged by default argument promotions that can
57 hold any value corresponding to members of the extended character set, as
58 well as at least one value that does not correspond to any member of the
59 extended character set: WEOF.
62 typedef _EFI_WINT_T
wint_t;
67 /* Since wchar_t is an unsigned 16-bit value, it has a minimum value of 0, and
68 a maximum value defined by __USHRT_MAX (65535 on IA processors).
72 #define WCHAR_MAX __USHRT_MAX
75 /* limits of wint_t */
77 #define WINT_MIN _EFI_WINT_MIN /* wint_t */
78 #define WINT_MAX _EFI_WINT_MAX /* wint_t */
81 /* WEOF expands to a constant expression of type wint_t whose value does not
82 correspond to any member of the extended character set. It is accepted
83 (and returned) by several functions, declared in this file, to indicate
84 end-of-file, that is, no more input from a stream. It is also used as a
85 wide character value that does not correspond to any member of the
86 extended character set.
89 #define WEOF ((wint_t)-1)
92 /* tm is declared here as an incomplete structure type. The full structure
93 declaration is in <time.h>.
97 /* ############### Formatted Input/Output Functions ##################### */
100 The fwprintf function writes output to the stream pointed to by stream, under
101 control of the wide string pointed to by format that specifies how subsequent arguments
102 are converted for output. If there are insufficient arguments for the format, the behavior
103 is undefined. If the format is exhausted while arguments remain, the excess arguments
104 are evaluated (as always) but are otherwise ignored. The fwprintf function returns
105 when the end of the format string is encountered.
107 The fwprintf function returns the number of wide characters transmitted, or a negative
108 value if an output or encoding error occurred.
110 int fwprintf(FILE * __restrict stream
, const wchar_t * __restrict format
, ...);
113 The fwscanf function reads input from the stream pointed to by stream, under
114 control of the wide string pointed to by format that specifies the admissible input
115 sequences and how they are to be converted for assignment, using subsequent arguments
116 as pointers to the objects to receive the converted input. If there are insufficient
117 arguments for the format, the behavior is undefined. If the format is exhausted while
118 arguments remain, the excess arguments are evaluated (as always) but are otherwise
121 The fwscanf function returns the value of the macro EOF if an input failure occurs
122 before any conversion. Otherwise, the function returns the number of input items
123 assigned, which can be fewer than provided for, or even zero, in the event of an early
126 int fwscanf(FILE * __restrict stream
, const wchar_t * __restrict format
, ...);
129 The swprintf function is equivalent to fwprintf, except that the argument s
130 specifies an array of wide characters into which the generated output is to be written,
131 rather than written to a stream. No more than n wide characters are written, including a
132 terminating null wide character, which is always added (unless n is zero).
134 The swprintf function returns the number of wide characters written in the array, not
135 counting the terminating null wide character, or a neg ative value if an encoding error
136 occurred or if n or more wide characters were requested to be written.
138 int swprintf(wchar_t * __restrict s
, size_t n
, const wchar_t * __restrict format
, ...);
142 int swscanf(const wchar_t * __restrict s
, const wchar_t * __restrict format
, ...);
146 int vfwprintf(FILE * __restrict stream
, const wchar_t * __restrict format
, va_list arg
);
150 int vfwscanf(FILE * __restrict stream
, const wchar_t * __restrict format
, va_list arg
);
154 int vswprintf(wchar_t * __restrict s
, size_t n
, const wchar_t * __restrict format
, va_list arg
);
158 int vswscanf(const wchar_t * __restrict s
, const wchar_t * __restrict format
, va_list arg
);
162 int vwprintf(const wchar_t * __restrict format
, va_list arg
);
166 int vwscanf(const wchar_t * __restrict format
, va_list arg
);
170 int wprintf(const wchar_t * __restrict format
, ...);
174 int wscanf(const wchar_t * __restrict format
, ...);
176 /* ################### Input/Output Functions ########################### */
181 wint_t fgetwc(FILE *stream
);
185 wchar_t *fgetws(wchar_t * __restrict s
, int n
, FILE * __restrict stream
);
189 wint_t fputwc(wchar_t c
, FILE *stream
);
193 int fputws(const wchar_t * __restrict s
, FILE * __restrict stream
);
197 int fwide(FILE *stream
, int mode
);
201 wint_t getwc(FILE *stream
);
205 wint_t getwchar(void);
209 wint_t putwc(wchar_t c
, FILE *stream
);
213 wint_t putwchar(wchar_t c
);
217 wint_t ungetwc(wint_t c
, FILE *stream
);
219 /* ################### Numeric Conversions ########################### */
223 double wcstod(const wchar_t * __restrict nptr
, wchar_t ** __restrict endptr
);
227 float wcstof(const wchar_t * __restrict nptr
, wchar_t ** __restrict endptr
);
231 long double wcstold(const wchar_t * __restrict nptr
, wchar_t ** __restrict endptr
);
235 long int wcstol( const wchar_t * __restrict nptr
, wchar_t ** __restrict endptr
, int base
);
239 long long int wcstoll( const wchar_t * __restrict nptr
, wchar_t ** __restrict endptr
, int base
);
243 unsigned long int wcstoul( const wchar_t * __restrict nptr
, wchar_t ** __restrict endptr
, int base
);
247 unsigned long long int wcstoull( const wchar_t * __restrict nptr
, wchar_t ** __restrict endptr
, int base
);
249 /* ####################### String Copying ############################### */
251 /** The wcscpy function copies the wide string pointed to by s2 (including the
252 terminating null wide character) into the array pointed to by s1.
254 @return The wcscpy function returns the value of s1.
256 wchar_t *wcscpy(wchar_t * __restrict s1
, const wchar_t * __restrict s2
);
258 /** The wcsncpy function copies not more than n wide characters (those that
259 follow a null wide character are not copied) from the array pointed to by
260 s2 to the array pointed to by s1.
262 If the array pointed to by s2 is a wide string that is shorter than n wide
263 characters, null wide characters are appended to the copy in the array
264 pointed to by s1, until n wide characters in all have been written.
266 @return The wcsncpy function returns the value of s1.
268 wchar_t *wcsncpy(wchar_t * __restrict s1
, const wchar_t * __restrict s2
, size_t n
);
270 /** The wmemcpy function copies n wide characters from the object pointed to by
271 s2 to the object pointed to by s1.
273 Use this function if you know that s1 and s2 DO NOT Overlap. Otherwise,
276 @return The wmemcpy function returns the value of s1.
278 wchar_t *wmemcpy(wchar_t * __restrict s1
, const wchar_t * __restrict s2
, size_t n
);
280 /** The wmemmove function copies n wide characters from the object pointed to by
281 s2 to the object pointed to by s1. The objects pointed to by s1 and s2 are
284 Because the UEFI BaseMemoryLib function CopyMem explicitly handles
285 overlapping source and destination objects, this function and wmemcpy are
286 implemented identically.
288 For programming clarity, it is recommended that you use wmemcpy if you know
289 that s1 and s2 DO NOT Overlap. If s1 and s2 might possibly overlap, then
292 @return The wmemmove function returns the value of s1.
294 wchar_t *wmemmove(wchar_t *s1
, const wchar_t *s2
, size_t n
);
296 /* ################### String Concatenation ########################## */
298 /** The wcscat function appends a copy of the wide string pointed to by s2
299 (including the terminating null wide character) to the end of the wide
300 string pointed to by s1. The initial wide character of s2 overwrites the
301 null wide character at the end of s1.
303 @return The wcscat function returns the value of s1.
305 wchar_t *wcscat(wchar_t * __restrict s1
, const wchar_t * __restrict s2
);
307 /** The wcsncat function appends not more than n wide characters (a null wide
308 character and those that follow it are not appended) from the array pointed
309 to by s2 to the end of the wide string pointed to by s1. The initial wide
310 character of s2 overwrites the null wide character at the end of s1.
311 A terminating null wide character is always appended to the result.
313 @return The wcsncat function returns the value of s1.
315 wchar_t *wcsncat(wchar_t * __restrict s1
, const wchar_t * __restrict s2
, size_t n
);
317 /* ##################### String Comparison ############################# */
319 /** The wcscmp function compares the wide string pointed to by s1 to the wide
320 string pointed to by s2.
322 @return The wcscmp function returns an integer greater than, equal to, or
323 less than zero, accordingly as the wide string pointed to by s1
324 is greater than, equal to, or less than the wide string
327 int wcscmp(const wchar_t *s1
, const wchar_t *s2
);
329 /** The wcscoll function compares the wide string pointed to by s1 to the wide
330 string pointed to by s2, both interpreted as appropriate to the LC_COLLATE
331 category of the current locale.
333 @return The wcscoll function returns an integer greater than, equal to,
334 or less than zero, accordingly as the wide string pointed to by
335 s1 is greater than, equal to, or less than the wide string
336 pointed to by s2 when both are interpreted as appropriate to
339 int wcscoll(const wchar_t *s1
, const wchar_t *s2
);
341 /** The wcsncmp function compares not more than n wide characters (those that
342 follow a null wide character are not compared) from the array pointed to by
343 s1 to the array pointed to by s2.
345 @return The wcsncmp function returns an integer greater than, equal to,
346 or less than zero, accordingly as the possibly null-terminated
347 array pointed to by s1 is greater than, equal to, or less than
348 the possibly null-terminated array pointed to by s2.
350 int wcsncmp(const wchar_t *s1
, const wchar_t *s2
, size_t n
);
352 /** The wcsxfrm function transforms the wide string pointed to by s2 and places
353 the resulting wide string into the array pointed to by s1. The
354 transformation is such that if the wcscmp function is applied to two
355 transformed wide strings, it returns a value greater than, equal to, or
356 less than zero, corresponding to the result of the wcscoll function applied
357 to the same two original wide strings. No more than n wide characters are
358 placed into the resulting array pointed to by s1, including the terminating
359 null wide character. If n is zero, s1 is permitted to be a null pointer.
361 @return The wcsxfrm function returns the length of the transformed wide
362 string (not including the terminating null wide character). If
363 the value returned is n or greater, the contents of the array
364 pointed to by s1 are indeterminate.
366 size_t wcsxfrm(wchar_t * __restrict s1
, const wchar_t * __restrict s2
, size_t n
);
368 /** The wmemcmp function compares the first n wide characters of the object
369 pointed to by s1 to the first n wide characters of the object pointed to
372 @return The wmemcmp function returns an integer greater than, equal to,
373 or less than zero, accordingly as the object pointed to by s1 is
374 greater than, equal to, or less than the object pointed to by s2.
376 int wmemcmp(const wchar_t *s1
, const wchar_t *s2
, size_t n
);
378 /* ##################### String Searching ############################## */
380 /** The wcschr function locates the first occurrence of c in the wide string
381 pointed to by s. The terminating null wide character is considered to be
382 part of the wide string.
384 @return The wcschr function returns a pointer to the located wide
385 character, or a null pointer if the wide character does not occur
388 wchar_t *wcschr(const wchar_t *s
, wchar_t c
);
390 /** The wcscspn function computes the length of the maximum initial segment of
391 the wide string pointed to by s1 which consists entirely of wide characters
392 not from the wide string pointed to by s2.
394 @return The wcscspn function returns the length of the segment.
396 size_t wcscspn(const wchar_t *s1
, const wchar_t *s2
);
398 /** The wcspbrk function locates the first occurrence in the wide string
399 pointed to by s1 of any wide character from the wide string
402 @return The wcspbrk function returns a pointer to the wide character
403 in s1, or a null pointer if no wide character from s2 occurs
406 wchar_t *wcspbrk(const wchar_t *s1
, const wchar_t *s2
);
408 /** The wcsrchr function locates the last occurrence of c in the wide string
409 pointed to by s. The terminating null wide character is considered to be
410 part of the wide string.
412 @return The wcsrchr function returns a pointer to the wide character,
413 or a null pointer if c does not occur in the wide string.
415 wchar_t *wcsrchr(const wchar_t *s
, wchar_t c
);
417 /** The wcsspn function computes the length of the maximum initial segment of
418 the wide string pointed to by s1 which consists entirely of wide characters
419 from the wide string pointed to by s2.
421 @return The wcsspn function returns the length of the segment.
423 size_t wcsspn(const wchar_t *s1
, const wchar_t *s2
);
425 /** The wcsstr function locates the first occurrence in the wide string pointed
426 to by s1 of the sequence of wide characters (excluding the terminating null
427 wide character) in the wide string pointed to by s2.
429 @return The wcsstr function returns a pointer to the located wide string,
430 or a null pointer if the wide string is not found. If s2 points
431 to a wide string with zero length, the function returns s1.
433 wchar_t *wcsstr(const wchar_t *s1
, const wchar_t *s2
);
435 /** A sequence of calls to the wcstok function breaks the wide string pointed
436 to by s1 into a sequence of tokens, each of which is delimited by a wide
437 character from the wide string pointed to by s2. The third argument points
438 to a caller-provided wchar_t pointer into which the wcstok function stores
439 information necessary for it to continue scanning the same wide string.
441 The first call in a sequence has a non-null first argument and stores an
442 initial value in the object pointed to by ptr. Subsequent calls in the
443 sequence have a null first argument and the object pointed to by ptr is
444 required to have the value stored by the previous call in the sequence,
445 which is then updated. The separator wide string pointed to by s2 may be
446 different from call to call.
448 The first call in the sequence searches the wide string pointed to by s1
449 for the first wide character that is not contained in the current separator
450 wide string pointed to by s2. If no such wide character is found, then
451 there are no tokens in the wide string pointed to by s1 and the wcstok
452 function returns a null pointer. If such a wide character is found, it is
453 the start of the first token.
455 The wcstok function then searches from there for a wide character that is
456 contained in the current separator wide string. If no such wide character
457 is found, the current token extends to the end of the wide string pointed
458 to by s1, and subsequent searches in the same wide string for a token
459 return a null pointer. If such a wide character is found, it is overwritten
460 by a null wide character, which terminates the current token.
462 In all cases, the wcstok function stores sufficient information in the
463 pointer pointed to by ptr so that subsequent calls, with a null pointer for
464 s1 and the unmodified pointer value for ptr, shall start searching just
465 past the element overwritten by a null wide character (if any).
467 @return The wcstok function returns a pointer to the first wide character
468 of a token, or a null pointer if there is no token.
470 wchar_t *wcstok(wchar_t * __restrict s1
, const wchar_t * __restrict s2
, wchar_t ** __restrict ptr
);
472 /** The wmemchr function locates the first occurrence of c in the initial n
473 wide characters of the object pointed to by s.
475 @return The wmemchr function returns a pointer to the located wide
476 character, or a null pointer if the wide character does not occur
479 wchar_t *wmemchr(const wchar_t *s
, wchar_t c
, size_t n
);
481 /* ################### String Manipulation ############################# */
483 /** The wcslen function computes the length of the wide string pointed to by s.
485 @return The wcslen function returns the number of wide characters that
486 precede the terminating null wide character.
488 size_t wcslen(const wchar_t *s
);
490 /** The wmemset function copies the value of c into each of the first n wide
491 characters of the object pointed to by s.
493 @return The wmemset function returns the value of s.
495 wchar_t *wmemset(wchar_t *s
, wchar_t c
, size_t n
);
497 /* ################# Date and Time Conversion ########################### */
501 size_t wcsftime(wchar_t * __restrict s
, size_t maxsize
, const wchar_t * __restrict format
, const struct tm
* __restrict timeptr
);
503 /* ############# Multibyte <--> Wide Character Conversion ############### */
509 /** The wctob function determines whether c corresponds to a member of the extended
510 character set whose multibyte character representation is a single byte when in the initial
513 @Returns The wctob function returns EOF if c does not correspond to a multibyte
514 character with length one in the initial shift state. Otherwise, it
515 returns the single-byte representation of that character as an
516 unsigned char converted to an int.
520 /** If ps is not a null pointer, the mbsinit function determines whether the
521 pointed-to mbstate_t object describes an initial conversion state.
523 @Returns The mbsinit function returns nonzero if ps is a null pointer
524 or if the pointed-to object describes an initial conversion
525 state; otherwise, it returns zero.
527 int mbsinit(const mbstate_t *ps
);
529 /* ####### Restartable Multibyte <--> Wide Character Conversion ######### */
533 size_t mbrlen(const char * __restrict s
, size_t n
, mbstate_t * __restrict ps
);
537 size_t mbrtowc(wchar_t * __restrict pwc
, const char * __restrict s
, size_t n
, mbstate_t * __restrict ps
);
541 size_t wcrtomb(char * __restrict s
, wchar_t wc
, mbstate_t * __restrict ps
);
545 size_t mbsrtowcs(wchar_t * __restrict dst
, const char ** __restrict src
, size_t len
, mbstate_t * __restrict ps
);
547 /** The wcsrtombs function converts a sequence of wide characters from the array
548 indirectly pointed to by src into a sequence of corresponding multibyte
549 characters that begins in the conversion state described by the object
550 pointed to by ps. If dst is not a null pointer, the converted characters
551 are then stored into the array pointed to by dst. Conversion continues
552 up to and including a terminating null wide character, which is also
553 stored. Conversion stops earlier in two cases: when a wide character is
554 reached that does not correspond to a valid multibyte character, or
555 (if dst is not a null pointer) when the next multibyte character would
556 exceed the limit of len total bytes to be stored into the array pointed
557 to by dst. Each conversion takes place as if by a call to the wcrtomb
560 If dst is not a null pointer, the pointer object pointed to by src is
561 assigned either a null pointer (if conversion stopped due to reaching
562 a terminating null wide character) or the address just past the last wide
563 character converted (if any). If conversion stopped due to reaching a
564 terminating null wide character, the resulting state described is the
565 initial conversion state.
567 @Returns If conversion stops because a wide character is reached that
568 does not correspond to a valid multibyte character, an
569 encoding error occurs: the wcsrtombs function stores the
570 value of the macro EILSEQ in errno and returns (size_t)(-1);
571 the conversion state is unspecified. Otherwise, it returns
572 the number of bytes in the resulting multibyte character
573 sequence, not including the terminating null character (if any).
575 size_t wcsrtombs(char * __restrict dst
, const wchar_t ** __restrict src
, size_t len
, mbstate_t * __restrict ps
);
577 #endif /* _WCHAR_H */