13.20 <cwchar>

The <cwchar> header is the C++ version of the C standard <wchar.h> header, which declares types and functions for working with wide characters. Many of these functions are wide versions of functions found in <cstdio> and <cstring> plus improved versions of the multibyte functions from <cstdlib>.

You can use narrow (byte-oriented) I/O functions, as declared in <cstdio>, or wide I/O functions, as declared in <cwchar>, but you cannot mix wide and narrow functions on a single stream without explicitly changing the stream's orientation (see the fwide function in this section for details).

Wide I/O treats a file as a sequence of multibyte characters. When reading, multibyte characters are converted to wide characters, and when writing, wide characters are converted to multibyte characters. The conversion depends on the C locale (set with setlocale in <clocale>).

See Chapter 1 for information about character sets, Chapter 8 for information about multibyte characters and shift states, and Chapter 9 for information about wide characters and I/O.

When working with wide characters, consider using the C++ I/O streams and wstring class instead of the C functions. (See <string> later in this chapter for the wstring class and the char_traits class template.) The <locale> header provides additional support for converting between narrow and wide characters (the codecvt and related facets).

wint_t btowc(int c)

The btowc function returns a wide character representation of c, which is a multibyte character that can be represented in a single byte (as an unsigned char). If c is not a valid one-byte, multibyte character, or if c is EOF, WEOF is returned.

See Also

mbrtowc function, wctob function, WEOF macro, codecvt in <locale>

wint_t fgetwc(FILE* stream)

The fgetwc function reads the next wide character from stream. It returns the character read, or WEOF for end-of-file or an error.

See Also

fgetws function, fputwc function, getwc macro, fgetc in <cstdio>

wchar_t* fgetwc(wchar_t* str, int n, FILE* stream)

The fgetws function reads a line of wide characters from stream and stores them in str. The newline character is also stored. At most, n wide characters are stored in str, including a terminating null wide character.

The return value is str for success or a null pointer for end-of-file or an error.

See Also

fgetwc function, fputws function, fgets in <cstdio>

wint_t fputwc(wchar_t wc, FILE* stream)

The fputwc function writes a wide character, wc, to stream. It returns wc, or WEOF for an error.

See Also

fgetwc function, putwc macro, fputc in <cstdio>

int fputws(const wchar_t* str, FILE* stream)

The fputws function writes the wide string str to stream. It returns EOF (not WEOF) for an error, or a nonnegative value for success.

See Also

fgetws function, fputwc function, fputs in <cstdio>

int fwide(FILE* stream, int mode);

The fwide function gets or sets the orientation of stream. The orientation is wide or narrow (byte). When a file is opened, it starts without orientation. Calling any wide I/O function on the stream gives it wide orientation. Calling any narrow I/O function on the stream gives it narrow orientation. Mixing narrow and wide functions on a stream results in an error—that is, calling a narrow function on a stream with wide orientation or calling a wide function on a stream with narrow orientation results in an error.

Before performing any I/O on a newly opened stream, you can force the stream's orientation by calling fwide. Once the orientation is set, it cannot be changed except by closing and reopening the stream (for example, by calling freopen in <cstdio>).

If mode is positive, the orientation is set to wide. If mode is negative, the orientation is set to narrow. If the orientation has already been set, it is not changed, and the stream's true orientation is returned. If mode is 0, the orientation is queried without being changed.

The return value indicates the new orientation: positive for wide, negative for narrow, or 0 if the stream has no orientation.

See Also

fopen in <cstdio>, freopen in <cstdio>

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

The fwprintf function writes wide output to stream, formatted according to the conversion specifiers in format. See fprintf in <cstdio> for more information.

See Also

fprintf in <cstdio>

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

The fwscanf function reads wide input from stream and interprets it according to the conversion specifiers in format. See fscanf in <cstdio> for more information.

See Also

fscanf in <cstdio>

wint_t getwc(FILE* stream)

The getwc macro reads a wide character from stream. It returns the character converted to wint_t, or WEOF for end-of-file or an error.

