StdLib/Include/wchar.h

   1 /** @file
   2     Extended multibyte and wide character utilities.
   3
   4     Within this implementation, multibyte characters are represented using the
   5     Unicode UTF-8 encoding and wide characters are represented using the
   6     16-bit UCS-2 encoding.
   7
   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.
  11
  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.
  17
  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.
  20
  21 **/
  22 #ifndef _WCHAR_H
  23 #define _WCHAR_H
  24 #include  <sys/EfiCdefs.h>
  25 #include  <machine/ansi.h>
  26 #include  <machine/limits.h>
  27 #include  <stdarg.h>
  28 #include  <stdio.h>
  29
  30 #if defined(_MSC_VER)
  31   #pragma warning ( disable : 4142 )
  32 #endif
  33
  34 #ifdef _EFI_SIZE_T_
  35   typedef _EFI_SIZE_T_  size_t;
  36   #undef _BSD_SIZE_T_
  37   #undef _EFI_SIZE_T_
  38 #endif
  39
  40 #ifndef __cplusplus
  41   #ifdef _EFI_WCHAR_T
  42     typedef _EFI_WCHAR_T wchar_t;
  43     #undef _BSD_WCHAR_T_
  44     #undef  _EFI_WCHAR_T
  45   #endif
  46 #endif
  47
  48 /*  mbstate_t is an opaque object, that must not be an array type, used to keep
  49     conversion state during multibyte stream conversions.
  50  */
  51 #ifdef _BSD_MBSTATE_T_
  52   typedef _BSD_MBSTATE_T_ mbstate_t;
  53   #undef _BSD_MBSTATE_T_
  54 #endif
  55
  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.
  60 */
  61 #ifdef _EFI_WINT_T
  62   typedef _EFI_WINT_T  wint_t;
  63   #undef _BSD_WINT_T_
  64   #undef _EFI_WINT_T
  65 #endif
  66
  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).
  69 */
  70 #ifndef WCHAR_MIN
  71   #define WCHAR_MIN 0
  72   #define WCHAR_MAX __USHRT_MAX
  73 #endif
  74
  75 /* limits of wint_t */
  76 #ifndef WINT_MIN
  77   #define WINT_MIN  _EFI_WINT_MIN       /* wint_t   */
  78   #define WINT_MAX  _EFI_WINT_MAX       /* wint_t   */
  79 #endif
  80
  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.
  87 */
  88 #ifndef WEOF
  89   #define WEOF  ((wint_t)-1)
  90 #endif
  91
  92 /*  tm is declared here as an incomplete structure type.  The full structure
  93     declaration is in <time.h>.
  94 */
  95 struct  tm;
  96
  97 /* ###############  Formatted Input/Output Functions  ##################### */
  98
  99 /**
 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.
 106
 107 The fwprintf function returns the number of wide characters transmitted, or a negative
 108 value if an output or encoding error occurred.
 109 **/
 110 int fwprintf(FILE * __restrict stream, const wchar_t * __restrict format, ...);
 111
 112 /**
 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
 119 ignored.
 120
 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
 124 matching failure.
 125 **/
 126 int fwscanf(FILE * __restrict stream, const wchar_t * __restrict format, ...);
 127
 128 /**
 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).
 133
 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.
 137 **/
 138 int swprintf(wchar_t * __restrict s, size_t n, const wchar_t * __restrict format, ...);
 139
 140 /**
 141 **/
 142 int swscanf(const wchar_t * __restrict s, const wchar_t * __restrict format, ...);
 143
 144 /**
 145 **/
 146 int vfwprintf(FILE * __restrict stream, const wchar_t * __restrict format, va_list arg);
 147
 148 /**
 149 **/
 150 int vfwscanf(FILE * __restrict stream, const wchar_t * __restrict format, va_list arg);
 151
 152 /**
 153 **/
 154 int vswprintf(wchar_t * __restrict s, size_t n, const wchar_t * __restrict format, va_list arg);
 155
 156 /**
 157 **/
 158 int vswscanf(const wchar_t * __restrict s, const wchar_t * __restrict format, va_list arg);
 159
 160 /**
 161 **/
 162 int vwprintf(const wchar_t * __restrict format, va_list arg);
 163
 164 /**
 165 **/
 166 int vwscanf(const wchar_t * __restrict format, va_list arg);
 167
 168 /**
 169 **/
 170 int wprintf(const wchar_t * __restrict format, ...);
 171
 172 /**
 173 **/
 174 int wscanf(const wchar_t * __restrict format, ...);
 175
 176 /* ###################  Input/Output Functions  ########################### */
 177
 178
 179 /**
 180 **/
 181 wint_t fgetwc(FILE *stream);
 182
 183 /**
 184 **/
 185 wchar_t *fgetws(wchar_t * __restrict s, int n, FILE * __restrict stream);
 186
 187 /**
 188 **/
 189 wint_t fputwc(wchar_t c, FILE *stream);
 190
 191 /**
 192 **/
 193 int fputws(const wchar_t * __restrict s, FILE * __restrict stream);
 194
 195 /**
 196 **/
 197 int fwide(FILE *stream, int mode);
 198
 199 /**
 200 **/
 201 wint_t getwc(FILE *stream);
 202
 203 /**
 204 **/
 205 wint_t getwchar(void);
 206
 207 /**
 208 **/
 209 wint_t putwc(wchar_t c, FILE *stream);
 210
 211 /**
 212 **/
 213 wint_t putwchar(wchar_t c);
 214
 215 /**
 216 **/
 217 wint_t ungetwc(wint_t c, FILE *stream);
 218
 219 /* ###################  Numeric Conversions     ########################### */
 220
 221 /**
 222 **/
 223 double wcstod(const wchar_t * __restrict nptr, wchar_t ** __restrict endptr);
 224
 225 /**
 226 **/
 227 float wcstof(const wchar_t * __restrict nptr, wchar_t ** __restrict endptr);
 228
 229 /**
 230 **/
 231 long double wcstold(const wchar_t * __restrict nptr, wchar_t ** __restrict endptr);
 232
 233 /**
 234 **/
 235 long int wcstol( const wchar_t * __restrict nptr, wchar_t ** __restrict endptr, int base);
 236
 237 /**
 238 **/
 239 long long int wcstoll( const wchar_t * __restrict nptr, wchar_t ** __restrict endptr, int base);
 240
 241 /**
 242 **/
 243 unsigned long int wcstoul( const wchar_t * __restrict nptr, wchar_t ** __restrict endptr, int base);
 244
 245 /**
 246 **/
 247 unsigned long long int wcstoull( const wchar_t * __restrict nptr, wchar_t ** __restrict endptr, int base);
 248
 249 /* #######################  String Copying  ############################### */
 250
 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.
 253
 254     @return   The wcscpy function returns the value of s1.
 255 **/
 256 wchar_t *wcscpy(wchar_t * __restrict s1, const wchar_t * __restrict s2);
 257
 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.
 261
 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.
 265
 266     @return   The wcsncpy function returns the value of s1.
 267 **/
 268 wchar_t *wcsncpy(wchar_t * __restrict s1, const wchar_t * __restrict s2, size_t n);
 269
 270 /** The wmemcpy function copies n wide characters from the object pointed to by
 271     s2 to the object pointed to by s1.
 272
 273     Use this function if you know that s1 and s2 DO NOT Overlap.  Otherwise,
 274     use wmemmove.
 275
 276     @return   The wmemcpy function returns the value of s1.
 277 **/
 278 wchar_t *wmemcpy(wchar_t * __restrict s1, const wchar_t * __restrict s2, size_t n);
 279
 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
 282     allowed to overlap.
 283
 284     Because the UEFI BaseMemoryLib function CopyMem explicitly handles
 285     overlapping source and destination objects, this function and wmemcpy are
 286     implemented identically.
 287
 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
 290     use wmemmove.
 291
 292     @return   The wmemmove function returns the value of s1.
 293 **/
 294 wchar_t *wmemmove(wchar_t *s1, const wchar_t *s2, size_t n);
 295
 296 /* ###################  String Concatenation     ########################## */
 297
 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.
 302
 303     @return   The wcscat function returns the value of s1.
 304 **/
 305 wchar_t *wcscat(wchar_t * __restrict s1, const wchar_t * __restrict s2);
 306
 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.
 312
 313     @return   The wcsncat function returns the value of s1.
 314 **/
 315 wchar_t *wcsncat(wchar_t * __restrict s1, const wchar_t * __restrict s2, size_t n);
 316
 317 /* #####################  String Comparison   ############################# */
 318
 319 /** The wcscmp function compares the wide string pointed to by s1 to the wide
 320     string pointed to by s2.
 321
 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
 325               pointed to by s2.
 326 **/
 327 int wcscmp(const wchar_t *s1, const wchar_t *s2);
 328
 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.
 332
 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
 337               the current locale.
 338 **/
 339 int wcscoll(const wchar_t *s1, const wchar_t *s2);
 340
 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.
 344
 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.
 349 **/
 350 int wcsncmp(const wchar_t *s1, const wchar_t *s2, size_t n);
 351
 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.
 360
 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.
 365 **/
 366 size_t wcsxfrm(wchar_t * __restrict s1, const wchar_t * __restrict s2, size_t n);
 367
 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
 370     by s2.
 371
 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.
 375 **/
 376 int wmemcmp(const wchar_t *s1, const wchar_t *s2, size_t n);
 377
 378 /* #####################  String Searching   ############################## */
 379
 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.
 383
 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
 386               in the wide string.
 387 **/
 388 wchar_t *wcschr(const wchar_t *s, wchar_t c);
 389
 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.
 393
 394     @return   The wcscspn function returns the length of the segment.
 395 **/
 396 size_t wcscspn(const wchar_t *s1, const wchar_t *s2);
 397
 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
 400     pointed to by s2.
 401
 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
 404               in s1.
 405 **/
 406 wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2);
 407
 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.
 411
 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.
 414 **/
 415 wchar_t *wcsrchr(const wchar_t *s, wchar_t c);
 416
 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.
 420
 421     @return   The wcsspn function returns the length of the segment.
 422 **/
 423 size_t wcsspn(const wchar_t *s1, const wchar_t *s2);
 424
 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.
 428
 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.
 432 **/
 433 wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2);
 434
 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.
 440
 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.
 447
 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.
 454
 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.
 461
 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).
 466
 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.
 469 **/
 470 wchar_t *wcstok(wchar_t * __restrict s1, const wchar_t * __restrict s2, wchar_t ** __restrict ptr);
 471
 472 /** The wmemchr function locates the first occurrence of c in the initial n
 473     wide characters of the object pointed to by s.
 474
 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
 477               in the object.
 478 **/
 479 wchar_t *wmemchr(const wchar_t *s, wchar_t c, size_t n);
 480
 481 /* ###################  String Manipulation   ############################# */
 482
 483 /** The wcslen function computes the length of the wide string pointed to by s.
 484
 485     @return   The wcslen function returns the number of wide characters that
 486               precede the terminating null wide character.
 487 **/
 488 size_t wcslen(const wchar_t *s);
 489
 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.
 492
 493     @return   The wmemset function returns the value of s.
 494 **/
 495 wchar_t *wmemset(wchar_t *s, wchar_t c, size_t n);
 496
 497 /* #################  Date and Time Conversion  ########################### */
 498
 499 /**
 500 **/
 501 size_t wcsftime(wchar_t * __restrict s, size_t maxsize, const wchar_t * __restrict format, const struct tm * __restrict timeptr);
 502
 503 /* #############  Multibyte <--> Wide Character Conversion  ############### */
 504
 505 /**
 506 **/
 507 wint_t btowc(int c);
 508
 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
 511     shift state.
 512
 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.
 517 **/
 518 int wctob(wint_t c);
 519
 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.
 522
 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.
 526 **/
 527 int mbsinit(const mbstate_t *ps);
 528
 529 /* #######  Restartable Multibyte <--> Wide Character Conversion  ######### */
 530
 531 /**
 532 **/
 533 size_t mbrlen(const char * __restrict s, size_t n, mbstate_t * __restrict ps);
 534
 535 /**
 536 **/
 537 size_t mbrtowc(wchar_t * __restrict pwc, const char * __restrict s, size_t n, mbstate_t * __restrict ps);
 538
 539 /**
 540 **/
 541 size_t wcrtomb(char * __restrict s, wchar_t wc, mbstate_t * __restrict ps);
 542
 543 /**
 544 **/
 545 size_t mbsrtowcs(wchar_t * __restrict dst, const char ** __restrict src, size_t len, mbstate_t * __restrict ps);
 546
 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
 558     function.)
 559
 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.
 566
 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).
 574 **/
 575 size_t wcsrtombs(char * __restrict dst, const wchar_t ** __restrict src, size_t len, mbstate_t * __restrict ps);
 576
 577 #endif  /* _WCHAR_H */