<wchar.h>

[Added with Amendment 1]

NULL · WCHAR_MAX · WCHAR_MIN · WEOF

btowc · fgetwc · fgetws · fputwc · fputws · fwide · fwprintf · fwscanf · getwc · getwchar · mbrlen · mbrtowc · mbsinit · mbsrtowcs · mbstate_t · putwc · putwchar · size_t · swprintf · swscanf · tm · ungetwc · vfwprintf · vfwscanf · vswprintf · vswscanf · vwprintf · vwscanf · wchar_t · wcrtomb · wcscat · wcschr · wcscmp · wcscoll · wcscpy · wcscspn · wcsftime · wcslen · wcsncat · wcsncmp · wcsncpy · wcspbrk · wcsrchr · wcsrtombs · wcsspn · wcsstr · wcstod · wcstof · wcstok · wcstold · wcstol · wcstoll · wcstoul · wcstoull · wcsxfrm · wctob · wint_t · wmemchr · wmemcmp · wmemcpy · wmemmove · wmemset · wprintf · wscanf

Include the standard header <wchar.h> so that you can perform input and output operations on wide streams or manipulate wide strings.

    /* MACROS */
#define NULL <either 0, 0L, or (void *)0> [0 in C++]
#define WCHAR_MAX <#if expression >= 127>
#define WCHAR_MIN <#if expression <= 0>
#define WEOF <wint_t constant expression>

    /* TYPES */