See Also

fgetwc function, getwchar macro, getc in <cstdio>

wint_t getwchar(  )

The getwchar macro is equivalent to getwc(stdin).

See Also

getwc macro, getchar in <cstdio>

size_t mbrlen(const char* str, size_t n, mbstate_t* ps)

The mbrlen function counts the number of bytes needed to complete the next multibyte character that str points to. At most, n bytes of str are examined.

The ps parameter points to the shift state, which keeps track of the conversion state between calls to mbrlen. If ps is a null pointer, an internal shift state is used (which is similar to calling mblen in <cstdlib>).

The return value is one of the following:

0

If the multibyte character represents the null wide character

static_cast<size_t>(-1)

If str does not point to a valid multibyte character

static_cast<size_t>(-2)

If n is too small

Anything else

If the multibyte character is valid, in which case the value returned is the number of bytes in the multibyte character

See Also

mbrtowc function, mbstate_t type, mblen in <cstdlib>

size_t mbrtowc(wchar_t* pwc, const char* str, size_t n, mbstate_t* ps)

The mbrtowc function converts a multibyte character to a wide character. First, it counts the number of bytes needed to complete the next multibyte character that str points to. At most, n bytes of str are examined. If str points to a valid multibyte character, that character is converted to a wide character, which is stored in *pwc.

The ps parameter points to the shift state, which keeps track of the conversion state between calls to mbrtowc. If ps is a null pointer, an internal shift state is used (which is similar to calling mbtowc in <cstdlib>).

The return value is one of the following:

0

If the multibyte character represents the null wide character

static_cast<size_t>(-1)

If str does not point to a valid multibyte character

static_cast<size_t>(-2)

If n is too small

Anything else

If the multibyte character is valid, in which case the value returned is the number of bytes in the multibyte character

See Also

mbstate_t type, mbtowc in <cstdlib>, codecvt in <locale>

int mbsinit(const mbstate_t* ps)

The mbsinit function returns true (nonzero) if ps is a null pointer or it points to an mbstate_t object that is in the initial shift state; otherwise, it returns false (0).

See Also

mbstate_t type

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

The mbsrtowcs converts a multibyte string to a wide character string. The src parameter indirectly points to the null-terminated multibyte string, that is, *src points to the start of the multibyte string.

If dst is not null, up to len wide characters are stored in dst. If fewer than len characters are stored, a trailing null character is appended to the wide character array. If conversion stops upon reaching a null character in the src string, a null pointer is assigned to *src; otherwise, *src is assigned a pointer to the byte immediately past the end of the last multibyte character converted.

The dst parameter can be a null pointer, in which case no wide characters are stored and *src is not altered, but ps is updated and the return value is the same as it would be if dst were large enough to hold the entire converted string.

The ps parameter points to the shift state, which keeps track of the conversion state between calls to mbsrtowcs. If ps is a null pointer, an internal shift state is used (which is similar to calling mbstowcs in <cstdlib>). If the conversion ends without a terminating null character in *src, the shift state is reset to an mbstate_t initial state.

The return value is the number of wide characters successfully converted. If any multibyte character is not valid, the return value is static_cast<size_t>(-1).

See Also

mbrtowc function, mbstate_t type, mbstowcs in <cstdlib>, codecvt in <locale>

typedef  . . .  mbstate_t

The mbstate_t type is an opaque, POD type that stores the conversion state used to convert between multibyte and wide characters. The type is implementation-defined, but it is not an array type, so an mbstate_t object can be returned from a function.

A value of 0 for an mbstate_t object corresponds to the initial shift state, although other values might also represent the initial state. Thus, to initialize an mbstate_t object, use a default constructor:

std::mbstate_t mbs = std::mbstate_t(  );

If two mbstate_t objects are identical, they represent the same shift state, but the reverse is not necessarily true.

There is no way to compare two mbstate_t objects to determine whether they represent the same state, but you can call mbsinit to determine whether a state is the initial state.

