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