typedef o-type mbstate_t;
typedef ui-type size_t;
typedef i-type wchar_t; [keyword in C++]
typedef i_type wint_t;
struct tm;

    /* 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);

int fwscanf(FILE *restrict stream, const wchar_t *restrict format, ...);
int swscanf(const wchar_t *restrict s,
    const wchar_t *restrict format, ...);
int wscanf(const wchar_t *restrict format, ...);
int fwprintf(FILE *restrict stream, const wchar_t *restrict format, ...);
int swprintf(wchar_t *restrict s, size_t n,
    const wchar_t *restrict format, ...);
int wprintf(const wchar_t *restrict format, ...);
int vfwscanf(FILE *restrict stream, const wchar_t *restrict format,
    va_list arg); [added with C99]
int vswscanf(const wchar_t *restrict s, size_t n, const wchar_t *restrict format,
    va_list arg); [added with C99]
int vwscanf(const wchar_t *restrict format,
    va_list arg); [added with C99]
int vfwprintf(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 vwprintf(const wchar_t *restrict format,
    va_list arg);

size_t wcsftime(wchar_t *restrict s, size_t maxsize,
    const wchar_t *restrict format, const struct tm *restrict timeptr);

wint_t btowc(int c);
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);
int mbsinit(const mbstate_t *ps);
size_t mbsrtowcs(wchar_t *restrict dst, const char **restrict src,
    size_t len, mbstate_t *restrict ps);
size_t wcrtomb(char *restrict s, wchar_t wc,
    mbstate_t *restrict ps);
size_t wcsrtombs(char *restrict dst, const wchar_t **restrict src,
    size_t len, mbstate_t *restrict ps);
double wcstod(const wchar_t *restrict nptr,
    wchar_t **restrict endptr);
float wcstof(const wchar_t *restrict nptr,
    wchar_t **restrict endptr); [added with C99]
long double wcstold(const wchar_t *restrict nptr,
    wchar_t **restrict endptr); [added with C99]
long long wcstoll(const wchar_t *restrict nptr, wchar_t **restrict endptr,
    int base); [added with C99]
unsigned long long wcstoull(const wchar_t *restrict nptr, wchar_t **restrict endptr,
    int base); [added with C99]
long wcstol(const wchar_t *restrict nptr, wchar_t **restrict endptr,
    int base);
unsigned long wcstoul(const wchar_t *restrict nptr, wchar_t **restrict endptr,
    int base);
int wctob(wint_t c);

wchar_t *wcscat(wchar_t *restrict s1, const wchar_t *restrict s2);
int wcscmp(const wchar_t *s1, const wchar_t *s2);
int wcscoll(const wchar_t *s1, const wchar_t *s2);
wchar_t *wcscpy(wchar_t *restrict s1, const wchar_t *restrict s2);
size_t wcscspn(const wchar_t *s1, const wchar_t *s2);
size_t wcslen(const wchar_t *s);
wchar_t *wcsncat(wchar_t *restrict s1, const wchar_t *restrict s2,
    size_t n);
int wcsncmp(const wchar_t *s1, const wchar_t *s2,
    size_t n);
wchar_t *wcsncpy(wchar_t *restrict s1, const wchar_t *restrict s2,
    size_t n);
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);
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);
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);
wchar_t *wmemset(wchar_t *s, wchar_t c, size_t n);

wchar_t *wcschr(const wchar_t *s, wchar_t c); [not in C++]
const wchar_t *wcschr(const wchar_t *s, wchar_t c); [C++ only]
wchar_t *wcschr(wchar_t *s, wchar_t c); [C++ only]

wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2); [not in C++]
const wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2); [C++ only]
wchar_t *wcspbrk(wchar_t *s1, const wchar_t *s2); [C++ only]

wchar_t *wcsrchr(const wchar_t *s, wchar_t c); [not in C++]
const wchar_t *wcsrchr(const wchar_t *s, wchar_t c); [C++ only]
wchar_t *wcsrchr(wchar_t *s, wchar_t c); [C++ only]

wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2); [not in C++]
const wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2); [C++ only]
wchar_t *wcsstr(wchar_t *s1, const wchar_t *s2); [C++ only]

wchar_t *wmemchr(const wchar_t *s, wchar_t c,
    size_t n); [not in C++]
const wchar_t *wmemchr(const wchar_t *s, wchar_t c,
    size_t n); [C++ only]
wchar_t *wmemchr(wchar_t *s, wchar_t c,
    size_t n); [C++ only]

btowc

wint_t btowc(int c);

The function returns WEOF if c equals EOF. Otherwise, it converts (unsigned char)c as a one-byte multibyte character beginning in the initial conversion state, as if by calling mbrtowc. If the conversion succeeds, the function returns the wide-character conversion. Otherwise, it returns WEOF.

fgetwc

wint_t fgetwc(FILE *stream);

The function reads the next wide character c (if present) from the input stream stream, advances the file-position indicator (if defined), and returns (wint_t)c. If the function sets either the end-of-file indicator or the error indicator, it returns WEOF.

fgetws

wchar_t *fgetws(wchar_t *restrict s, int n, FILE *restrict stream);

The function reads wide characters from the input stream stream and stores them in successive elements of the array beginning at s and continuing until it stores n - 1 wide characters, stores an NL wide character, or sets the end-of-file or error indicators. If fgetws stores any wide characters, it concludes by storing a null wide character in the next element of the array. It returns s if it stores any wide characters and it has not set the error indicator for the stream; otherwise, it returns a null pointer. If it sets the error indicator, the array contents are indeterminate.

fputwc

wint_t fputwc(wchar_t c, FILE *stream);

The function writes the wide character c to the output stream stream, advances the file-position indicator (if defined), and returns (wint_t)c. If the function sets the error indicator for the stream, it returns WEOF.

fputws

int fputws(const wchar_t *restrict s, FILE *restrict stream);

The function accesses wide characters from the string s and writes them to the output stream stream. The function does not write the terminating null wide character. It returns a nonnegative value if it has not set the error indicator; otherwise, it returns WEOF.

fwide

int fwide(FILE *stream, int mode);

The function determines the orientation of the stream stream. If mode is greater than zero, it first attempts to make the stream wide oriented. If mode is less than zero, it first attempts to make the stream byte oriented. In any event, the function returns:

• a value greater than zero if the stream is left wide oriented
• zero if the stream is left unbound
• a value less than zero if the stream is left byte oriented

In no event will the function alter the orientation of a stream once it has been oriented.

fwprintf

int fwprintf(FILE *restrict stream, const wchar_t *restrict format, ...);

The function generates formatted text, under the control of the format format and any additional arguments, and writes each generated wide character to the stream stream. It returns the number of wide characters generated, or it returns a negative value if the function sets the error indicator for the stream.

fwscanf

int fwscanf(FILE *restrict stream, const wchar_t *restrict format, ...);

The function scans formatted text, under the control of the format format and any additional arguments. It obtains each scanned character from the stream stream. It returns the number of input items matched and assigned, or it returns EOF if the function does not store values before it sets the end-of-file or error indicator for the stream.

getwc

wint_t getwc(FILE *stream);

The function has the same effect as fgetwc(stream) except that a macro version of getwc can evaluate stream more than once.

getwchar

wint_t getwchar(void);

The function has the same effect as fgetwc(stdin).

mbrlen

size_t mbrlen(const char *restrict s, size_t n, mbstate_t *restrict ps);

The function is equivalent to the call:

mbrtowc(0, s, n, ps != 0 ? ps : &internal)

where internal is an object of type mbstate_t internal to the mbrlen function. At program startup, internal is initialized to the initial conversion state. No other library function alters the value stored in internal.

The function returns:

• (size_t)-2 if, after converting all n characters, the resulting conversion state indicates an incomplete multibyte character
• (size_t)-1 if the function detects an encoding error before completing the next multibyte character, in which case the function stores the value EILSEQ in errno and leaves the resulting conversion state undefined
• zero, if the next completed character is a null character, in which case the resulting conversion state is the initial conversion state
• x, the number of bytes needed to complete the next muitibyte character, in which case the resulting conversion state indicates that x bytes have been converted

Thus, mbrlen effectively returns the number of bytes that would be consumed in successfully converting a multibyte character to a wide character (without storing the converted wide character), or an error code if the conversion cannot succeed.

mbrtowc

size_t mbrtowc(wchar_t *restrict pwc, const char *restrict s,
    size_t n, mbstate_t *restrict ps);

The function determines the number of bytes in a multibyte string that completes the next multibyte character, if possible.

If ps is not a null pointer, the conversion state for the multibyte string is assumed to be *ps. Otherwise, it is assumed to be &internal, where internal is an object of type mbstate_t internal to the mbrtowc function. At program startup, internal is initialized to the initial conversion state. No other library function alters the value stored in internal.

If s is not a null pointer, the function determines x, the number of bytes in the multibyte string s that complete or contribute to the next multibyte character. (x cannot be greater than n.) Otherwise, the function effectively returns mbrtowc(0, "", 1, ps), ignoring pwc and n. (The function thus returns zero only if the conversion state indicates that no incomplete multibyte character is pending from a previous call to mbrlen, mbrtowc, or mbsrtowcs for the same string and conversion state.)

If pwc is not a null pointer, the function converts a completed multibyte character to its corresponding wide-character value and stores that value in *pwc.

The function returns:

• (size_t)-2 if, after converting all n characters, the resulting conversion state indicates an incomplete multibyte character
• (size_t)-1 if the function detects an encoding error before completing the next multibyte character, in which case the function stores the value EILSEQ in errno and leaves the resulting conversion state undefined
• zero, if the next completed character is a null character, in which case the resulting conversion state is the initial conversion state
• x, the number of bytes needed to complete the next muitibyte character, in which case the resulting conversion state indicates that x bytes have been converted

mbsinit

int mbsinit(const mbstate_t *ps);

The function returns a nonzero value if ps is a null pointer or if *ps designates an initial conversion state. Otherwise, it returns zero.

mbsrtowcs

size_t mbsrtowcs(wchar_t *restrict dst, const char **restrict src,
    size_t len, mbstate_t *restrict ps);

The function converts the multibyte string beginning at *src to a sequence of wide characters as if by repeated calls of the form:

x = mbrtowc(dst, *src, n, ps != 0 ? ps : &internal)

where n is some value > 0 and internal is an object of type mbstate_t internal to the mbsrtowcs function. At program startup, internal is initialized to the initial conversion state. No other library function alters the value stored in internal.

If dst is not a null pointer, the mbsrtowcs function stores at most len wide characters by calls to mbrtowc. The function effectively increments dst by one and *src by x after each call to mbrtowc that stores a converted wide character. After a call that returns zero, mbsrtowcs stores a null wide character at dst and stores a null pointer at *src.

If dst is a null pointer, len is effectively assigned a large value.

The function returns:

• (size_t)-1, if a call to mbrtowc returns (size_t)-1, indicating that it has detected an encoding error before completing the next multibyte character
• the number of multibyte characters successfully converted, not including the terminating null character

mbstate_t

typedef o-type mbstate_t;

The type is an object type o-type that can represent a conversion state for any of the functions mbrlen, mbrtowc, mbsrtowcs, wcrtomb, or wcsrtombs. A definition of the form:

mbstate_t mbst = {0};

ensures that mbst represents the initial conversion state. Note, however, that other values stored in an object of type mbstate_t can also represent this state. To test safely for this state, use the function mbsinit.

NULL

#define NULL <either 0, 0L, or (void *)0> [0 in C++]

The macro yields a null pointer constant that is usable as an address constant expression.

putwc

wint_t putwc(wchar_t c, FILE *stream);

The function has the same effect as fputwc(c, stream) except that a macro version of putwc can evaluate stream more than once.

putwchar

wint_t putwchar(wchar_t c);

The function has the same effect as fputwc(c, stdout).

size_t

typedef ui-type size_t;

The type is the unsigned integer type ui-type of an object that you declare to store the result of the sizeof operator.

swprintf

int swprintf(wchar_t *restrict s, size_t n,
    const wchar_t *restrict format, ...);

The function generates formatted text, under the control of the format format and any additional arguments, and stores each generated character in successive locations of the array object whose first element has the address s. The function concludes by storing a null wide character in the next location of the array. If it cannot generate and store all characters in an array of size n, the function returns a negative number. Otherwise, it returns the number of wide characters generated -- not including the null wide character.

swscanf

int swscanf(const wchar_t *restrict s,
    const wchar_t *restrict format, ...);

The function scans formatted text, under the control of the format format and any additional arguments. It accesses each scanned character from successive locations of the array object whose first element has the address s. It returns the number of items matched and assigned, or it returns EOF if the function does not store values before it accesses a null wide character from the array.

tm

struct tm;

struct tm contains members that describe various properties of the calendar time. The declaration in this header leaves struct tm an incomplete type. Include the header <time.h> to complete the type.

ungetwc

wint_t ungetwc(wint_t c, FILE *stream);

If c is not equal to WEOF, the function stores (wchar_t)c in the object whose address is stream and clears the end-of-file indicator. If c equals WEOF or the store cannot occur, the function returns WEOF; otherwise, it returns (wchar_t)c. A subsequent library function call that reads a wide character from the stream stream obtains this stored value, which is then forgotten.

Thus, you can effectively push back a wide character to a stream after reading a wide character.

vfwprintf

int vfwprintf(FILE *restrict stream, const wchar_t *restrict format,
    va_list arg);

The function generates formatted text, under the control of the format format and any additional arguments, and writes each generated wide character to the stream stream. It returns the number of wide characters generated, or it returns a negative value if the function sets the error indicator for the stream.

The function accesses additional arguments by using the context information designated by ap. The program must execute the macro va_start before it calls the function, and then execute the macro va_end after the function returns.

vfwscanf

int vfwscanf(FILE *restrict stream, const wchar_t *restrict format,
    va_list ap); [added with C99]

The function scans formatted text, under the control of the format format and any additional arguments. It obtains each scanned wide character from the stream stream. It returns the number of input items matched and assigned, or it returns WEOF if the function does not store values before it sets the end-of-file or error indicator for the stream.

The function accesses additional arguments by using the context information designated by ap. The program must execute the macro va_start before it calls the function, and then execute the macro va_end after the function returns.

vswprintf

int vswprintf(wchar_t *restrict s, size_t n, const wchar_t *restrict format,
    va_list arg);

The function generates formatted text, under the control of the format format and any additional arguments, and stores each generated wide character in successive locations of the array object whose first element has the address s. The function concludes by storing a null wide character in the next location of the array. If it cannot generate and store all characters in an array of size n, the function returns a negative number. Otherwise, it returns the number of wide characters generated -- not including the null wide character.

The function accesses additional arguments by using the context information designated by ap. The program must execute the macro va_start before it calls the function, and then execute the macro va_end after the function returns.

vswscanf

int vswscanf(const wchar_t *restrict s, const wchar_t *restrict format,
    va_list ap); [added with C99]

The function scans formatted text, under the control of the format format and any additional arguments. It accesses each scanned wide character from successive locations of the array object whose first element has the address s. It returns the number of items matched and assigned, or it returns WEOF if the function does not store values before it accesses a null character from the array.

The function accesses additional arguments by using the context information designated by ap. The program must execute the macro va_start before it calls the function, and then execute the macro va_end after the function returns.

vwprintf

int vwprintf(const wchar_t *restrict format,
    va_list arg);

The function generates formatted text, under the control of the format format and any additional arguments, and writes each generated wide character to the stream stdout. It returns the number of characters generated, or a negative value if the function sets the error indicator for the stream.

The function accesses additional arguments by using the context information designated by ap. The program must execute the macro va_start before it calls the function, and then execute the macro va_end after the function returns.

vwscanf

int vwscanf(const wchar_t *restrict format,
    va_list ap); [added with C99]

The function scans formatted text, under the control of the format format and any additional arguments. It obtains each scanned wide character from the stream stdin. It returns the number of input items matched and assigned, or it returns WEOF if the function does not store values before it sets the end-of-file or error indicators for the stream.

The function accesses additional arguments by using the context information designated by ap. The program must execute the macro va_start before it calls the function, and then execute the macro va_end after the function returns.

WCHAR_MAX

#define WCHAR_MAX <#if expression >= 127>

The macro yields the maximum value for type wchar_t.

WCHAR_MIN

#define WCHAR_MIN <#if expression <= 0>

The macro yields the minimum value for type wchar_t.

wchar_t

typedef i-type wchar_t; [keyword in C++]

The type is the integer type i-type of a wide-character constant, such as L'X'. You declare an object of type wchar_t to hold a wide character.

wcrtomb

size_t wcrtomb(char *restrict s, wchar_t wc, mbstate_t *restrict ps);

The function determines the number of bytes needed to represent the wide character wc as a multibyte character, if possible. (Not all values representable as type wchar_t are necessarily valid wide-character codes.)

If ps is not a null pointer, the conversion state for the multibyte string is assumed to be *ps. Otherwise, it is assumed to be &internal, where internal is an object of type mbstate_t internal to the wcrtomb function. At program startup, internal is initialized to the initial conversion state. No other library function alters the value stored in internal.

If s is not a null pointer and wc is a valid wide-character code, the function determines x, the number of bytes needed to represent wc as a multibyte character, and stores the converted bytes in the array of char beginning at s. (x cannot be greater than MB_CUR_MAX.) If wc is a null wide character, the function stores any shift sequence needed to restore the initial shift state. followed by a null byte. The resulting conversion state is the initial conversion state.

If s is a null pointer, the function effectively returns wcrtomb(buf, L'\0', ps), where buf is a buffer internal to the function. (The function thus returns the number of bytes needed to restore the initial conversion state and to terminate the multibyte string pending from a previous call to wcrtomb or wcsrtombs for the same string and conversion state.)

The function returns:

• (size_t)-1 if wc is an invalid wide-character code, in which case the function stores the value EILSEQ in errno and leaves the resulting conversion state undefined
• x, the number of bytes needed to complete the next muitibyte character, in which case the resulting conversion state indicates that x bytes have been generated

wcscat

wchar_t *wcscat(wchar_t *restrict s1, const wchar_t *restrict s2);

The function copies the wide string s2, including its terminating null wide character, to successive elements of the array that stores the wide string s1, beginning with the element that stores the terminating null wide character of s1. It returns s1.

wcschr

wchar_t *wcschr(const wchar_t *s, wchar_t c); [not in C++]
const wchar_t *wcschr(const wchar_t *s, wchar_t c); [C++ only]
wchar_t *wcschr(wchar_t *s, wchar_t c); [C++ only]

The function searches for the first element of the wide string s that equals c. It considers the terminating null wide character as part of the wide string. If successful, the function returns the address of the matching element; otherwise, it returns a null pointer.

wcscmp

int wcscmp(const wchar_t *s1, const wchar_t *s2);

The function compares successive elements from two wide strings, s1 and s2, until it finds elements that are not equal.

• If all elements are equal, the function returns zero.

• If the differing element from s1 is greater than the element from s2, the function returns a positive number.
• Otherwise, the function returns a negative number.

wcscoll

int wcscoll(const wchar_t *s1, const wchar_t *s2);

The function compares two wide strings, s1 and s2, using a comparison rule that depends on the current locale. If s1 compares greater than s2 by this rule, the function returns a positive number. If the two wide strings compare equal, it returns zero. Otherwise, it returns a negative number.

wcscpy

wchar_t *wcscpy(wchar_t *restrict s1, const wchar_t *restrict s2);

The function copies the wide string s2, including its terminating null wide character, to successive elements of the array whose first element has the address s1. It returns s1.

wcscspn

size_t wcscspn(const wchar_t *s1, const wchar_t *s2);

The function searches for the first element s1[i] in the wide string s1 that equals any one of the elements of the wide string s2 and returns i. Each terminating null wide character is considered part of its wide string.

wcsftime

size_t wcsftime(wchar_t *restrict s, size_t maxsize,
    const wchar_t *restrict format, const struct tm *restrict timeptr);

The function generates formatted text, under the control of the format format and the values stored in the time structure *tptr. It stores each generated wide character in successive locations of the array object of size n whose first element has the address s. The function then stores a null wide character in the next location of the array. It returns x, the number of wide characters generated, if x < n; otherwise, it returns zero, and the values stored in the array are indeterminate.

For each wide character other than % in the format, the function stores that wide character in the array object. Each occurrence of % followed by another character in the format is a conversion specifier. For each conversion specifier, the function stores a replacement wide character sequence. Conversion specifiers are the same as for the function strftime. The current locale category LC_TIME can affect these replacement character sequences.

wcslen

size_t wcslen(const wchar_t *s);

The function returns the number of wide characters in the wide string s, not including its terminating null wide character.

wcsncat

wchar_t *wcsncat(wchar_t *restrict s1, const wchar_t *restrict s2,
    size_t n);

The function copies the wide string s2, not including its terminating null wide character, to successive elements of the array that stores the wide string s1, beginning with the element that stores the terminating null wide character of s1. The function copies no more than n wide characters from s2. It then stores a null wide character, in the next element to be altered in s1, and returns s1.

wcsncmp

int wcsncmp(const wchar_t *s1, const wchar_t *s2,
    size_t n);

The function compares successive elements from two wide strings, s1 and s2, until it finds elements that are not equal or until it has compared the first n elements of the two wide strings.

• If all elements are equal, the function returns zero.
• If the differing element from s1 is greater than the element from s2, the function returns a positive number.
• Otherwise, it returns a negative number.

wcsncpy

wchar_t *wcsncpy(wchar_t *restrict s1, const wchar_t *restrict s2,
    size_t n);

The function copies the wide string s2, not including its terminating null wide character, to successive elements of the array whose first element has the address s1. It copies no more than n wide characters from s2. The function then stores zero or more null wide characters in the next elements to be altered in s1 until it stores a total of n wide characters. It returns s1.

wcspbrk

wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2); [not in C++]
const wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2); [C++ only]
wchar_t *wcspbrk(wchar_t *s1, const wchar_t *s2); [C++ only]

The function searches for the first element s1[i] in the wide string s1 that equals any one of the elements of the wide string s2. It considers each terminating null wide character as part of its wide string. If s1[i] is not the terminating null wide character, the function returns &s1[i]; otherwise, it returns a null pointer.

wcsrchr

wchar_t *wcsrchr(const wchar_t *s, wchar_t c); [not in C++]
const wchar_t *wcsrchr(const wchar_t *s, wchar_t c); [C++ only]
wchar_t *wcsrchr(wchar_t *s, wchar_t c); [C++ only]

The function searches for the last element of the wide string s that equals c. It considers the terminating null wide character as part of the wide string. If successful, the function returns the address of the matching element; otherwise, it returns a null pointer.

wcsrtombs

size_t wcsrtombs(char *restrict dst, const wchar_t **restrict src,
    size_t len, mbstate_t *restrict ps);

The function converts the wide-character string beginning at *src to a sequence of multibyte characters as if by repeated calls of the form:

x = wcrtomb(dst ? dst : buf, *src, ps != 0 ? ps : &internal)

where buf is an array of type char and internal is an object of type mbstate_t, both internal to the wcsrtombs function. At program startup, internal is initialized to the initial conversion state. No other library function alters the value stored in internal.

If dst is not a null pointer, the wcsrtombs function stores at most len bytes by calls to wcrtomb. The function effectively increments dst by x and *src by one after each call to wcrtomb that stores a complete converted multibyte character in the remaining space available. After a call that stores a complete null multibyte character at dst (including any shift sequence needed to restore the initial shift state), the function stores a null pointer at *src.

If dst is a null pointer, len is effectively assigned a large value.

The function returns:

• (size_t)-1, if a call to wcrtomb returns (size_t)-1, indicating that it has detected an invalid wide-character code
• the number of bytes successfully converted, not including the terminating null byte

wcsspn

size_t wcsspn(const wchar_t *s1, const wchar_t *s2);

The function searches for the first element s1[i] in the wide string s1 that equals none of the elements of the wide string s2 and returns i. It considers the terminating null wide character as part of the wide string s1 only.

wcsstr

wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2); [not in C++]
const wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2); [C++ only]
wchar_t *wcsstr(wchar_t *s1, const wchar_t *s2); [C++ only]

The function searches for the first sequence of elements in the wide string s1 that matches the sequence of elements in the wide string s2, not including its terminating null wide character. If successful, the function returns the address of the matching first element; otherwise, it returns a null pointer.

wcstod

double wcstod(const wchar_t *restrict nptr,
    wchar_t **restrict endptr);

The function converts the initial wide characters of the wide string s to an equivalent value x of type double. If endptr is not a null pointer, the function stores a pointer to the unconverted remainder of the wide string in *endptr. The function then returns x.

The initial wide characters of the wide string s must match the same pattern as recognized by the function strtod, where each wide character wc is converted as if by calling wctob(wc)).

If the wide string s matches this pattern, its equivalent value is the value returned by strtod for the converted sequence. If the wide string s does not match a valid pattern, the value stored in *endptr is s, and x is zero. If a range error occurs, wcstod behaves exactly as the functions declared in <math.h>.

wcstof

float wcstof(const wchar_t *restrict nptr,
 wchar_t **restrict endptr);

The function converts the initial wide characters of the wide string s to an equivalent value x of type float. If endptr is not a null pointer, the function stores a pointer to the unconverted remainder of the wide string in *endptr. The function then returns x.

The initial wide characters of the wide string s must match the same pattern as recognized by the function strtod, where each wide character wc is converted as if by calling wctob(wc)).

If the wide string s matches this pattern, its equivalent value is the value returned by strtof for the converted sequence. If the wide string s does not match a valid pattern, the value stored in *endptr is s, and x is zero. If a range error occurs, wcstod behaves exactly as the functions declared in <math.h>.

wcstok

wchar_t *wcstok(wchar_t *restrict s1, const wchar_t *restrict s2,
    wchar_t **restrict ptr);

If s1 is not a null pointer, the function begins a search of the wide string s1. Otherwise, it begins a search of the wide string whose address was last stored in *ptr on an earlier call to the function, as described below. The search proceeds as follows:

1. The function searches the wide string for begin, the address of the first element that equals none of the elements of the wide string s2 (a set of token separators). It considers the terminating null character as part of the search wide string only.
2. If the search does not find an element, the function stores the address of the terminating null wide character in *ptr (so that a subsequent search beginning with that address will fail) and returns a null pointer. Otherwise, the function searches from begin for end, the address of the first element that equals any one of the elements of the wide string s2. It again considers the terminating null wide character as part of the search string only.
3. If the search does not find an element, the function stores the address of the terminating null wide character in *ptr. Otherwise, it stores a null wide character in the element whose address is end. Then it stores the address of the next element after end in *ptr (so that a subsequent search beginning with that address will continue with the remaining elements of the string) and returns begin.

wcstol

long wcstol(const wchar_t *restrict nptr, wchar_t **restrict endptr,
    int base);

The function converts the initial wide characters of the wide string s to an equivalent value x of type long. If endptr is not a null pointer, the function stores a pointer to the unconverted remainder of the wide string in *endptr. The function then returns x.

The initial wide characters of the wide string s must match the same pattern as recognized by the function strtol, with the same base argument, where each wide character wc is converted as if by calling wctob(wc)).

If the wide string s matches this pattern, its equivalent value is the value returned by strtol, with the same base argument, for the converted sequence. If the wide string s does not match a valid pattern, the value stored in *endptr is s, and x is zero. If the equivalent value is too large in magnitude to represent as type long, wcstol stores the value of ERANGE in errno and returns either LONG_MAX if x is positive or LONG_MIN if x is negative.

wcstold

long double wcstof(const wchar_t *restrict nptr,
 wchar_t **restrict endptr);

The function converts the initial wide characters of the wide string s to an equivalent value x of type long double. If endptr is not a null pointer, the function stores a pointer to the unconverted remainder of the wide string in *endptr. The function then returns x.

The initial wide characters of the wide string s must match the same pattern as recognized by the function strtod, where each wide character wc is converted as if by calling wctob(wc)).

If the wide string s matches this pattern, its equivalent value is the value returned by strtold for the converted sequence. If the wide string s does not match a valid pattern, the value stored in *endptr is s, and x is zero. If a range error occurs, wcstod behaves exactly as the functions declared in <math.h>.

wcstoll

long long wcstoll(const wchar_t *restrict nptr, wchar_t **restrict endptr,
    int base);

The function converts the initial wide characters of the wide string s to an equivalent value x of type long long. If endptr is not a null pointer, the function stores a pointer to the unconverted remainder of the wide string in *endptr. The function then returns x.

The initial wide characters of the wide string s must match the same pattern as recognized by the function strtol, with the same base argument, where each wide character wc is converted as if by calling wctob(wc)).

If the wide string s matches this pattern, its equivalent value is the value returned by strtoll, with the same base argument, for the converted sequence. If the wide string s does not match a valid pattern, the value stored in *endptr is s, and x is zero. If the equivalent value is too large in magnitude to represent as type long long, wcstoll stores the value of ERANGE in errno and returns either LLONG_MAX if x is positive or LLONG_MIN if x is negative.

wcstoul

unsigned long wcstoul(const wchar_t *restrict nptr,
     wchar_t **restrict endptr, int base);

The function converts the initial wide characters of the wide string s to an equivalent value x of type unsigned long. If endptr is not a null pointer, it stores a pointer to the unconverted remainder of the wide string in *endptr. The function then returns x.

wcstoul converts strings exactly as does wcstol, but checks only if the equivalent value is too large to represent as type unsigned long. In this case, wcstoul stores the value of ERANGE in errno and returns ULONG_MAX.

wcstoull

unsigned long long wcstoull(const wchar_t *restrict nptr,
     wchar_t **restrict endptr, int base);

The function converts the initial wide characters of the wide string s to an equivalent value x of type unsigned long long. If endptr is not a null pointer, it stores a pointer to the unconverted remainder of the wide string in *endptr. The function then returns x.

wcstoull converts strings exactly as does wcstoll, but checks only if the equivalent value is too large to represent as type unsigned long long. In this case, wcstoull stores the value of ERANGE in errno and returns ULLONG_MAX.

wcsxfrm

size_t wcsxfrm(wchar_t *restrict s1, const wchar_t *restrict s2,
    size_t n);

The function stores a wide string in the array whose first element has the address s1. It stores no more than n wide characters, including the terminating null wide character, and returns the number of wide characters needed to represent the entire wide string, not including the terminating null wide character. If the value returned is n or greater, the values stored in the array are indeterminate. (If n is zero, s1 can be a null pointer.)

wcsxfrm generates the wide string it stores from the wide string s2 by using a transformation rule that depends on the current locale. For example, if x is a transformation of s1 and y is a transformation of s2, then wcscmp(x, y) returns the same value as wcscoll(s1, s2).

wctob

int wctob(wint_t c);

The function determines whether c can be represented as a one-byte multibyte character x, beginning in the initial shift state. (It effectively calls wcrtomb to make the conversion.) If so, the function returns x. Otherwise, it returns EOF.

WEOF

#define WEOF <wint_t constant expression>

The macro yields the return value, of type wint_t, used to signal the end of a wide stream or to report an error condition.

wint_t

typedef i_type wint_t;

The type is the integer type i_type that can represent all values of type wchar_t as well as the value of the macro WEOF, and that doesn't change when promoted.

wmemchr

wchar_t *wmemchr(const wchar_t *s, wchar_t c,
    size_t n); [not in C++]
const wchar_t *wmemchr(const wchar_t *s, wchar_t c,
    size_t n); [C++ only]
wchar_t *wmemchr(wchar_t *s, wchar_t c,
    size_t n); [C++ only]

The function searches for the first element of an array beginning at the address s with size n, that equals c. If successful, it returns the address of the matching element; otherwise, it returns a null pointer.

wmemcmp

int wmemcmp(const wchar_t *s1, const wchar_t *s2,
    size_t n);

The function compares successive elements from two arrays beginning at the addresses s1 and s2 (both of size n), until it finds elements that are not equal:

• If all elements are equal, the function returns zero.
• If the differing element from s1 is greater than the element from s2, the function returns a positive number.
• Otherwise, the function returns a negative number.

wmemcpy

wchar_t *wmemcpy(wchar_t *restrict s1, const wchar_t *restrict s2,
    size_t n);

The function copies the array beginning at the address s2 to the array beginning at the address s1 (both of size n). It returns s1. The elements of the arrays can be accessed and stored in any order.

wmemmove

wchar_t *wmemmove(wchar_t *s1, const wchar_t *s2,
    size_t n);

The function copies the array beginning at s2 to the array beginning at s1 (both of size n). It returns s1. If the arrays overlap, the function accesses each of the element values from s2 before it stores a new value in that element, so the copy is not corrupted.

wmemset

wchar_t *wmemset(wchar_t *s, wchar_t c, size_t n);

The function stores c in each of the elements of the array beginning at s, with size n. It returns s.

wprintf

int wprintf(const wchar_t *restrict format, ...);

The function generates formatted text, under the control of the format format and any additional arguments, and writes each generated wide character to the stream stdout. It returns the number of wide characters generated, or it returns a negative value if the function sets the error indicator for the stream.

wscanf

int wscanf(const wchar_t *restrict format, ...);

The function scans formatted text, under the control of the format format and any additional arguments. It obtains each scanned wide character from the stream stdin. It returns the number of input items matched and assigned, or it returns EOF if the function does not store values before it sets the end-of-file or error indicators for the stream.

See also the Table of Contents and the Index.

Copyright © 1989-2002 by P.J. Plauger and Jim Brodie. All rights reserved.