Typically, you would use an mbstate_t object by initializing it to the initial shift state, then passing it to any of the multibyte functions (such as mbrtowc) repeatedly. Each call to the multibyte function reads the shift state and uses that information for the conversion, updating the shift state depending on which multibyte characters were provided as input. You should not alter the mbstate_t object between calls to the multibyte function.

See Also

mbrlen function, mbrtowc function, mbsinit function, mbsrtowcs function, wcrtomb function, wcsrtombs function

#define NULL  . . .

The NULL macro expands to a null pointer constant. See <cstddef> for more information.

See Also

NULL in <cstddef>

wint_t putwc(wchar_t wc, FILE* stream)

The putwc macro writes the wide character wc. The return value is the character converted to wint_t, or WEOF for an error.

See Also

fputwc function, putwchar macro, putc in <cstdio>

wint_t putwchar(wchar_t wc)

The putwchar macro is equivalent to puwc(wc, stdout).

See Also

putwc macro, putchar in <cstdio>

typedef  . . .  size_t

The size_t type is the type of the result of the sizeof operator. It is an unsigned integral type. The exact type is implementation-defined.

See Also

size_t in <cstddef>

int swprintf(wchar_t* dst, size_t n, const wchar_t* format,  . . . )

The swprintf function is similar to sprintf, except it stores the formatted output in a wide string, dst, and the format is a wide string. Another difference is that n is the maximum number of wide characters (including a terminating null wide character) that can be written to dst.

The return value is the number of wide characters actually stored in dst (not counting the terminating null wide character) or a negative value if the formatted output requires n or more characters (not including the terminating null character).

See Also

fwprintf function, vswprintf function, sprintf in <cstdio>

int swscanf(const wchar_t* str, const wchar_t* format,  . . . )

The swscanf function is similar to sscanf, except it reads from a wide string, str, and the format string is also wide. Like sscanf, the return value is the number of items converted.

See Also

fwscanf function, sscanf in <cstdio>

struct tm {
  int tm_sec;   /* Seconds: 0-61 */
  int tm_min;   /* Minutes: 0-60 */
  int tm_hour;  /* Hours:   0-24 */
  int tm_mday;  /* Day of month: 1-31 */
  int tm_mon;   /* Month: 1-12 */
  int tm_year;  /* Years since 1900 */
  int tm_wday;  /* Days since Sunday: 0-6 */
  int tm_yday;  /* Days since January 1: 0-365 */
  int tm_isdst; /* Daylight Savings Time */
}

The tm structure stores parts of a date and time. It is the same structure definition as that found in <ctime>. See <ctime> for details.

See Also

tm struct in <ctime>

wint_t ungetwc(wint_t wc, FILE* stream)

The ungetwc function pushes back the wide character wc, so the next read from stream will return wc. The standard guarantees that you can push back just one character, though in some situations you may be able to push back more.

The return value is wc if the pushback was successful, or WEOF if the pushback was not successful.

See Also

fgetwc function, getwc function, ungetc in <cstdio>

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

The vfwprintf function is similar to vfprintf in <cstdio>, except it prints wide characters to stream, and the format parameter is a wide string.

See Also

vfprintf in <cstdio>, <cstdarg>

int vswprintf(wchar_t* dst, size_t n, const wchar_t* format, va_list arg)

The vswprintf function is similar to vsprintf in <cstdio>, except it stores its output in a wide string, dst, and the format parameter is a wide string. Another difference is that no more than n wide characters are written to dst, including a terminating null character.

See Also

swprintf function, vsprintf in <cstdio>, <cstdarg>

int vwprintf(const wchar_t* format, va_list arg)

The vwprintf function is similar to vprintf in <cstdio>, except it prints wide characters to stdout, and the format parameter is a wide string.

See Also

wprintf function, vprintf in <cstdio>, <cstdarg>

wchar_t WCHAR_MAX

The WCHAR_MAX macro is the largest value that can be represented by the wchar_t type. It is not necessarily a valid character in the extended character set.

See Also

WCHAR_MIN macro, CHAR_MAX in <climits>, <limits>

