Fix @return Doxygen commands to be singular instead of plural.

[mirror_edk2.git] / StdLib / Include / wchar.h

/** @file\r
    Extended multibyte and wide character utilities.\r
\r
    Within this implementation, multibyte characters are represented using the\r
    Unicode UTF-8 encoding and wide characters are represented using the\r
    16-bit UCS-2 encoding.\r
\r
    Unless explicitly stated otherwise, if the execution of a function declared\r
    in this file causes copying to take place between objects that overlap, the\r
    behavior is undefined.\r
\r
    Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>\r
    This program and the accompanying materials are licensed and made available under\r
    the terms and conditions of the BSD License that accompanies this distribution.\r
    The full text of the license may be found at\r
    http://opensource.org/licenses/bsd-license.php.\r
\r
    THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
    WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
**/\r
#ifndef _WCHAR_H\r
#define _WCHAR_H\r
#include  <sys/EfiCdefs.h>\r
#include  <machine/ansi.h>\r
#include  <machine/limits.h>\r
#include  <stdarg.h>\r
#include  <stdio.h>\r
\r
#if defined(_MSC_VER)\r
  #pragma warning ( disable : 4142 )\r
#endif\r
\r
#ifdef _EFI_SIZE_T_\r
  typedef _EFI_SIZE_T_  size_t;\r
  #undef _BSD_SIZE_T_\r
  #undef _EFI_SIZE_T_\r
#endif\r
\r
#ifndef __cplusplus\r
  #ifdef _EFI_WCHAR_T\r
    typedef _EFI_WCHAR_T wchar_t;\r
    #undef _BSD_WCHAR_T_\r
    #undef  _EFI_WCHAR_T\r
  #endif\r
#endif\r
\r
/*  mbstate_t is an opaque object, that must not be an array type, used to keep\r
    conversion state during multibyte stream conversions.\r
 */\r
#ifdef _BSD_MBSTATE_T_\r
  typedef _BSD_MBSTATE_T_ mbstate_t;\r
  #undef _BSD_MBSTATE_T_\r
#endif\r
\r
/*  wint_t is an integer type unchanged by default argument promotions that can\r
    hold any value corresponding to members of the extended character set, as\r
    well as at least one value that does not correspond to any member of the\r
    extended character set: WEOF.\r
*/\r
#ifdef _EFI_WINT_T\r
  typedef _EFI_WINT_T  wint_t;\r
  #undef _BSD_WINT_T_\r
  #undef _EFI_WINT_T\r
#endif\r
\r
/*  Since wchar_t is an unsigned 16-bit value, it has a minimum value of 0, and\r
    a maximum value defined by __USHRT_MAX (65535 on IA processors).\r
*/\r
#ifndef WCHAR_MIN\r
  #define WCHAR_MIN 0\r
  #define WCHAR_MAX __USHRT_MAX\r
#endif\r
\r
/* limits of wint_t */\r
#ifndef WINT_MIN\r
  #define WINT_MIN  _EFI_WINT_MIN       /* wint_t   */\r
  #define WINT_MAX  _EFI_WINT_MAX       /* wint_t   */\r
#endif\r
\r
/*  WEOF expands to a constant expression of type wint_t whose value does not\r
    correspond to any member of the extended character set. It is accepted\r
    (and returned) by several functions, declared in this file, to indicate\r
    end-of-file, that is, no more input from a stream. It is also used as a\r
    wide character value that does not correspond to any member of the\r
    extended character set.\r
*/\r
#ifndef WEOF\r
  #define WEOF  ((wint_t)-1)\r
