<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

errno_t · fwprintf_s · fwscanf_s · mbsrtowcs_s · rsize_t · snwprintf_s · swprintf_s · swscanf_s · vfwprintf_s · vfwscanf_s · vsnwprintf_s · vswprintf_s · vswscanf_s · vwprintf_s · vwscanf_s · wcrtomb_s · wcscat_s · wcscpy_s · wcsncat_s · wcsncpy_s · wcsnlen_s · wcsrtombs_s · wcstok_s · wmemcpy_s · wmemmove_s · wprintf_s · wscanf_s


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, 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]

#if __STDC_WANT_LIB_EXT1__ [added with TR24731]
typedef int errno_t;
typedef size_t rsize_t;

int fwprintf_s(_Filet *restrict stream,
    const wchar_t *restrict format, ...);
int fwscanf_s(_Filet *restrict stream,
    const wchar_t *restrict format, ...);
int snwprintf_s(wchar_t *restrict s, rsize_t n,
    const wchar_t *restrict format, ...);
int swprintf_s(wchar_t *restrict s, rsize_t n,
    const wchar_t *restrict format, ...);
int swscanf_s(const wchar_t *restrict s,
    const wchar_t *restrict format, ...);
int vfwprintf_s(_Filet *restrict stream,
    const wchar_t *restrict format,
    _Va_list arg);
int vfwscanf_s(_Filet *restrict stream,
    const wchar_t *restrict format,
    _Va_list arg);
int vsnwprintf_s(wchar_t *restrict s, rsize_t m,
    const wchar_t *restrict format,
    _Va_list arg);
int vswprintf_s(wchar_t *restrict s, rsize_t n,
    const wchar_t *restrict format,
    _Va_list arg);
int vswscanf_s(const wchar_t *restrict s,
    const wchar_t *restrict format,
    _Va_list arg);
int vwprintf_s(const wchar_t *restrict format,
    _Va_list arg);
int vwscanf_s(const wchar_t *restrict format,
    _Va_list arg);
int wprintf_s(const wchar_t *restrict format, ...);
int wscanf_s(const wchar_t *restrict format, ...);

errno_t wcscpy_s(wchar_t *restrict s1, rsize_t maxsize,
    const wchar_t *restrict s2);
errno_t wcsncpy_s(wchar_t *restrict s1, rsize_t maxsize,
    const wchar_t *restrict s2, rsize_t n);
errno_t wmemcpy_s(wchar_t *restrict s1, rsize_t maxsize,
    const wchar_t *restrict s2, rsize_t n);
errno_t wmemmove_s(wchar_t * s1, rsize_t maxsize,
    const wchar_t *s2, rsize_t n);
errno_t wcscat_s(wchar_t *restrict s1, rsize_t maxsize,
    const wchar_t *restrict s2);
errno_t wcsncat_s(wchar_t *restrict, rsize_t,
    const wchar_t *restrict, rsize_t);
wchar_t *wcstok_s(wchar_t *restrict s1, rsize_t *restrict psize1,
    const wchar_t *restrict s2, wchar_t **restrict pbuf1);

size_t wcsnlen_s(const wchar_t *s, size_t maxsize);

errno_t wcrtomb_s(size_t *restrict psize,
    char *restrict s, rsize_t maxsize,
    wchar_t wc,
    mbstate_t *restrict ps);
errno_t mbsrtowcs_s(size_t *restrict psize,
    wchar_t *restrict dst, rsize_t maxsize,
    const char **restrict src, rsize_t len,
    mbstate_t *restrict ps);
errno_t wcsrtombs_s(size_t *restrict psize,
    char *restrict dst, rsize_t maxsize,
    const wchar_t **restrict src, rsize_t len,
    mbstate_t *restrict ps);
#endif /* __STDC_WANT_LIB_EXT1__ */

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.

errno_t

typedef int errno_t; [added with TR24731]

The type is a synonym for int, used to represent a value that can be stored in errno.

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 wide 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:

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.

fwprintf_s

int fwprintf_s(FILE *restrict stream,
    const wchar_t *restrict format, ...); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, the function returns a negative value, after producing an unspecified amount of output.

Otherwise, 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 wide 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.

fwscanf_s

int fwscanf_s(FILE *restrict stream,
    const wchar_t *restrict format, ...); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, the function returns a negative value, after consuming an unspecified amount of input.

Otherwise, the function scans formatted text, with additional checking, 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 EOF if the function does not store values before it sets the end-of-file or error indicator for the stream.