wchar_t WCHAR_MIN

The WCHAR_MIN macro is the smallest value that can be represented by the wchar_t type. It is not necessarily a valid character in the extended character set.

See Also

WCHAR_MAX macro, CHAR_MIN in <climits>, <limits>

size_t wcrtomb(char* dst, wchar_t wc, mbstate_t* ps)

The wcrtomb function converts a wide character to a multibyte character. It first determines the number of bytes needed to represent wc as a multibyte character. If dst is not null, the sequence of multibyte characters is stored there. At most, MB_CUR_MAX (defined in <cstdlib>) bytes are stored, and the return value is the actual number of bytes written to dst. If wc does not have a valid multibyte encoding, static_cast<size_t>(-1) is returned.

If dst is null, wcrtomb ignores wc and converts the null wide character using a private, internal buffer (e.g., wcrtomb(buffer, L'\0', ps)).

The ps parameter points to the shift state, which keeps track of the conversion state between calls to wcrtomb. If ps is null, an internal shift state is used (which is similar to calling wctomb in <cstdlib>).

See Also

mbrtowc function, mbstate_t type, MB_CUR_MAX in <cstdlib>, wctomb in <cstdlib>, codecvt in <locale>

wchar_t* wcscat(wchar_t* dst, const wchar_t* src)

The wcscat function concatenates src onto the end of dst, overwriting the null character at the end of dst. The caller must ensure that dst points to a region of memory that is large enough to hold the entire string plus its null terminator. The return value is dst.

See Also

wcscpy function, wcsncat function, strcat in <cstring>

const wchar_t* wcschr(const wchar_t* str, wchar_t wc)
      wchar_t* wcschr(      wchar_t* str, wchar_t wc)

The wcschr function returns a pointer to the first occurrence of wc in the null-terminated wide string str. If wc does not appear in str, a null pointer is returned.

See Also

wmemchr function, wcscspn function, wcspbrk function, wcsrchr function, wcsspn function, strchr in <cstring>

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

The wcscmp function compares two null-terminated wide strings. If the strings are equal, the return value is 0. Otherwise, the return value is positive if s1 is greater than s2 or negative if s1 is less than s2. If one string is a prefix of the other, the longer string is greater than the shorter string.

See Also

wmemcmp function, wcsncmp function, strcmp in <cstring>

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

The wcscoll function compares two null-terminated wide strings, interpreting the strings according to the LC_COLLATE (defined in <clocale>) category of the current C locale. The return value is the same as that of wcscmp.

See Also

wcscmp function, strcoll in <cstring>, <clocale>, collate in <locale>

wchar_t* wcscpy(wchar_t* dst, const wchar_t* src)

The wcscpy function copies the null-terminated wide string src to dst. The caller must ensure that dst points to a region of memory that is large enough to hold the entire src string plus its null terminator. The return value is dst.

See Also

wmemcpy function, wcsncpy function, strcpy in <cstring>

size_t wcscspn(const wchar_t* str, const wchar_t* spanset)

The wcscspn function returns the number of wide characters at the start of str that are not in the wide string spanset. Thus, the c in its name means complement, that is, wcscspn counts characters that are in the complement of the span set.

See Also

wcschr function, wcspbrk function, wcsspn function, wcsstr function, strspn in <cstring>

size_t wcsftime(wchar_t* str, size_t n, const wchar_t* format, const tm* tmptr)

The wcsftime function is similar to strftime in <ctime>, except it formats the result as a wide string, str, and the format parameter is a wide string.

See Also

strftime in <ctime>

size_t wcslen(const wchar_t* str)

The wcslen function returns the number of wide characters (not including the terminating null wide character) in str.

See Also

strlen in <cstring>

wchar_t* wcscat(wchar_t* dst, const wchar_t* src, size_t n)

The wcsncat function concatenates src onto the end of dst. At most, n wide characters are copied from src. A terminating null wide character is always appended to the end of dst. You must ensure that dst points to a region of memory that is large enough to hold the concatenated result plus the null terminator. The return value is dst.

