/** @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.
The following macros are defined in this file:
@verbatim
NULL Actually defined in
WCHAR_MIN Minimum value of a wide char.
WCHAR_MAX Maximum value of a wide char.
WEOF Wide char version of end-of-file.
@endverbatim
The following types are defined in this file:
@verbatim
size_t Unsigned integer type of the result of the sizeof operator.
wchar_t Type of wide characters.
wint_t Type capable of holding all wchar_t values and WEOF.
mbstate_t Type of object holding multibyte conversion state.
struct tm Incomplete declaration of the broken-down time structure.
@endverbatim
The following functions are declared in this file:
@verbatim
############### Formatted Input/Output Functions
int fwprintf (FILE * __restrict stream,
const wchar_t * __restrict format, ...);
int fwscanf (FILE * __restrict stream,
const wchar_t * __restrict format, ...);
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
wchar_t *wcscpy (wchar_t * __restrict s1,
const wchar_t * __restrict s2);
wchar_t *wcsncpy (wchar_t * __restrict s1,
const wchar_t * __restrict s2, size_t n);
wchar_t *wmemcpy (wchar_t * __restrict s1,
const wchar_t * __restrict s2, size_t n);
wchar_t *wmemmove (wchar_t *s1, const wchar_t *s2, size_t n);
################### String Concatenation
wchar_t *wcscat (wchar_t * __restrict s1,
const wchar_t * __restrict s2);
wchar_t *wcsncat (wchar_t * __restrict s1,
const wchar_t * __restrict s2, size_t n);
##################### String Comparison
int wcscmp (const wchar_t *s1, const wchar_t *s2);
int wcscoll (const wchar_t *s1, const wchar_t *s2);
int wcsncmp (const wchar_t *s1, const wchar_t *s2, size_t n);
size_t wcsxfrm (wchar_t * __restrict s1,
const wchar_t * __restrict s2, size_t n);
int wmemcmp (const wchar_t *s1, const wchar_t *s2, size_t n);
##################### String Searching
wchar_t *wcschr (const wchar_t *S, wchar_t c);
size_t wcscspn (const wchar_t *s1, const wchar_t *s2);
wchar_t *wcspbrk (const wchar_t *s1, const wchar_t *s2);
wchar_t *wcsrchr (const wchar_t *S, wchar_t c);
size_t wcsspn (const wchar_t *s1, const wchar_t *s2);
wchar_t *wcsstr (const wchar_t *s1, const wchar_t *s2);
wchar_t *wcstok (wchar_t * __restrict s1,
const wchar_t * __restrict s2,
wchar_t ** __restrict ptr);
wchar_t *wmemchr (const wchar_t *S, wchar_t c, size_t n);
################### String Manipulation
size_t wcslen (const wchar_t *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);
@endverbatim
@note Properly constructed programs will take the following into consideration:
- wchar_t and wint_t may be the same integer type.
- WEOF might be a different value than that of EOF.
- WEOF might not be negative.
- mbstate_t objects are not intended to be inspected by programs.
Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.
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.
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
#include
#include
#include
#include
#if defined(_MSC_VER)
#pragma warning ( disable : 4142 )
#endif
#ifdef _EFI_SIZE_T_
typedef _EFI_SIZE_T_ size_t; /**< Unsigned integer type of the result of the sizeof operator. */
#undef _BSD_SIZE_T_
#undef _EFI_SIZE_T_
#endif
#ifndef __cplusplus
#ifdef _EFI_WCHAR_T
/** An integer type capable of representing all distinct codes in the
UCS-2 encoding supported by UEFI.
**/
typedef _EFI_WCHAR_T wchar_t;
#undef _BSD_WCHAR_T_
#undef _EFI_WCHAR_T
#endif
#endif
#ifdef _BSD_MBSTATE_T_
/** mbstate_t is an opaque object, that is not an array type, used to keep
conversion state during multibyte stream conversions.
*/
typedef _BSD_MBSTATE_T_ mbstate_t;
#undef _BSD_MBSTATE_T_
#endif
#ifdef _EFI_WINT_T
/** 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.
*/
typedef _EFI_WINT_T wint_t;
#undef _BSD_WINT_T_
#undef _EFI_WINT_T
#endif
#ifndef WCHAR_MIN
/** @{
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).
*/
#define WCHAR_MIN 0
#define WCHAR_MAX __USHRT_MAX
/*@}*/
#endif
#ifndef WEOF
/** 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.
*/
#define WEOF ((wint_t)-1)
#endif
/* limits of wint_t -- These are NOT specified by ISO/IEC 9899 */
#ifndef WINT_MIN
#define WINT_MIN _EFI_WINT_MIN /* wint_t */
#define WINT_MAX _EFI_WINT_MAX /* wint_t */
#endif
/** Type struct tm is declared here as an incomplete structure type for use as an argument
type by the wcsftime function. The full structure declaration is in .
*/
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 format is composed of zero or more directives: ordinary wide characters
(not %), which are copied unchanged to the output stream; and conversion
specifications, each of which results in fetching zero or more subsequent
arguments, converting them, if applicable, according to the corresponding
conversion specifier, and then writing the result to the output stream.
Each conversion specification is introduced by the wide character %. After
the %, the following appear in sequence:
— Zero or more flags (in any order) that modify the meaning of the
conversion specification.
— An optional minimum field width. If the converted value has fewer wide
characters than the field width, it is padded with spaces (by default)
on the left (or right, if the left adjustment flag, described later,
has been given) to the field width. The field width takes the form of
an asterisk * (described later) or a nonnegative decimal integer.
— An optional precision that gives the minimum number of digits to appear
for the d, i, o, u, x, and X conversions, the number of digits to
appear after the decimal-point wide character for e, E, f, and F
conversions, the maximum number of significant digits for the g and G
conversions, or the maximum number of wide characters to be written
for s conversions. The precision takes the form of a period (.)
followed either by an asterisk * (described later) or by an optional
decimal integer; if only the period is specified, the precision is
taken as zero. If a precision appears with any other conversion
specifier, the behavior is undefined.
— An optional length modifier that specifies the size of the argument.
— A conversion specifier wide character that specifies the type of
conversion to be applied.
As noted above, a field width, or precision, or both, may be indicated by
an asterisk. In this case, an int argument supplies the field width or
precision. The arguments specifying field width, or precision, or both,
must appear (in that order) before the argument (if any) to be converted.
A negative field width argument is taken as a - flag followed by a positive
field width. A negative precision argument is taken as if the precision
were omitted.
The flag wide characters and their meanings are:
- The result of the conversion is left-justified within the field.
(It is right-justified if this flag is not specified.)
+ The result of a signed conversion always begins with a plus or minus
sign. (It begins with a sign only when a negative value is converted
if this flag is not specified.)
space If the first wide character of a signed conversion is not a sign, or
if a signed conversion results in no wide characters, a space is
prefixed to the result. If the space and + flags both appear, the
space flag is ignored.
# The result is converted to an ‘‘alternative form’’. For o conversion,
it increases the precision, if and only if necessary, to force the
first digit of the result to be a zero (if the value and precision
are both 0, a single 0 is printed). For x (or X) conversion, a
nonzero result has 0x (or 0X) prefixed to it. For e, E, f, F, g,
and G conversions, the result of converting a floating-point number
always contains a decimal-point wide character, even if no digits
follow it. (Normally, a decimal-point wide character appears in the
result of these conversions only if a digit follows it.) For g and G
conversions, trailing zeros are not removed from the result. For
other conversions, the behavior is undefined.
0 For d, i, o, u, x, X, e, E, f, F, g, and G conversions, leading zeros
(following any indication of sign or base) are used to pad to the
field width rather than performing space padding, except when
converting an infinity or NaN. If the 0 and - flags both appear,
the 0 flag is ignored. For d, i, o, u, x, and X conversions, if a
precision is specified, the 0 flag is ignored. For other conversions,
the behavior is undefined.
The length modifiers and their meanings are:
hh Specifies that a following d, i, o, u, x, or X conversion specifier
applies to a signed char or unsigned char argument (the argument
will have been promoted according to the integer promotions, but its
value shall be converted to signed char or unsigned char before
printing); or that a following n conversion specifier applies to a
pointer to a signed char argument.
h Specifies that a following d, i, o, u, x, or X conversion specifier
applies to a short int or unsigned short int argument (the argument
will have been promoted according to the integer promotions, but its
value shall be converted to short int or unsigned short int before
printing); or that a following n conversion specifier applies to a
pointer to a short int argument.
l (ell) Specifies that a following d, i, o, u, x, or X conversion
specifier applies to a long int or unsigned long int argument;
that a following n conversion specifier applies to a pointer to a
long int argument; that a following c conversion specifier
applies to a wint_t argument; that a following s conversion
specifier applies to a pointer to a wchar_t argument; or has no
effect on a following e, E, f, F, g, or G conversion specifier.
ll (ell-ell) Specifies that a following d, i, o, u, x, or X conversion
specifier applies to a long long int or unsigned long long int
argument; or that a following n conversion specifier applies
to a pointer to a long long int argument.
j Specifies that a following d, i, o, u, x, or X conversion specifier
applies to an intmax_t or uintmax_t argument; or that a following
n conversion specifier applies to a pointer to an intmax_t argument.
z Specifies that a following d, i, o, u, x, or X conversion specifier
applies to a size_t or the corresponding signed integer type
argument; or that a following n conversion specifier applies to a
pointer to a signed integer type corresponding to size_t argument.
t Specifies that a following d, i, o, u, x, or X conversion specifier
applies to a ptrdiff_t or the corresponding unsigned integer type
argument; or that a following n conversion specifier applies to a
pointer to a ptrdiff_t argument.
L Specifies that a following a, A, e, E, f, F, g, or G conversion
specifier applies to a long double argument.
If a length modifier appears with any conversion specifier other than as
specified above, the behavior is undefined.
The conversion specifiers and their meanings are:
d,i The int argument is converted to signed decimal in the
style [-]dddd. The precision specifies the minimum number of digits
to appear; if the value being converted can be represented in fewer
digits, it is expanded with leading zeros. The default precision
is 1. The result of converting a zero value with a precision of
zero is no wide characters.
o,u,x,X The unsigned int argument is converted to unsigned octal (o),
unsigned decimal (u), or unsigned hexadecimal notation (x or X) in
the style dddd; the letters abcdef are used for x conversion and
the letters ABCDEF for X conversion. The precision specifies the
minimum number of digits to appear; if the value being converted
can be represented in fewer digits, it is expanded with leading
zeros. The default precision is 1. The result of converting a zero
value with a precision of zero is no wide characters.
f,F A double argument representing a floating-point number is converted
to decimal notation in the style [-]ddd.ddd, where the number of
digits after the decimal-point wide character is equal to the
precision specification. If the precision is missing, it is taken
as 6; if the precision is zero and the # flag is not specified, no
decimal-point wide character appears. If a decimal-point wide
character appears, at least one digit appears before it. The value
is rounded to the appropriate number of digits.
A double argument representing an infinity is converted to [-]inf.
A double argument representing a NaN is converted to [-]nan.
The F conversion specifier produces INF or NAN instead
of inf or nan, respectively.
e,E A double argument representing a floating-point number is converted
in the style [-]d.ddd e±dd, where there is one digit (which is
nonzero if the argument is nonzero) before the decimal-point wide
character and the number of digits after it is equal to the
precision; if the precision is missing, it is taken as 6; if the
precision is zero and the # flag is not specified, no decimal-point
wide character appears. The value is rounded to the appropriate
number of digits. The E conversion specifier produces a number with
E instead of e introducing the exponent. The exponent always
contains at least two digits, and only as many more digits as
necessary to represent the exponent. If the value is zero, the
exponent is zero. A double argument representing an infinity or NaN
is converted in the style of an f or F conversion specifier.
g,G A double argument representing a floating-point number is converted
in style f or e (or in style F or E in the case of a G conversion
specifier), depending on the value converted and the precision.
Let P equal the precision if nonzero, 6 if the precision is
omitted, or 1 if the precision is zero. Then, if a conversion with
style E would have an exponent of X:
- if P > X = -4, the conversion is with style f (or F) and
precision P - (X + 1).
- otherwise, the conversion is with style e (or E) and
precision P - 1.
Finally, unless the # flag is used, any trailing zeros are removed
from the fractional portion of the result and the decimal-point
wide character is removed if there is no fractional portion
remaining. A double argument representing an infinity or NaN is
converted in the style of an f or F conversion specifier.
c If no l length modifier is present, the int argument is converted
to a wide character as if by calling btowc and the resulting wide
character is written. If an l length modifier is present, the
wint_t argument is converted to wchar_t and written.
s If no l length modifier is present, the argument shall be a pointer
to the initial element of a character array containing a multibyte
character sequence beginning in the initial shift state. Characters
from the array are converted as if by repeated calls to the mbrtowc
function, with the conversion state described by an mbstate_t
object initialized to zero before the first multibyte character is
converted, and written up to (but not including) the terminating
null wide character. If the precision is specified, no more than
that many wide characters are written. If the precision is not
specified or is greater than the size of the converted array, the
converted array shall contain a null wide character.
If an l length modifier is present, the argument shall be a pointer
to the initial element of an array of wchar_t type. Wide characters
from the array are written up to (but not including) a terminating
null wide character. If the precision is specified, no more than
that many wide characters are written. If the precision is not
specified or is greater than the size of the array, the array
shall contain a null wide character.
p The argument shall be a pointer to void. The value of the pointer
is converted to a sequence of printing wide characters, in an
implementation-defined manner.
n The argument shall be a pointer to signed integer into which is
written the number of wide characters written to the output stream
so far by this call to fwprintf. No argument is converted, but one
is consumed. If the conversion specification includes any flags, a
field width, or a precision, the behavior is undefined.
% A % wide character is written. No argument is converted. The
complete conversion specification is %%.
@param[in] stream An open File specifier to which the output is sent.
@param[in] format A wide character sequence containing characters
to be copied unchanged, and conversion specifiers
which convert their associated arguments.
@param ... Variable number of parameters as required by format.
@return 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 format is composed of zero or more directives: one or more white-space
wide characters, an ordinary wide character (neither % nor a white-space
wide character), or a conversion specification. Each conversion
specification is introduced by the wide character %. After the %, the
following appear in sequence:
- An optional assignment-suppressing wide character *.
- An optional decimal integer greater than zero that specifies the
maximum field width (in wide characters).
- An optional length modifier that specifies the size of the receiving object.
- A conversion specifier wide character that specifies the type of
conversion to be applied.
The fwscanf function executes each directive of the format in turn. If a
directive fails, as detailed below, the function returns. Failures are
described as input failures (due to the occurrence of an encoding error
or the unavailability of input characters), or matching failures
(due to inappropriate input).
A directive composed of white-space wide character(s) is executed by
reading input up to the first non-white-space wide character (which remains
unread), or until no more wide characters can be read.
A directive that is an ordinary wide character is executed by reading the
next wide character of the stream. If that wide character differs from the
directive, the directive fails and the differing and subsequent wide
characters remain unread. Similarly, if end-of-file, an encoding error, or
a read error prevents a wide character from being read, the directive fails.
A directive that is a conversion specification defines a set of matching
input sequences, as described below for each specifier. A conversion
specification is executed in the following steps:
- Input white-space wide characters (as specified by the iswspace
function) are skipped, unless the specification includes
a [, c, or n specifier.
- An input item is read from the stream, unless the specification
includes an n specifier. An input item is defined as the longest
sequence of input wide characters which does not exceed any specified
field width and which is, or is a prefix of, a matching input sequence.
The first wide character, if any, after the input item remains unread.
If the length of the input item is zero, the execution of the directive
fails; this condition is a matching failure unless end-of-file, an
encoding error, or a read error prevented input from the stream, in
which case it is an input failure.
- Except in the case of a % specifier, the input item (or, in the case of
a %n directive, the count of input wide characters) is converted to a
type appropriate to the conversion specifier. If the input item is not
a matching sequence, the execution of the directive fails: this
condition is a matching failure. Unless assignment suppression was
indicated by a *, the result of the conversion is placed in the object
pointed to by the first argument following the format argument that has
not already received a conversion result. If this object does not have
an appropriate type, or if the result of the conversion cannot be
represented in the object, the behavior is undefined.
The length modifiers and their meanings are:
hh Specifies that a following d, i, o, u, x, X, or n conversion
specifier applies to an argument with type pointer to signed char
or unsigned char.
h Specifies that a following d, i, o, u, x, X, or n conversion
specifier applies to an argument with type pointer to short int
or unsigned short int.
l (ell) Specifies that a following d, i, o, u, x, X, or n conversion
specifier applies to an argument with type pointer to long int or
unsigned long int; that a following e, E, f, F, g, or G conversion
specifier applies to an argument with type pointer to double; or
that a following c, s, or [ conversion specifier applies to an
argument with type pointer to wchar_t.
ll (ell-ell) Specifies that a following d, i, o, u, x, X, or n conversion
specifier applies to an argument with type
pointer to long long int or unsigned long long int.
j Specifies that a following d, i, o, u, x, X, or n conversion
specifier applies to an argument with type pointer to intmax_t
or uintmax_t.
z Specifies that a following d, i, o, u, x, X, or n conversion
specifier applies to an argument with type pointer to size_t or the
corresponding signed integer type.
t Specifies that a following d, i, o, u, x, X, or n conversion
specifier applies to an argument with type pointer to ptrdiff_t or
the corresponding unsigned integer type.
L Specifies that a following e, E, f, F, g, or G conversion specifier
applies to an argument with type pointer to long double.
If a length modifier appears with any conversion specifier other than as
specified above, the behavior is undefined.
The conversion specifiers and their meanings are:
d Matches an optionally signed decimal integer, whose format is the
same as expected for the subject sequence of the wcstol function
with the value 10 for the base argument. The corresponding argument
shall be a pointer to signed integer.
i Matches an optionally signed integer, whose format is the same as
expected for the subject sequence of the wcstol function with the
value 0 for the base argument. The corresponding argument shall be
a pointer to signed integer.
o Matches an optionally signed octal integer, whose format is the
same as expected for the subject sequence of the wcstoul function
with the value 8 for the base argument. The corresponding argument
shall be a pointer to unsigned integer.
u Matches an optionally signed decimal integer, whose format is the
same as expected for the subject sequence of the wcstoul function
with the value 10 for the base argument. The corresponding argument
shall be a pointer to unsigned integer.
x Matches an optionally signed hexadecimal integer, whose format is
the same as expected for the subject sequence of the wcstoul
function with the value 16 for the base argument. The corresponding
argument shall be a pointer to unsigned integer.
e,f,g Matches an optionally signed floating-point number, infinity, or
NaN, whose format is the same as expected for the subject sequence
of the wcstod function. The corresponding argument shall be a
pointer to float.
c Matches a sequence of wide characters of exactly the number
specified by the field width (1 if no field width is present in the
directive).
If no l length modifier is present, characters from the input field
are converted as if by repeated calls to the wcrtomb function, with
the conversion state described by an mbstate_t object initialized
to zero before the first wide character is converted. The
corresponding argument shall be a pointer to the initial element of
a character array large enough to accept the sequence. No null
character is added.
If an l length modifier is present, the corresponding argument
shall be a pointer to the initial element of an array of
wchar_t large enough to accept the sequence.
No null wide character is added.
s Matches a sequence of non-white-space wide characters.
If no l length modifier is present, characters from the input field
are converted as if by repeated calls to the wcrtomb function, with
the conversion state described by an mbstate_t object initialized
to zero before the first wide character is converted. The
corresponding argument shall be a pointer to the initial element of
a character array large enough to accept the sequence and a
terminating null character, which will be added automatically.
If an l length modifier is present, the corresponding argument
shall be a pointer to the initial element of an array of wchar_t
large enough to accept the sequence and the terminating null wide
character, which will be added automatically.
[ Matches a nonempty sequence of wide characters from a set of
expected characters (the scanset).
If no l length modifier is present, characters from the input field
are converted as if by repeated calls to the wcrtomb function, with
the conversion state described by an mbstate_t object initialized
to zero before the first wide character is converted. The
corresponding argument shall be a pointer to the initial element of
a character array large enough to accept the sequence and a
terminating null character, which will be added automatically.
If an l length modifier is present, the corresponding argument
shall be a pointer to the initial element of an array of wchar_t
large enough to accept the sequence and the terminating null wide
character, which will be added automatically.
The conversion specifier includes all subsequent wide characters
in the format string, up to and including the matching right
bracket (]). The wide characters between the brackets
(the scanlist) compose the scanset, unless the wide character after
the left bracket is a circumflex (^), in which case the scanset
contains all wide characters that do not appear in the scanlist
between the circumflex and the right bracket. If the conversion
specifier begins with [] or [^], the right bracket wide character
is in the scanlist and the next following right bracket wide
character is the matching right bracket that ends the specification;
otherwise the first following right bracket wide character is the
one that ends the specification. If a - wide character is in the
scanlist and is not the first, nor the second where the first wide
character is a ^, nor the last character,
the - is added to the scanset.
p Matches the set of sequences produced by the %p conversion of the
fwprintf function. The corresponding argument is a pointer to a
pointer to void. The input item is converted to a pointer value. If
the input item is a value converted earlier during the same program
execution, the pointer that results will compare equal to that
value.
n No input is consumed. The corresponding argument is a pointer to
signed integer into which is to be written the number of wide
characters read from the input stream so far by this call to the
fwscanf function. Execution of a %n directive does not increment
the assignment count returned at the completion of execution of the
fwscanf function. No argument is converted, but one is consumed.
% Matches a single % wide character; no conversion or assignment
occurs. The complete conversion specification shall be %%.
The conversion specifiers E, F, G, and X are also valid and behave the same
as, respectively, e, f, g, and x.
Trailing white space (including new-line wide characters) is left unread
unless matched by a directive. The success of literal matches and
suppressed assignments is not directly determinable other than via
the %n directive.
@param[in] stream An open File specifier from which the input is read.
@param[in] format A wide character sequence containing characters
to be matched against, and conversion specifiers
which convert their associated arguments. Converted
items are stored according to their associated arguments.
@param ... Variable number of parameters, as required by format,
specifying the objects to receive the converted input.
@return 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, ...);
/** Formatted wide-character output to a buffer.
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).
@param[out] s A pointer to the array to receive the formatted output.
@param[in] n Maximum number of characters to write into buffer s.
@param[in] format A wide character sequence containing characters
to be copied unchanged, and conversion specifiers
which convert their associated arguments. Copied and
converted characters are written to the array pointed
to by s.
@param ... Variable number of parameters as required by format.
@return The swprintf function returns the number of wide characters
written in the array, not counting the terminating null wide
character, or a negative 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, ...);
/** Formatted wide input from a string.
The swscanf function is equivalent to fwscanf, except that the argument
Buff specifies a wide string from which the input is to be obtained, rather
than from a stream. Reaching the end of the wide string is equivalent to
encountering end-of-file for the fwscanf function.
@param[in] Buff Pointer to the string from which to obtain input.
@param[in] Format A wide character sequence containing characters
to be matched against, and conversion specifiers
which convert their associated arguments.
@param[out] ... Variable number of parameters, as required by format,
specifying the objects to receive the converted input.
@return The swscanf function returns the value of the macro EOF if an
input failure occurs before any conversion. Otherwise, the
swscanf 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 swscanf(const wchar_t * __restrict Buff, const wchar_t * __restrict Format, ...);
/** Print formatted values from an argument list.
The vfwprintf function is equivalent to fwprintf, with the variable argument list
replaced by Args, which shall have been initialized by the va_start macro (and
possibly subsequent va_arg calls). The vfwprintf function does not invoke the
va_end macro.
@param[in] Stream The output stream to receive the formatted output.
@param[in] Format A wide character sequence containing characters
to be matched against, and conversion specifiers
which convert their associated arguments.
@param[in] Args A list of arguments, initialized by the va_start macro
and accessed using the va_arg macro, used to satisfy
the directives in the Format string.
@return The vfwprintf function returns the number of wide characters
transmitted, or a negative value if an output or encoding
error occurred.
**/
int vfwprintf(FILE * __restrict Stream, const wchar_t * __restrict Format, va_list Args);
/** Formatted input from a stream.
The vfwscanf function is equivalent to fwscanf, with the variable argument
list replaced by Args, which must have been initialized by the va_start
macro (and possibly subsequent va_arg calls). The vfwscanf function does
not invoke the va_end macro.
@param[in] Stream The input stream.
@param[in] Format A wide character sequence containing characters
to be matched against, and conversion specifiers
which convert their associated arguments.
@param[in] Args A list of arguments, initialized by the va_start macro
and accessed using the va_arg macro, used to satisfy
the directives in the Format string.
@return The vfwscanf function returns the value of the macro EOF if an
input failure occurs before any conversion. Otherwise, the
vfwscanf 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 vfwscanf(FILE * __restrict Stream, const wchar_t * __restrict Format, va_list Args);
/** Formatted print, to a buffer, from an argument list.
The vswprintf function is equivalent to swprintf, with the variable
argument list replaced by Args, which must have been initialized by the
va_start macro (and possibly subsequent va_arg calls). The vswprintf
function does not invoke the va_end macro.
@param[in] S A pointer to the array to receive the formatted output.
@param[in] N Maximum number of characters to write into array S.
@param[in] Format A wide character sequence containing characters
to be matched against, and conversion specifiers
which convert their associated arguments.
@param[in] Args A list of arguments, initialized by the va_start macro
and accessed using the va_arg macro, used to satisfy
the directives in the Format string.
@return The vswprintf 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 generated.
**/
int vswprintf(wchar_t * __restrict S, size_t N, const wchar_t * __restrict Format, va_list Args);
/** Formatted input from a string, using an argument list.
The vswscanf function is equivalent to swscanf, with the variable argument
list replaced by Args, which must have been initialized by the va_start
macro. The vswscanf function does not invoke the va_end macro.
@param[in] S Pointer to the string from which to obtain input.
@param[in] Format A wide character sequence containing characters
to be matched against, and conversion specifiers
which convert their associated arguments.
@param[out] Args A list of arguments, initialized by the va_start macro
and accessed using the va_arg macro, used to satisfy
the directives in the Format string.
@return The vswscanf function returns the value of the macro EOF if an
input failure occurs before any conversion. Otherwise, the
vswscanf 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 vswscanf(const wchar_t * __restrict S, const wchar_t * __restrict Format, va_list Args);
/** Formatted print, to stdout, from an argument list.
The vwprintf function is equivalent to wprintf, with the variable argument
list replaced by Args, which must have been initialized by the va_start
macro. The vwprintf function does not invoke the va_end macro.
@param[in] Format A wide character sequence containing characters
to be matched against, and conversion specifiers
which convert their associated arguments.
@param[out] Args A list of arguments, initialized by the va_start macro
and accessed using the va_arg macro, used to satisfy
the directives in the Format string.
@return The vwprintf function returns the number of wide characters
transmitted, or a negative value if an output or encoding error
occurred.
**/
int vwprintf(const wchar_t * __restrict Format, va_list Args);
/** Formatted input, from stdin, to an argument list.
The vwscanf function is equivalent to wscanf, with the variable argument
list replaced by arg, which shall have been initialized by the va_start
macro. The vwscanf function does not invoke the va_end macro.
@param[in] Format A wide character sequence containing characters
to be matched against, and conversion specifiers
which convert their associated arguments.
@param[out] Args A list of arguments, initialized by the va_start macro
and accessed using the va_arg macro, used to satisfy
the directives in the Format string.
@return The vwscanf function returns the value of the macro EOF if an
input failure occurs before any conversion. Otherwise, the
vwscanf 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 vwscanf(const wchar_t * __restrict Format, va_list Args);
/** Formatted print to stdout.
The wprintf function is equivalent to fwprintf with the argument stdout
specifying the output stream.
@param[in] format A wide character sequence containing characters
to be copied unchanged, and conversion specifiers
which convert their associated arguments.
@param ... Variable number of parameters as required by format.
@return The wprintf function returns the number of wide characters
transmitted, or a negative value if an output or encoding error
occurred.
**/
int wprintf(const wchar_t * __restrict Format, ...);
/** Formatted input from stdin.
The wscanf function is equivalent to fwscanf with the argument stdin
specifying the input stream.
@param[in] format A wide character sequence containing characters
to be matched against, and conversion specifiers
which convert their associated arguments. Converted
items are stored according to their associated arguments.
@param ... Variable number of parameters, as required by format,
specifying the objects to receive the converted input.
@return The wscanf function returns the value of the macro EOF if an
input failure occurs before any conversion. Otherwise, the
wscanf 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 wscanf(const wchar_t * __restrict format, ...);
/* ################### Input/Output Functions ########################### */
/** Get a character from an input Stream.
If the end-of-file indicator for the input stream pointed to by stream is not set and a
next wide character is present, the fgetwc function obtains that wide character as a
wchar_t converted to a wint_t and advances the associated file position indicator for
the stream (if defined).
@param[in] Stream An input stream from which to obtain a character.
@return If the end-of-file indicator for the stream is set, or if the stream is at end-of-file, the endof-
file indicator for the stream is set and the fgetwc function returns WEOF. Otherwise,
the fgetwc function returns the next wide character from the input stream pointed to by
stream. If a read error occurs, the error indicator for the stream is set and the fgetwc
function returns WEOF. If an encoding error occurs (including too few bytes), the value of
the macro EILSEQ is stored in errno and the fgetwc function returns WEOF.
**/
wint_t fgetwc(FILE *Stream);
/** Read a string from an input stream into a buffer.
The fgetws function reads at most one less than the number of
wide characters specified by n from the stream pointed to by
stream into the array pointed to by s. No additional wide
characters are read after a new-line wide character (which is
retained) or after end-of-file. A null wide character is written
immediately after the last wide character read into the array.
@param[out] S A pointer to the array to receive the input string.
@param[in] Limit The maximum number of characters to put into Buff,
including the terminating null character.
@param[in] Stream An input stream from which to obtain a character.
@return The fgetws function returns S if successful. If end-of-file is
encountered and no characters have been read into the array, the
contents of the array remain unchanged and a null pointer is
returned. If a read or encoding error occurs during the
operation, the array contents are indeterminate and a
null pointer is returned.
**/
wchar_t *fgetws(wchar_t * __restrict S, int Limit, FILE * __restrict Stream);
/** Write a character to an output stream.
The fputwc function writes the wide character specified by c to the output stream
pointed to by stream, at the position indicated by the associated file position indicator
for the stream (if defined), and advances the indicator appropriately. If the file cannot
support positioning requests, or if the stream was opened with append mode, the
character is appended to the output stream.
@param[in] C The character to be written to Stream.
@param[in] Stream The output stream that C is to be written to.
@return The fputwc function returns the wide character written. If a write error occurs, the
error indicator for the stream is set and fputwc returns WEOF. If an encoding error
occurs, the value of the macro EILSEQ is stored in errno and fputwc returns WEOF.
**/
wint_t fputwc(wchar_t C, FILE *Stream);
/** Write a string to an output stream.
The fputws function writes the wide string pointed to by S to the stream pointed to by
Stream. The terminating null wide character is not written.
@param[in] String The character string to be written to Stream.
@param[in] Stream The output stream that String is to be written to.
@return The fputws function returns EOF if a write or encoding error occurs; otherwise, it
returns a nonnegative value.
**/
int fputws(const wchar_t * __restrict S, FILE * __restrict Stream);
/** Query or set a stream's orientation.
The fwide function determines the orientation of the stream pointed to by stream. If
Mode is greater than zero, the function first attempts to make the stream wide oriented. If
Mode is less than zero, the function first attempts to make the stream byte oriented.
Otherwise, Mode is zero and the function does not alter the orientation of the stream.
@param[in] Stream The stream to be queried.
@param[in] Mode Control value selecting between quering or setting
the Stream's orientation.
@return The fwide function returns a value greater than zero if, after the call, the stream has
wide orientation, a value less than zero if the stream has byte orientation, or zero if the
stream has no orientation.
**/
int fwide(FILE *Stream, int Mode);
/** Get a character from an input stream.
The getwc function is equivalent to fgetwc, except that if it is implemented as a
macro, it may evaluate Stream more than once, so the argument should never be an
expression with side effects.
@param[in] Stream The stream to be read.
@return The getwc function returns the next wide character from the input stream pointed to by
stream, or WEOF.
**/
wint_t getwc(FILE *Stream);
/** Get a character from stdin.
The getwchar function is equivalent to getwc with the argument stdin.
@return The getwchar function returns the next wide character from the
input stream pointed to by stdin, or WEOF.
**/
wint_t getwchar(void);
/** Write a character to an output stream.
The putwc function is equivalent to fputwc, except that if it is implemented as a
macro, it may evaluate Stream more than once, so the Stream argument should never be an
expression with side effects.
@param[in] C The wide character to be written to Stream.
@param[in] Stream The output stream that C is to be written to.
@return The putwc function returns the wide character written, or WEOF.
**/
wint_t putwc(wchar_t C, FILE *Stream);
/** Write a character to stdout.
The putwchar function is equivalent to putwc with the second argument stdout.
@param[in] C The wide character to be written to stdout.
@return The putwchar function returns the character written, or WEOF.
**/
wint_t putwchar(wchar_t C);
/** Return a character to the input Stream as if it had not been read.
The ungetwc function pushes the wide character specified by C back onto the input
stream pointed to by Stream. Pushed-back wide characters will be returned by
subsequent reads on that stream in the reverse order of their pushing. A successful
intervening call (with the stream pointed to by Stream) to a file positioning function
(fseek, fsetpos, or rewind) discards any pushed-back wide characters for the
stream. The external storage corresponding to the stream is unchanged.
One wide character of pushback is guaranteed, even if the call to the ungetwc function
follows just after a call to a formatted wide character input function fwscanf,
vfwscanf, vwscanf, or wscanf. If the ungetwc function is called too many times
on the same stream without an intervening read or file positioning operation on that
stream, the operation may fail.
If the value of C equals that of the macro WEOF, the operation fails and the input stream is
unchanged.
A successful call to the ungetwc function clears the end-of-file indicator for the stream.
The value of the file position indicator for the stream after reading or discarding all
pushed-back wide characters is the same as it was before the wide characters were pushed
back. For a text or binary stream, the value of its file position indicator after a successful
call to the ungetwc function is unspecified until all pushed-back wide characters are
read or discarded.
@param[in] C The wide character to push back onto the Stream.
@param[in] Stream The output stream that C is to be pushed back onto.
@return The ungetwc function returns the character pushed back,
or WEOF if the operation fails.
**/
wint_t ungetwc(wint_t C, FILE *Stream);
/* ################### Numeric Conversions ########################### */
/** @{
The wcstod, wcstof, and wcstold functions convert the initial portion of the wide
string pointed to by nptr to double, float, and long double representation,
respectively. First, they decompose the input string into three parts: an initial, possibly
empty, sequence of white-space wide characters (as specified by the iswspace
function), a subject sequence resembling a floating-point constant or representing an
infinity or NaN; and a final wide string of one or more unrecognized wide characters,
including the terminating null wide character of the input wide string. Then, they attempt
to convert the subject sequence to a floating-point number, and return the result.
@param[in] Nptr Pointer to the string to convert to a floating-point value.
@param[in] EndPtr Optional pointer to an object in which to store a pointer
to the final wide string.
The functions return the converted value, if any. If no conversion could be performed,
zero is returned. If the correct value is outside the range of representable values, plus or
minus HUGE_VAL, HUGE_VALF, or HUGE_VALL is returned (according to the return
type and sign of the value), and the value of the macro ERANGE is stored in errno. If
the result underflows (7.12.1), the functions return a value whose magnitude is no greater
than the smallest normalized positive number in the return type. A pointer to the
final wide string is stored in the object pointed to by endptr, provided that endptr is
not a null pointer.
**/
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);
/*@}*/
/** @{
The wcstol, wcstoll, wcstoul, and wcstoull functions convert the initial
portion of the wide string pointed to by nptr to long int, long long int,
unsigned long int, and unsigned long long int representation,
respectively. First, they decompose the input string into three parts: an initial, possibly
empty, sequence of white-space wide characters (as specified by the iswspace
function), a subject sequence resembling an integer represented in some radix determined
by the value of base, and a final wide string of one or more unrecognized wide
characters, including the terminating null wide character of the input wide string. Then,
they attempt to convert the subject sequence to an integer, and return the result.
@param[in] Nptr Pointer to the string to convert to a floating-point value.
@param[in] EndPtr Optional pointer to an object in which to store a pointer
to the final wide string.
@param[in] Base Base, 0 to 36, of the value represented by the string
pointed to by Nptr.
@return The wcstol, wcstoll, wcstoul, and wcstoull functions return the converted
value, if any. If no conversion could be performed, zero is returned. If the correct value
is outside the range of representable values, LONG_MIN, LONG_MAX, LLONG_MIN,
LLONG_MAX, ULONG_MAX, or ULLONG_MAX is returned (according to the return type
sign of the value, if any), and the value of the macro ERANGE is stored in errno.
**/
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 Src (including the
terminating null wide character) into the array pointed to by Dest.
@return The wcscpy function returns the value of Dest.
**/
wchar_t *wcscpy(wchar_t * __restrict Dest, const wchar_t * __restrict Src);
/** 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
Src to the array pointed to by Dest.
If the array pointed to by Src 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 Dest, until n wide characters in all have been written.
@return The wcsncpy function returns the value of Dest.
**/
wchar_t *wcsncpy(wchar_t * __restrict Dest, const wchar_t * __restrict Src, size_t n);
/** The wmemcpy function copies n wide characters from the object pointed to by
Src to the object pointed to by Dest.
Use this function if you know that Dest and Src DO NOT Overlap. Otherwise,
use wmemmove.
@return The wmemcpy function returns the value of Dest.
**/
wchar_t *wmemcpy(wchar_t * __restrict Dest, const wchar_t * __restrict Src, size_t n);
/** The wmemmove function copies n wide characters from the object pointed to by
Src to the object pointed to by Dest. The objects pointed to by Dest and Src 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 Dest and Src DO NOT Overlap. If Dest and Src might possibly overlap, then
use wmemmove.
@return The wmemmove function returns the value of Dest.
**/
wchar_t *wmemmove(wchar_t *Dest, const wchar_t *Src, size_t n);
/* ################### String Concatenation ########################## */
/** The wcscat function appends a copy of the wide string pointed to by Src
(including the terminating null wide character) to the end of the wide
string pointed to by Dest. The initial wide character of Src overwrites the
null wide character at the end of Dest.
@return The wcscat function returns the value of Dest.
**/
wchar_t *wcscat(wchar_t * __restrict Dest, const wchar_t * __restrict Src);
/** 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 Src to the end of the wide string pointed to by Dest. The initial wide
character of Src overwrites the null wide character at the end of Dest.
A terminating null wide character is always appended to the result.
@return The wcsncat function returns the value of Dest.
**/
wchar_t *wcsncat(wchar_t * __restrict Dest, const wchar_t * __restrict Src, 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 ########################### */
/**
The wcsftime function is equivalent to the strftime function, except that:
- The argument s points to the initial element of an array of wide characters into which
the generated output is to be placed.
- The argument maxsize indicates the limiting number of wide characters.
- The argument format is a wide string and the conversion specifiers are replaced by
corresponding sequences of wide characters.
- The return value indicates the number of wide characters.
If the total number of resulting wide characters including the terminating null wide
character is not more than maxsize, the wcsftime function returns the number of
wide characters placed into the array pointed to by s not including the terminating null
wide character. Otherwise, zero is returned and the contents of the array are
indeterminate.
**/
size_t wcsftime(wchar_t * __restrict S, size_t maxsize, const wchar_t * __restrict format, const struct tm * __restrict timeptr);
/* ############# Multibyte <--> Wide Character Conversion ############### */
/** The btowc function determines whether C constitutes a valid single-byte
character in the initial shift state.
@return The btowc function returns WEOF if c has the value EOF or if
(unsigned char)C does not constitute a valid single-byte
character in the initial shift state. Otherwise, it returns the
wide character representation of that character.
**/
wint_t btowc(int C);
/** The wctob function determines whether C corresponds to a member of the extended
character set whose multibyte character representation is a single byte when in the initial
shift state.
@return The wctob function returns EOF if C does not correspond to a multibyte
character with length one in the initial shift state. Otherwise, it
returns the single-byte representation of that character as an
unsigned char converted to an int.
**/
int wctob(wint_t C);
/** If ps is not a null pointer, the mbsinit function determines whether the
pointed-to mbstate_t object describes an initial conversion state.
@return The mbsinit function returns nonzero if ps is a null pointer
or if the pointed-to object describes an initial conversion
state; otherwise, it returns zero.
**/
int mbsinit(const mbstate_t *ps);
/* ####### Restartable Multibyte <--> Wide Character Conversion ######### */
/** The mbrlen function is equivalent to the call:
@verbatim
mbrtowc(NULL, s, n, ps != NULL ? ps : &internal)
@endverbatim
where internal is the mbstate_t object for the mbrlen function, except that
the expression designated by ps is evaluated only once.
@return The mbrlen function returns a value between zero and n,
inclusive, (size_t)(-2), or (size_t)(-1).
**/
size_t mbrlen(const char * __restrict S, size_t n, mbstate_t * __restrict ps);
/**
If S is a null pointer, the mbrtowc function is equivalent to the call:
@verbatim
mbrtowc(NULL, "", 1, ps)
@endverbatim
In this case, the values of the parameters pwc and n are ignored.
If S is not a null pointer, the mbrtowc function inspects at most n bytes beginning with
the byte pointed to by S to determine the number of bytes needed to complete the next
multibyte character (including any shift sequences). If the function determines that the
next multibyte character is complete and valid, it determines the value of the
corresponding wide character and then, if pwc is not a null pointer, stores that value in
the object pointed to by pwc. If the corresponding wide character is the null wide
character, the resulting state described is the initial conversion state.
@retval 0 if the next n or fewer bytes complete the multibyte
character that corresponds to the null wide
character (which is the value stored).
@retval between_1_and_n_inclusive if the next n or fewer bytes complete
a valid multibyte character (which is the value
stored); the value returned is the number of bytes
that complete the multibyte character.
@retval (size_t)(-2) if the next n bytes contribute to an incomplete
(but potentially valid) multibyte character, and
all n bytes have been processed (no value is stored).
@retval (size_t)(-1) if an encoding error occurs, in which case the next
n or fewer bytes do not contribute to a complete and
valid multibyte character (no value is stored); the
value of the macro EILSEQ is stored in errno, and
the conversion state is unspecified.
**/
size_t mbrtowc(wchar_t * __restrict pwc, const char * __restrict S, size_t n, mbstate_t * __restrict ps);
/**
If S is a null pointer, the wcrtomb function is equivalent to the call:
@verbatim
wcrtomb(buf, L'\0', ps)
@endverbatim
where buf is an internal buffer.
If S is not a null pointer, the wcrtomb function determines the number of bytes needed
to represent the multibyte character that corresponds to the wide character given by wc
(including any shift sequences), and stores the multibyte character representation in the
array whose first element is pointed to by S. At most MB_CUR_MAX bytes are stored. If
wc is a null wide character, a null byte is stored, preceded by any shift sequence needed
to restore the initial shift state; the resulting state described is the initial conversion state.
@return The wcrtomb function returns the number of bytes stored in the
array object (including any shift sequences). When wc is not a
valid wide character, an encoding error occurs: the function
stores the value of the macro EILSEQ in errno and
returns (size_t)(-1); the conversion state is unspecified.
**/
size_t wcrtomb(char * __restrict S, wchar_t wc, mbstate_t * __restrict ps);
/**
The mbsrtowcs function converts a sequence of multibyte characters that begins in the
conversion state described by the object pointed to by ps, from the array indirectly
pointed to by src into a sequence of corresponding wide characters. If dst is not a null
pointer, the converted characters are stored into the array pointed to by dst. Conversion
continues up to and including a terminating null character, which is also stored.
Conversion stops earlier in two cases: when a sequence of bytes is encountered that does
not form a valid multibyte character, or (if dst is not a null pointer) when len wide
characters have been stored into the array pointed to by dst. Each conversion takes
place as if by a call to the mbrtowc function.
If dst is not a null pointer, the pointer object pointed to by src is assigned either a null
pointer (if conversion stopped due to reaching a terminating null character) or the address
just past the last multibyte character converted (if any). If conversion stopped due to
reaching a terminating null character and if dst is not a null pointer, the resulting state
described is the initial conversion state.
@return If the input conversion encounters a sequence of bytes that do
not form a valid multibyte character, an encoding error occurs:
the mbsrtowcs function stores the value of the macro EILSEQ in
errno and returns (size_t)(-1); the conversion state is
unspecified. Otherwise, it returns the number of multibyte
characters successfully converted, not including the terminating
null character (if any).
**/
size_t mbsrtowcs(wchar_t * __restrict dst, const char ** __restrict src, size_t len, mbstate_t * __restrict ps);
/** The wcsrtombs function converts a sequence of wide characters from the array
indirectly pointed to by src into a sequence of corresponding multibyte
characters that begins in the conversion state described by the object
pointed to by ps. If dst is not a null pointer, the converted characters
are then stored into the array pointed to by dst. Conversion continues
up to and including a terminating null wide character, which is also
stored. Conversion stops earlier in two cases: when a wide character is
reached that does not correspond to a valid multibyte character, or
(if dst is not a null pointer) when the next multibyte character would
exceed the limit of len total bytes to be stored into the array pointed
to by dst. Each conversion takes place as if by a call to the wcrtomb
function.)
If dst is not a null pointer, the pointer object pointed to by src is
assigned either a null pointer (if conversion stopped due to reaching
a terminating null wide character) or the address just past the last wide
character converted (if any). If conversion stopped due to reaching a
terminating null wide character, the resulting state described is the
initial conversion state.
@return If conversion stops because a wide character is reached that
does not correspond to a valid multibyte character, an
encoding error occurs: the wcsrtombs function stores the
value of the macro EILSEQ in errno and returns (size_t)(-1);
the conversion state is unspecified. Otherwise, it returns
the number of bytes in the resulting multibyte character
sequence, not including the terminating null character (if any).
**/
size_t wcsrtombs(char * __restrict dst, const wchar_t ** __restrict src, size_t len, mbstate_t * __restrict ps);
#endif /* _WCHAR_H */