Additional checking occurs for the scan conversion specifiers c, s, and [. Each of these conversion specifiers consumes an additional argument, of type rsize_t, that specifies the maximum number of elements N that can be stored in the array object. It is a runtime constraint violation if N is greater than RSIZE_MAX, or if the number of elements to be stored is greater than N.

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:

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.

The function is not necessarily thread safe if ps is a null pointer.

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:

The function is not necessarily thread safe if ps is a null pointer.

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:

The function is not necessarily thread safe if ps is a null pointer.

mbsrtowcs_s

errno_t mbsrtowcs_s(size_t *restrict psize,
    wchar_t *restrict dst, rsize_t maxsize,
    const char *restrict src, rsize_t len,
    mbstate_t *restrict ps); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, other than the first one, and dst is not a null pointer, the function stores a null wide character at dst[0]. If psize is not a null pointer, the function stores (rsize_t)-1 in *psize. It returns the error code it reported to the constraint handler.

Otherwise, 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)

where n is some value > 0.

If dst is not a null pointer, the mbsrtowcs_s 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_s stores a null wide character at dst and stores a null pointer at *src. If no such null wide character is stored, the function stores a null wide character at dst[len].

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

The function returns zero if all conversions are successful; otherwise, it returns a nonzero value.

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).

rsize_t

typedef size_t rsize_t; [added with TR24731]

The type is a synonym for size_t, used to represent a function argument to be checked on entry to a function. It is a runtime constraint violation for an argument of type rsize_t to be greater than RSIZE_MAX.

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.

snwprintf_s

int snwprintf_s(wchar_t *restrict s, rsize_t n,
    const wchar_t *restrict format, ...); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, other than the first two, the function stores a null character at s[0]. It then returns a negative value.

Otherwise, the function generates formatted text, under the control of the format format and any additional arguments, and stores each wide generated character in successive locations of the array object whose first element has the address s. If n is zero, it stores no wide characters. Otherwise, the function stores up to n - 1 wide characters and concludes by storing a null wide character in the next location of the array. It returns the total number of wide characters generated (even those not stored), not including the null wide character, or a negative value if an encoding error occurs.

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.

swprintf_s

int swprintf_s(wchar_t *restrict s, rsize_t n,
    const wchar_t *restrict format, ...); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, other than the first two, the function stores a null wide character in s[0]. It then returns zero.

Otherwise, 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. If n is zero, it stores no characters. Otherwise, the function stores up to n - 1 wide characters and concludes by storing a null wide character in the next location of the array. It returns the total number of wide characters generated (even those not stored), not including the null wide character, or a negative value if an encoding error occurs.

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.

swscanf_s

int swscanf_s(const wchar_t *restrict s, const wchar_t *restrict format, ...); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, the function returns a negative value, after consuming an unspecified amount of input.

Otherwise, the function scans formatted text, with additional checking, 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.

vfwprintf_s

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

A runtime constraint violation occurs if:

If such a violation occurs, the function returns a negative value, after producing an unspecified amount of output.

Otherwise, 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.

vfwscanf_s

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

A runtime constraint violation occurs if:

If such a violation occurs, the function returns a negative value, after consuming an unspecified amount of input.

Otherwise, the function scans formatted text, with additional checking, 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 EOF 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.

vsnwprintf_s

int vsnwprintf_s(wchar_t *restrict s, rsize_t n, const wchar_t *restrict format,
    va_list ap); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, other than the first two, the function stores a null wide character at s[0]. It then returns a negative value.

Otherwise, the function generates formatted text, under the control of the format format and any additional arguments, and stores generated wide characters in successive locations of the array object whose first element has the address s. If n is zero, it stores no wide characters. Otherwise, the function stores up to n - 1 wide characters and concludes by storing a null wide character in the next location of the array. It returns the total number of wide characters generated (even those not stored), not including the null wide character, or a negative value if an encoding error occurs.

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.

vswprintf_s

int vswprintf_s(wchar_t *restrict s, rsize_t n,
    const wchar_t *restrict format,
    va_list ap); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, other than the first two, the function stores a null wide character at s[0]. It then returns zero.

Otherwise, 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. It returns the number of characters generated, not including the null character, or a negative value if an encoding error occurs.

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.

vswscanf_s

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

A runtime constraint violation occurs if:

If such a violation occurs, the function returns a negative value, after consuming an unspecified amount of input.

Otherwise, the function scans formatted text, with additional checking, 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 EOF if the function does not store values before it accesses a null wide 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.

vwprintf_s

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

A runtime constraint violation occurs if:

If such a violation occurs, the function returns a negative value, after producing an unspecified amount of output.

Otherwise, 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 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.

vwscanf_s

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

A runtime constraint violation occurs if:

If such a violation occurs, the function returns a negative value, after consuming an unspecified amount of input.

Otherwise, the function scans formatted text, with additional checking, 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.

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:

The function is not necessarily thread safe if ps is a null pointer.

wcrtomb_s