See Also

wcscat function, strncat in <cstring>

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

The wcsncmp function compares at most n wide characters of two null-terminated wide strings. If the strings are equal, the return value is 0. Otherwise, the return value is positive if s1 is greater than s2 or negative if s1 is less than s2. If one string is a prefix of the other, the longer string is greater than the shorter string.

See Also

wcscmp function, strncmp in <cstring>

wchar_t* wcsncpy(wchar_t* dst, const wchar_t* src, size_t n)

The wcsncpy function copies at most n wide characters from the null-terminated wide string src to dst. If src is shorter than dst, null wide characters are appended to the end so that exactly n characters are always written to dst.

The return value is dst.

See Also

wcscpy function, strncpy in <cstring>

const wchar_t* wcspbrk(const wchar_t* str, const wchar_t* spanset)
      wchar_t* wcspbrk(      wchar_t* str, const wchar_t* spanset)

The wcspbrk function searches str for any of the wide characters in spanset and returns a pointer to the first occurrence of such a character. If none of the characters in spanset appears in str, strpbrk returns a null pointer.

See Also

wcschr function, wcscspn function, wcsspn function, strpbrk in <cstring>

const wchar_t* wcsrchr(const wchar_t* str, wchar_t wc)
      wchar_t* wcsrchr(      wchar_t* str, wchar_t wc)

The wcsrchr function returns a pointer to the last (rightmost) occurrence of wc in the null-terminated wide string str. If wc does not appear in str, the function returns a null pointer .

See Also

wmemchr function, wcschr function, strrchr in <cstring>

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

The wcsrtombs function converts a wide string to a string of multibyte characters. The src parameter points indirectly to the source wide string, that is, *src points to the start of the wide string.

If dst is not null, up to len bytes are stored in dst. If fewer than len bytes are stored, a trailing null character is appended to the narrow character array. If conversion stops upon reaching a null wide character in the src string, a null pointer is assigned to *src; otherwise, *src is assigned a pointer to the character immediately past the end of the last wide character converted.

The dst parameter can be null, in which case no narrow characters are stored and *src is not altered, but ps is updated and the return value is the same as it would be if dst were large enough to hold the entire converted string.

The ps parameter points to the shift state, which keeps track of the conversion state between calls to wcsrtombs. If ps is null, an internal shift state is used (which is similar to calling wcstombs in <cstdlib>). If the conversion ends without a terminating null character in *src, the shift state is reset to an mbstate_t initial state.

If any of the wide characters cannot be represented as a multibyte character, static_cast<size_t>(-1) is returned. Otherwise, the return value is the number of bytes successfully converted from wide characters (not counting the trailing null byte).

See Also

mbstate_t type, wmbsrtowcs function, wcrtomb function, wcstombs in <cstdlib>, codecvt in <locale>

size_t wcsspn(const wchar_t* str, const wchar_t* spanset)

The wcsspn function returns the number of wide characters at the start of str that are in the string spanset.

See Also

wcschr function, wcscspn function, wcspbrk function, strspn in <cstring>

const wchar_t* wcsstr(const wchar_t* str, const wchar_t* substr)
      wchar_t* wcsstr(      wchar_t* str, const wchar_t* substr)

The wcsstr function returns the index in str of the first occurrence of substr, or a null pointer if substr does not appear in str.

See Also

wcschr function, strstr in <cstring>

double wcstod(const wchar_t* str, wchar_t** end)

The wcstod function converts a wide string to double. It is similar to the strtod function.

See Also

wcstol function, wcstoul function, strtod in <cstdlib>

wchar_t* wcstok(wchar_t* str, const wchar_t* delimset, wchar_t** ptr)

The wcstok function is similar to strtok in <cstring>, except it works with wide strings. Another difference is that it is reentrant, taking a third parameter, ptr, which is the address of a wide string. The wcstok function uses ptr for storing working information, which it uses when str is null.