#endif\r
\r
/*  tm is declared here as an incomplete structure type.  The full structure\r
    declaration is in <time.h>.\r
*/\r
struct  tm;\r
\r
/* ###############  Formatted Input/Output Functions  ##################### */\r
\r
/**\r
The fwprintf function writes output to the stream pointed to by stream, under\r
control of the wide string pointed to by format that specifies how subsequent arguments\r
are converted for output. If there are insufficient arguments for the format, the behavior\r
is undefined. If the format is exhausted while arguments remain, the excess arguments\r
are evaluated (as always) but are otherwise ignored. The fwprintf function returns\r
when the end of the format string is encountered.\r
\r
The fwprintf function returns the number of wide characters transmitted, or a negative\r
value if an output or encoding error occurred.\r
**/\r
int fwprintf(FILE * __restrict stream, const wchar_t * __restrict format, ...);\r
\r
/**\r
The fwscanf function reads input from the stream pointed to by stream, under\r
control of the wide string pointed to by format that specifies the admissible input\r
sequences and how they are to be converted for assignment, using subsequent arguments\r
as pointers to the objects to receive the converted input. If there are insufficient\r
arguments for the format, the behavior is undefined. If the format is exhausted while\r
arguments remain, the excess arguments are evaluated (as always) but are otherwise\r
ignored.\r
\r
The fwscanf function returns the value of the macro EOF if an input failure occurs\r
before any conversion. Otherwise, the function returns the number of input items\r
assigned, which can be fewer than provided for, or even zero, in the event of an early\r
matching failure.\r
**/\r
int fwscanf(FILE * __restrict stream, const wchar_t * __restrict format, ...);\r
\r
/**\r
The swprintf function is equivalent to fwprintf, except that the argument s\r
specifies an array of wide characters into which the generated output is to be written,\r
rather than written to a stream. No more than n wide characters are written, including a\r
terminating null wide character, which is always added (unless n is zero).\r
\r
The swprintf function returns the number of wide characters written in the array, not\r
counting the terminating null wide character, or a neg ative value if an encoding error\r
occurred or if n or more wide characters were requested to be written.\r
**/\r
int swprintf(wchar_t * __restrict s, size_t n, const wchar_t * __restrict format, ...);\r
\r
/**\r
**/\r
int swscanf(const wchar_t * __restrict s, const wchar_t * __restrict format, ...);\r
\r
/**\r
**/\r
int vfwprintf(FILE * __restrict stream, const wchar_t * __restrict format, va_list arg);\r
\r
/**\r
**/\r
int vfwscanf(FILE * __restrict stream, const wchar_t * __restrict format, va_list arg);\r
\r
/**\r
**/\r
int vswprintf(wchar_t * __restrict s, size_t n, const wchar_t * __restrict format, va_list arg);\r
\r
/**\r
**/\r
int vswscanf(const wchar_t * __restrict s, const wchar_t * __restrict format, va_list arg);\r
\r
/**\r
**/\r
int vwprintf(const wchar_t * __restrict format, va_list arg);\r
\r
/**\r
**/\r
int vwscanf(const wchar_t * __restrict format, va_list arg);\r
\r
/**\r
**/\r
int wprintf(const wchar_t * __restrict format, ...);\r
\r
/**\r
**/\r
int wscanf(const wchar_t * __restrict format, ...);\r
\r
/* ###################  Input/Output Functions  ########################### */\r
\r
\r
/**\r
**/\r
wint_t fgetwc(FILE *stream);\r
\r
/**\r
**/\r
wchar_t *fgetws(wchar_t * __restrict s, int n, FILE * __restrict stream);\r
\r
/**\r
**/\r
wint_t fputwc(wchar_t c, FILE *stream);\r
\r
/**\r
**/\r
int fputws(const wchar_t * __restrict s, FILE * __restrict stream);\r
\r
/**\r
**/\r
int fwide(FILE *stream, int mode);\r
\r
/**\r
**/\r
wint_t getwc(FILE *stream);\r
\r
/**\r
**/\r
wint_t getwchar(void);\r
\r
/**\r
**/\r
wint_t putwc(wchar_t c, FILE *stream);\r
\r
/**\r
**/\r
wint_t putwchar(wchar_t c);\r
\r
/**\r
**/\r
wint_t ungetwc(wint_t c, FILE *stream);\r
\r
/* ###################  Numeric Conversions     ########################### */\r
\r
/**\r
**/\r
double wcstod(const wchar_t * __restrict nptr, wchar_t ** __restrict endptr);\r
\r
/**\r
**/\r
float wcstof(const wchar_t * __restrict nptr, wchar_t ** __restrict endptr);\r
\r
/**\r
**/\r
long double wcstold(const wchar_t * __restrict nptr, wchar_t ** __restrict endptr);\r
\r
/**\r
**/\r
long int wcstol( const wchar_t * __restrict nptr, wchar_t ** __restrict endptr, int base);\r
\r
/**\r
**/\r
long long int wcstoll( const wchar_t * __restrict nptr, wchar_t ** __restrict endptr, int base);\r
\r
/**\r
**/\r
unsigned long int wcstoul( const wchar_t * __restrict nptr, wchar_t ** __restrict endptr, int base);\r
\r
/**\r
**/\r
unsigned long long int wcstoull( const wchar_t * __restrict nptr, wchar_t ** __restrict endptr, int base);\r
\r
/* #######################  String Copying  ############################### */\r
\r
/** The wcscpy function copies the wide string pointed to by s2 (including the\r
    terminating null wide character) into the array pointed to by s1.\r
\r
    @return   The wcscpy function returns the value of s1.\r
**/\r
wchar_t *wcscpy(wchar_t * __restrict s1, const wchar_t * __restrict s2);\r
\r
/** The wcsncpy function copies not more than n wide characters (those that\r
    follow a null wide character are not copied) from the array pointed to by\r
    s2 to the array pointed to by s1.\r
\r
    If the array pointed to by s2 is a wide string that is shorter than n wide\r
    characters, null wide characters are appended to the copy in the array\r
    pointed to by s1, until n wide characters in all have been written.\r
\r
    @return   The wcsncpy function returns the value of s1.\r
**/\r
wchar_t *wcsncpy(wchar_t * __restrict s1, const wchar_t * __restrict s2, size_t n);\r
\r
/** The wmemcpy function copies n wide characters from the object pointed to by\r
    s2 to the object pointed to by s1.\r
\r
    Use this function if you know that s1 and s2 DO NOT Overlap.  Otherwise,\r
    use wmemmove.\r
\r
    @return   The wmemcpy function returns the value of s1.\r
**/\r
wchar_t *wmemcpy(wchar_t * __restrict s1, const wchar_t * __restrict s2, size_t n);\r
\r
/** The wmemmove function copies n wide characters from the object pointed to by\r
    s2 to the object pointed to by s1. The objects pointed to by s1 and s2 are\r
    allowed to overlap.\r
\r
    Because the UEFI BaseMemoryLib function CopyMem explicitly handles\r
    overlapping source and destination objects, this function and wmemcpy are\r
    implemented identically.\r
\r
    For programming clarity, it is recommended that you use wmemcpy if you know\r
    that s1 and s2 DO NOT Overlap.  If s1 and s2 might possibly overlap, then\r
    use wmemmove.\r
\r
    @return   The wmemmove function returns the value of s1.\r
**/\r
wchar_t *wmemmove(wchar_t *s1, const wchar_t *s2, size_t n);\r
\r
/* ###################  String Concatenation     ########################## */\r
\r
/** The wcscat function appends a copy of the wide string pointed to by s2\r
    (including the terminating null wide character) to the end of the wide\r
    string pointed to by s1. The initial wide character of s2 overwrites the\r
    null wide character at the end of s1.\r
\r
    @return   The wcscat function returns the value of s1.\r
**/\r
wchar_t *wcscat(wchar_t * __restrict s1, const wchar_t * __restrict s2);\r
\r
/** The wcsncat function appends not more than n wide characters (a null wide\r
    character and those that follow it are not appended) from the array pointed\r
    to by s2 to the end of the wide string pointed to by s1. The initial wide\r
    character of s2 overwrites the null wide character at the end of s1.\r
    A terminating null wide character is always appended to the result.\r
\r
    @return   The wcsncat function returns the value of s1.\r
**/\r
wchar_t *wcsncat(wchar_t * __restrict s1, const wchar_t * __restrict s2, size_t n);\r
\r
/* #####################  String Comparison   ############################# */\r
\r
/** The wcscmp function compares the wide string pointed to by s1 to the wide\r
    string pointed to by s2.\r
\r
    @return   The wcscmp function returns an integer greater than, equal to, or\r
              less than zero, accordingly as the wide string pointed to by s1\r
              is greater than, equal to, or less than the wide string\r
              pointed to by s2.\r
**/\r
int wcscmp(const wchar_t *s1, const wchar_t *s2);\r
\r
/** The wcscoll function compares the wide string pointed to by s1 to the wide\r
    string pointed to by s2, both interpreted as appropriate to the LC_COLLATE\r
    category of the current locale.\r
\r
    @return   The wcscoll function returns an integer greater than, equal to,\r
              or less than zero, accordingly as the wide string pointed to by\r
              s1 is greater than, equal to, or less than the wide string\r
              pointed to by s2 when both are interpreted as appropriate to\r
              the current locale.\r
**/\r
int wcscoll(const wchar_t *s1, const wchar_t *s2);\r
\r
/** The wcsncmp function compares not more than n wide characters (those that\r
    follow a null wide character are not compared) from the array pointed to by\r
    s1 to the array pointed to by s2.\r
\r
    @return   The wcsncmp function returns an integer greater than, equal to,\r
              or less than zero, accordingly as the possibly null-terminated\r
              array pointed to by s1 is greater than, equal to, or less than\r
              the possibly null-terminated array pointed to by s2.\r
**/\r
int wcsncmp(const wchar_t *s1, const wchar_t *s2, size_t n);\r
\r
/** The wcsxfrm function transforms the wide string pointed to by s2 and places\r
    the resulting wide string into the array pointed to by s1. The\r
    transformation is such that if the wcscmp function is applied to two\r
    transformed wide strings, it returns a value greater than, equal to, or\r
    less than zero, corresponding to the result of the wcscoll function applied\r
    to the same two original wide strings. No more than n wide characters are\r
    placed into the resulting array pointed to by s1, including the terminating\r
    null wide character. If n is zero, s1 is permitted to be a null pointer.\r
\r
    @return   The wcsxfrm function returns the length of the transformed wide\r
              string (not including the terminating null wide character). If\r
              the value returned is n or greater, the contents of the array\r
              pointed to by s1 are indeterminate.\r
**/\r
size_t wcsxfrm(wchar_t * __restrict s1, const wchar_t * __restrict s2, size_t n);\r
\r
/** The wmemcmp function compares the first n wide characters of the object\r
    pointed to by s1 to the first n wide characters of the object pointed to\r
    by s2.\r
\r
    @return   The wmemcmp function returns an integer greater than, equal to,\r
              or less than zero, accordingly as the object pointed to by s1 is\r
              greater than, equal to, or less than the object pointed to by s2.\r
**/\r
int wmemcmp(const wchar_t *s1, const wchar_t *s2, size_t n);\r
\r
/* #####################  String Searching   ############################## */\r
\r
/** The wcschr function locates the first occurrence of c in the wide string\r
    pointed to by s.  The terminating null wide character is considered to be\r
    part of the wide string.\r
\r
    @return   The wcschr function returns a pointer to the located wide\r
              character, or a null pointer if the wide character does not occur\r
              in the wide string.\r
**/\r
wchar_t *wcschr(const wchar_t *s, wchar_t c);\r
\r
/** The wcscspn function computes the length of the maximum initial segment of\r
    the wide string pointed to by s1 which consists entirely of wide characters\r
    not from the wide string pointed to by s2.\r
\r
    @return   The wcscspn function returns the length of the segment.\r
**/\r
size_t wcscspn(const wchar_t *s1, const wchar_t *s2);\r
\r
/** The wcspbrk function locates the first occurrence in the wide string\r
    pointed to by s1 of any wide character from the wide string\r
    pointed to by s2.\r
\r
    @return   The wcspbrk function returns a pointer to the wide character\r
              in s1, or a null pointer if no wide character from s2 occurs\r
              in s1.\r
**/\r
wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2);\r
\r
/** The wcsrchr function locates the last occurrence of c in the wide string\r
    pointed to by s. The terminating null wide character is considered to be\r
    part of the wide string.\r
\r
    @return   The wcsrchr function returns a pointer to the wide character,\r
              or a null pointer if c does not occur in the wide string.\r
**/\r
wchar_t *wcsrchr(const wchar_t *s, wchar_t c);\r
\r
/** The wcsspn function computes the length of the maximum initial segment of\r
    the wide string pointed to by s1 which consists entirely of wide characters\r
    from the wide string pointed to by s2.\r
\r
    @return   The wcsspn function returns the length of the segment.\r
**/\r
size_t wcsspn(const wchar_t *s1, const wchar_t *s2);\r
\r
/** The wcsstr function locates the first occurrence in the wide string pointed\r
    to by s1 of the sequence of wide characters (excluding the terminating null\r
    wide character) in the wide string pointed to by s2.\r
\r
    @return   The wcsstr function returns a pointer to the located wide string,\r
              or a null pointer if the wide string is not found. If s2 points\r
              to a wide string with zero length, the function returns s1.\r
**/\r
wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2);\r
\r
/** A sequence of calls to the wcstok function breaks the wide string pointed\r
    to by s1 into a sequence of tokens, each of which is delimited by a wide\r
    character from the wide string pointed to by s2. The third argument points\r
    to a caller-provided wchar_t pointer into which the wcstok function stores\r
    information necessary for it to continue scanning the same wide string.\r
\r
    The first call in a sequence has a non-null first argument and stores an\r
    initial value in the object pointed to by ptr. Subsequent calls in the\r
    sequence have a null first argument and the object pointed to by ptr is\r
    required to have the value stored by the previous call in the sequence,\r
    which is then updated. The separator wide string pointed to by s2 may be\r
    different from call to call.\r
\r
    The first call in the sequence searches the wide string pointed to by s1\r
    for the first wide character that is not contained in the current separator\r
    wide string pointed to by s2. If no such wide character is found, then\r
    there are no tokens in the wide string pointed to by s1 and the wcstok\r
    function returns a null pointer. If such a wide character is found, it is\r
    the start of the first token.\r
\r
    The wcstok function then searches from there for a wide character that is\r
    contained in the current separator wide string. If no such wide character\r
    is found, the current token extends to the end of the wide string pointed\r
    to by s1, and subsequent searches in the same wide string for a token\r
    return a null pointer. If such a wide character is found, it is overwritten\r
    by a null wide character, which terminates the current token.\r
\r
    In all cases, the wcstok function stores sufficient information in the\r
    pointer pointed to by ptr so that subsequent calls, with a null pointer for\r
    s1 and the unmodified pointer value for ptr, shall start searching just\r
    past the element overwritten by a null wide character (if any).\r
\r
    @return   The wcstok function returns a pointer to the first wide character\r
              of a token, or a null pointer if there is no token.\r
**/\r
wchar_t *wcstok(wchar_t * __restrict s1, const wchar_t * __restrict s2, wchar_t ** __restrict ptr);\r
\r
/** The wmemchr function locates the first occurrence of c in the initial n\r
    wide characters of the object pointed to by s.\r
\r
    @return   The wmemchr function returns a pointer to the located wide\r
              character, or a null pointer if the wide character does not occur\r
              in the object.\r
**/\r
wchar_t *wmemchr(const wchar_t *s, wchar_t c, size_t n);\r
\r
/* ###################  String Manipulation   ############################# */\r
\r
/** The wcslen function computes the length of the wide string pointed to by s.\r
\r
    @return   The wcslen function returns the number of wide characters that\r
              precede the terminating null wide character.\r
**/\r
size_t wcslen(const wchar_t *s);\r
\r
/** The wmemset function copies the value of c into each of the first n wide\r
    characters of the object pointed to by s.\r
\r
    @return   The wmemset function returns the value of s.\r
**/\r
wchar_t *wmemset(wchar_t *s, wchar_t c, size_t n);\r
\r
/* #################  Date and Time Conversion  ########################### */\r
\r
/**\r
**/\r
size_t wcsftime(wchar_t * __restrict s, size_t maxsize, const wchar_t * __restrict format, const struct tm * __restrict timeptr);\r
\r
/* #############  Multibyte <--> Wide Character Conversion  ############### */\r
\r
/**\r
**/\r
wint_t btowc(int c);\r
\r
/** The wctob function determines whether c corresponds to a member of the extended\r
    character set whose multibyte character representation is a single byte when in the initial\r
    shift state.\r
\r
    @return     The wctob function returns EOF if c does not correspond to a multibyte\r
                character with length one in the initial shift state. Otherwise, it\r
                returns the single-byte representation of that character as an\r
                unsigned char converted to an int.\r
**/\r
int wctob(wint_t c);\r
\r
/** If ps is not a null pointer, the mbsinit function determines whether the\r
    pointed-to mbstate_t object describes an initial conversion state.\r
\r
    @return     The mbsinit function returns nonzero if ps is a null pointer\r
                or if the pointed-to object describes an initial conversion\r
                state; otherwise, it returns zero.\r
**/\r
int mbsinit(const mbstate_t *ps);\r
\r
/* #######  Restartable Multibyte <--> Wide Character Conversion  ######### */\r
\r
/**\r
**/\r
size_t mbrlen(const char * __restrict s, size_t n, mbstate_t * __restrict ps);\r
\r
/**\r
**/\r
size_t mbrtowc(wchar_t * __restrict pwc, const char * __restrict s, size_t n, mbstate_t * __restrict ps);\r
\r
/**\r
**/\r
size_t wcrtomb(char * __restrict s, wchar_t wc, mbstate_t * __restrict ps);\r
\r
/**\r
**/\r
size_t mbsrtowcs(wchar_t * __restrict dst, const char ** __restrict src, size_t len, mbstate_t * __restrict ps);\r
\r
/** The wcsrtombs function converts a sequence of wide characters from the array\r
    indirectly pointed to by src into a sequence of corresponding multibyte\r
    characters that begins in the conversion state described by the object\r
    pointed to by ps. If dst is not a null pointer, the converted characters\r
    are then stored into the array pointed to by dst.  Conversion continues\r
    up to and including a terminating null wide character, which is also\r
    stored. Conversion stops earlier in two cases: when a wide character is\r
    reached that does not correspond to a valid multibyte character, or\r
    (if dst is not a null pointer) when the next multibyte character would\r
    exceed the limit of len total bytes to be stored into the array pointed\r
    to by dst. Each conversion takes place as if by a call to the wcrtomb\r
    function.)\r
\r
    If dst is not a null pointer, the pointer object pointed to by src is\r
    assigned either a null pointer (if conversion stopped due to reaching\r
    a terminating null wide character) or the address just past the last wide\r
    character converted (if any). If conversion stopped due to reaching a\r
    terminating null wide character, the resulting state described is the\r
    initial conversion state.\r
\r
    @return     If conversion stops because a wide character is reached that\r
                does not correspond to a valid multibyte character, an\r
                encoding error occurs: the wcsrtombs function stores the\r
                value of the macro EILSEQ in errno and returns (size_t)(-1);\r
                the conversion state is unspecified. Otherwise, it returns\r
                the number of bytes in the resulting multibyte character\r
                sequence, not including the terminating null character (if any).\r
**/\r
size_t wcsrtombs(char * __restrict dst, const wchar_t ** __restrict src, size_t len, mbstate_t * __restrict ps);\r
\r
#endif  /* _WCHAR_H */\r