errno_t wcrtomb_s(int *restrict pstat,
    char *restrict s, rsize_t maxsize, wchar_t wchar,
    mbstate_t *restrict ps); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, other than the first one, and s is not a null pointer, the function stores a null wide character in s[0]. If pstat is not a null pointer, the function stores (size_t)-1 in *pstat. It returns the error code it reported to the constraint handler.

Otherwise, 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.) The conversion state for the multibyte string is assumed to be *ps.

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_s or wcsrtombs_s for the same string and conversion state.)

The function returns zero if all conversions are successful; otherwise, it returns a nonzero value.

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.

wcscat_s

errno_t wcscat_s(wchar_t *restrict s1, rsize_t maxsize,
    const wchar_t *restrict s2); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, other than the first two, the function stores a null wide character in s1[0]. It returns the error code it reported to the constraint handler.

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

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.

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.

wcscpy_s

errno_t wcscpy_s(wchar_t *restrict s1, rsize_t maxsize,
    const wchar_t *restrict s2); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, other than the first two, the function stores a null wide character in s1[0]. It returns the error code it reported to the constraint handler.

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

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.

wcsncat_s

errno_t wcsncat_s(wchar_t *restrict s1, rsize_t maxsize,
    const wchar_t *restrict s2, rsize_t n); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, other than the first two, the function stores a null wide character in s1[0]. It returns the error code it reported to the constraint handler.

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

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.

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.

wcsncpy_s

errno_t wcsncpy_s(wchar_t *restrict s1, rsize_t maxsize,
    const wchar_t *restrict s2, rsize_t n); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, other than the first two, the function stores a null wide character in s1[0]. It returns the error code it reported to the constraint handler.

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

wcsnlen_s

size_t wcsnlen_s(const wchar_t *s, size_t maxsize); [added with TR24731]

If s is a null pointer, the function returns zero. Otherwise, if a null wide character occurs in the first maxsize elements of the array beginning at s, the function returns the number of wide characters before the first null wide character. Otherwise, the function returns maxsize.

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:

The function is not necessarily thread safe if ps is a null pointer.

wcsrtombs_s

errno_t wcsrtombs_s(size_t *restrict psize,
    char *restrict dst, rsize_t maxsize,
    const wchar_t *restrict src, rsize_t len,
    mbstate_t *ps) [added with TR24731];

A runtime constraint violation occurs if:

If such a violation occurs, other than the first one, and dst is not a null pointer, the function stores a null character at dst[0]. If psize is not a null pointer, the function stores (rsize_t)-1 in *psize. It returns the error code it reported to the constraint handler.

Otherwise, 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)

where buf is an array of type char internal to the wcsrtombs function.

If dst is not a null pointer, the wcsrtombs_s 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 no such null cnaracter is stored, the function stores a null wide immediately after the last stored byte.

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

The function returns zero if all conversions are successful; otherwise, it returns a nonzero value.

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 wide string) and returns begin.

wcstok_s

char 8wcstok_s(wchar_t *restrict s1, rsize_t *restrict psize1,
    const wchar_t *restrict s2, wchar_t **restrict pbuf1); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, the function stores nothing and returns a null pointer.

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

  1. The function searches the 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 wide character as part of the search string only.
  2. If the search does not find an element, the function stores the address of the terminating null wide character in the internal static-duration object (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 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 the internal static-duration object. 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 the internal static-duration object (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:

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.

wmemcpy_s

errno_t wmemcpy_s(wchar_t *restrict s1, rsize_t maxsize,
    const wchar_t *restrict s2, size_t n); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, other than the first two, the function stores null wide characters in the first maxsize elements of the array of char beginning at the address s1. It returns the error code it reported to the constraint handler.

Otherwise, the function copies the array of wchar_t beginning at the address s2 to the array of wchar_t beginning at the address s1 (both of size n). It returns zero.

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.

wmemmove_s

errno_t wmemmove_s(wchar_t *s1, rsize_t maxsize,
    const wchar_t *s2, size_t n); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, other than the first two, the function stores null characters in the first maxsize elements of the array of wchar_t beginning at the address s1. It returns the error code it reported to the constraint handler.

Otherwise, the function copies the array of wchar_t beginning at s2 to the array of wchar_t beginning at s1 (both of size n). It returns zero. 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.

wprintf_s

int wprintf_s(const wchar_t *restrict format, ...); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, the function returns a negative value, after producing an unspecified amount of output.

Otherwise, 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.

wscanf_s

int wscanf_s(const wchar_t *restrict format, ...); [added with TR24731]

A runtime constraint violation occurs if:

If such a violation occurs, the function returns a negative value, after consuming an unspecified amount of input.

Otherwise, the function scans formatted text, with additional checking, 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 © 1992-2013 by P.J. Plauger and Jim Brodie. All rights reserved.