To parse a string str, you must call wcstok multiple times. The first time, pass str as the first parameter to wcstok; for the second and subsequent calls, pass a null pointer. For the final argument, ptr, pass the address of a wchar_t* object. For subsequent calls to wcstok (when str is null), pass the address of the same ptr object. Do not modify ptr between successive calls to wcstok when parsing a single wide string.

Each call to wcstok can use a different delimset.

See Also

wcscspn function, wcspbrk function, wcsspn function, strtok in <cstring>

long int wcstol(const wchar_t* str, wchar_t** end)

The wcstol function converts a wide string to long int. It is similar to the strtol function in <cstdlib>.

See Also

wcstod function, wcstoul function, strtol in <cstdlib>

unsigned long int wcstoul(const wchar_t* str, wchar_t** end)

The wcstoul function converts a wide string to unsigned long int. It is similar to the strtoul function in <cstdlib>.

See Also

wcstod function, wcstol function, strtoul in <cstdlib>

size_t strxfrm(wchar_t* dst, const wchar_t* src, size_t n)

The wcsxfrm function transforms the src wide string by converting each wide character to its collation order equivalent. The functionality and return value are similar to strxfrm in <cstring>, except wcsxfrm works with wide strings.

See Also

wcscmp function, wcscoll function, strxfrm in <cstring>, collate in <locale>, <clocale>

int wctob(wint_t wc)

If the wide character wc has a single-byte representation as a multibyte character, wctob returns that byte; otherwise, it returns EOF.

See Also

btowc function, EOF in <cstdio>, codecvt in <locale>

wint_t WEOF

The WEOF macro expands to a constant integer value that does not correspond to any valid wide character value. Unlike EOF, WEOF is not guaranteed to be negative.

See Also

wint_t type, EOF in <cstdio>

typedef  . . .  wint_t

The wint_t type is an integral type that represents wide characters. It can hold the value for any character in the extended character set plus the value WEOF.

See Also

WEOF macro

const wchar_t* wmemchr(const wchar_t* mem, wchar_t c, size_t n)
      wchar_t* wmemchr(      wchar_t* mem, wchar_t c, size_t n)

The wmemchr function searches the memory that mem points to, of size n wide characters, for the wide character whose value is c. The return value is a pointer in the mem array that points to the first occurrence of c, or a null pointer if c is not present in the first n wide characters of mem.

See Also

wcschr function, find in <algorithm>, memchr in <cstring>

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

The wmemcmp function compares the first n wide characters of s1 and s2. If all n wide characters are equal, the return value is 0. Otherwise, the return value is positive if s1 is greater than s2 or negative if s1 is less than s2.

See Also

wcscmp function, wcsncmp function, equal in <algorithm>, lexicographical_compare in <algorithm>, mismatch in <algorithm>, memcmp in <cstring>

wchar_t* wmemcpy(wchar_t* dst, const wchar_t* src, size_t n)

The wmemcpy function copies n wide characters from src to dst. If src and dst overlap, the results are undefined. The return value is dst.

See Also

wcscpy function, wcsncpy function, wmemmove function, copy in <algorithm>, memcpy in <cstring>

wchar_t* memmove(wchar_t* dst, const wchar_t* src, size_t n)

The wmemmove function copies n wide characters from src to dst. The memory regions can overlap. The return value is dst.

See Also

wcscpy function, wcsncpy function, wmemcpy function, copy in <algorithm>, copy_backward in <algorithm>, memmove in <cstring>

wchar_t* wmemset(wchar_t* str, wchar_t wc, size_t n)

The wmemset function fills the array str with n copies of the wide character wc. The return value is str.

See Also

wmemcpy function, fill_n in <algorithm>, memset in <cstring>

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

The wprintf function is similar to printf in <cstdio>, except it prints wide characters, and the format parameter is a wide string.

See Also

wfprintf function, wsprintf function, wvprintf function, printf in <cstdio>

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

The wscanf function is similar to scanf in <cstdio>, except it reads wide characters, and the format parameter is a wide string.

See Also

wfscanf function, wsscanf function, scanf in <cstdio>