The <cwchar> header is a wrapper for 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>, <cstdlib>, and <cstring>.
You can use narrow (byte-oriented) I/O functions, as declared in <cstdio>, or wide I/O function, as declarared 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).
Refer to Chapter 1 for more information about character sets, or Chapter 10 for general information about I/O, including I/O of multibyte characters.
Convert a wide character to a single multibyte character
wint_t btowc(int c)
The btowc function returns a wide character representation of c, which is a single byte of a multibyte character (as an unsigned char). If c is not a valid one-byte multibyte character, or if c is EOF, WEOF is returned.
wctob function, WEOF macro
Read a wide character
wint_t fgetwc(FILE* stream)
The fgetwc function reads the next wide character from stream, and returns the character or WEOF for end of file or error.
fgetws function, fputwc function, fgetc in <cstdio>
Read a wide string
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 new line 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 NULL for end of file or error.
fgetwc function, fputws function, fgets in <cstdio>
Print a wide character
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.
fgetwc function, fputc in <cstdio>
Print a wide string
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.
fgetws function, fputwc function, fputs in <cstdio>
Get or set stream orientation
int fwide(FILE* stream, int mode);
The fwide function sets or gets 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 is 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 is an error. The only way to alter orientation is to call freopen (because a newly opened stream has no orientation) or fwide.
If mode is positive, the orientation is set to wide. If mode is negative, the orientation is set to narrow. If mode is zero, the orientation is unchanged. The return value is the new orientation: positive for wide, negative for narrow, or zero if the stream has no orientation.
fopen in <cstdio>, freopen in <cstdio>
Formatted output
int fwprintf(FILE* stream, const wchar_t* format, ...)
The fwprintf function prints wide output to stream, formatted according to the conversion specifiers in format. See fprintf for more information.
fprintf in <cstdio>
Formatted input
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 for more information.
fscanf in <cstdio>
Read a wide character
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 error.
fgetwc function, getc in <cstdio>
Read a wide character
wint_t getwchar()
The getwchar macro is equivalent to getwc(stdin).
getwc function, getchar in <cstdio>
Number of bytes in a multibyte character
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.
If ps is not NULL, it points to the multibyte shift state for str. It ps is NULL, an internal shift state is used (which is similar to calling mblen).
The return value is one of the following:
static_cast<size_t>(-1)str does not point to a valid multibyte character static_cast<size_t>(-2)n is too smallmbrtowc function, mblen in <cstdlib>
Convert a multibyte character to a wide character
size_t mbrtowc(wchar_t* pwc, 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. If str points to a valid multibyte character, that character is converted to a wide character, which is stored in *pwc.
If ps is not NULL, it points to the multibyte shift state for str. It ps is NULL, an internal shift state is used (which is similar to calling mblen).
The return value is one of the following:
static_cast<size_t>(-1)str does not point to a valid multibyte character static_cast<size_t>(-2)n is too smallmbtowc in <cstdlib>
Determines whether a state is the initial shift state
int mbsinit(const mbstate_t* ps)
The mbsinit function returns true (non-zero) is ps is NULL or it points an mbstate_t object that is in the initial shift state; otherwise it returns false (zero).
mbstate_t type
Convert a multibyte string to a wide string
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 str parameter indirectly points to the null-terminated multibyte string.
If dst is not NULL, up to n wide characters are stored in dst. If fewer than n 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 ps parameter points to the conversion state.
The return value is the number of wide characters stored in dst. If any multibyte character is not valid, the return value is static_cast<size_t>(-1).
mbrtowc function, mbstowcs in <cstdlib>
Represent a multibyte shift state
typedef ... mbstate_t
The mbstate_t type is an opaque (not an array) type that stores the conversion state, used to convert between multibyte and wide characters.
A zero value 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, call memset to fill it with zero values, e.g.,
std::mbstate_t mbs; std::memset(&mbs, sizeof(mbs), 0);
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.
mbrlen function, mbrtowc function, mbsinit function, mbsrtowcs function, wcrtomb function, wcsrtombs function
NULL pointer
#define NULL 0
The NULL macro expands to the integer 0, which represents a null pointer.
NULL in <cstddef>
Print a wide character
wint_t putwc(wchar_t wc, FILE* stream)
The putwc macro prints the wide character wc. The return value is the character converted to wint_t or WEOF for an error.
fputwc function, putc in <cstdio>
Print a wide character to stdout
wint_t putwchar(wchar_t wc)
The putwchar macro is equivalent to puwc(wc, stdout).
putchar in <cstdio>
Size type
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.
size_t in <cstddef>
Represent the parts of a date and time
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 the <ctime> section for details.
tm struct in <ctime>
Formatted output to a wide string
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) 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.
fwprintf function, vswprintf function, sprintf in <cstdio>
Formatted read from a wide string
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.
fwscanf function, sscanf in <cstdio>
Push back a wide character
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. Only one wide character of push back is guaranteed, although more than one wide character might work.
The return value is wc or WEOF for an error.
fgetwc function, getwc function, ungetc in <cstdio>
Formatted output
int vfwprintf(FILE* stream, const wchar_t* format,
va_list arg)
The vfwprintf function is similar to vfprintf, except it prints wide characters to stream, and the format parameter is a wide string.
vfprintf in <cstdio>, <cstdarg>
Formatted output to a wide string
int vswprintf(wchar_t* dst, size_t n, const wchar_t* format,
va_list arg)
The vswprintf function is similar to vsprintf, 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.
swprintf function, vsprintf in <cstdio>, <cstdarg>
Formatted output
int vwprintf(const wchar_t* format, va_list arg)
The vwprintf function is similar to vprintf, except it prints wide characters to stdout, and the format parameter is a wide string.
wprintf function, vprintf in <cstdio>, <cstdarg>
Largest value of a wide character
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.
WCHAR_MIN macro
Smallest value of a wide character
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.
WCHAR_MAX macro
Convert a wide character to a multibyte character
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 bytes are stored, and the return value is the actual number of bytes written to s. If wc does not have a valid multibyte encoding, static_cast<size_t>(-1) is returned.
If dst is NULL, wcrtomb converts the null wide character using a private, internal buffer, e.g., wcrtomb(buffer, L'\0', ps).
mbrtowc function, wctomb in <cstdlib>
Concatenate wide strings
wchar_t* wcscat(wchar_t* dst, const wchar_t* src)
The wcscat function concatenate src onto the end of dst. The return value is dst.
wcscpy function, wcsncat function, strcat in <cstring>
Search for a wide character in a wide string
const wchar_t* wcschr(const wchar_t* str, wchar_t c)
wchar_t* wcschr( wchar_t* str, wchar_t c)
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, NULL is returned.
wmemchr function, wcscspn function, wcspbrk function, wcsrchr function, wcsspn function, strchr in <cstring>
Compare wide strings
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 zero. Otherwise, the return value is positive if s1 is greater than s2 or negative is s1 in less than s2. If one string is a prefix of the other, the longer string is greater than the shorter string.
wmemcmp function, wcsncmp function, strcmp in <cstring>
Compare wide strings using locale's collation order
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 category of the current locale. The return value is the same as that of wcscmp.
wcscmp function, strcoll in <cstring>, <clocale>
Copy wide strings
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 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.
wmemcpy function, wcsncpy function, strcpy in <cstring>
Count initial characters not in a span set
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.
wcschr function, wcspbrk function, wcsspn function, wcsstr function, strspn in <cstring>
Format a time as a wide string
size_t wcsftime(wchar_t* str, size_t n,
const wchar_t* format, const tm* tmptr)
The wcsftime function is similar to strftime, except it formats the result as a wide string, str, and the format parameter is a wide string.
strftime in <ctime>
Get length of a wide string
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.
strlen in <cstring>
Concatenate wide strings
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. The caller must ensure 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.
wcscat function, strncat in <cstring>
Compare wide strings
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 zero. Otherwise, the return value is positive if s1 is greater than s2 or negative is s1 in less than s2. If one string is a prefix of the other, the longer string is greater than the shorter string.
wcscmp function, strncmp in <cstring>
Copy wide strings
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.
wcscpy function, strncpy in <cstring>
Locate a wide character in a span set
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 NULL.
wcschr function, wcscspn function, wcsspn function, strpbrk in <cstring>
Locate rightmost occurrence of a wide character
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, NULL is returned.
wmemchr function, wcschr function, strrchr in <cstring>
Convert a wide string to a multibyte string
size_t wcsrtombs(char* dst, const wchar_t** src, size_t n,
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, and dst is NULL or it points to the destination buffer. At most n bytes of dst are written to. If the conversion requires fewer than n bytes, a trailing null byte is appended to dst.
If dst is not NULL, *src is assigned a new value: NULL if all characters were converted or a pointer to the address just past the last wide character that was converted successfully.
If any 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 in the multibyte character string (not counting the trailing null byte).
wmbsrtowcs function, wcrtomb function, wcstombs in <cstdlib>
Count characters in a span set
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.
wcschr function, wcscspn function, wcspbrk function, strspn in <cstring>
Find a wide substring
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.
wcschr function, strstr in <cstring>
Convert a wide string to double
double wcstod(const wchar_t* str, wchar_t** end)
The wcstod function converts a wide string to double, similar to the strtod function.
wcstol function, wcstoul function, strtod in <cstdlib>
Tokenize a wide string
wchar_t* wcstok(wchar_t* str, const wchar_t* delimset,
wchar_t** ptr)
The wcstok function is similar to strtok, except it works with wide strings. Another difference is that it is re-entrant, 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. Do not modify ptr between successive calls to wcstok when parsing a single wide string.
wcscspn function, wcspbrk function, wcsspn function, strtok in <cstring>
Convert a wide string to a long integer
long int wcstol(const wchar_t* str, wchar_t** end)
The wcstol function converts a wide string to long int, similar to the strtol function.
wcstod function, wcstoul function, strtol in <cstdlib>
Convert a wide string to an unsigned long integer
unsigned long int wcstoul(const wchar_t* str, wchar_t** end)
The wcstoul function converts a wide string to unsigned long int, similar to the strtoul function.
wcstod function, wcstol function, strtoul in <cstrdlib>
Transform a wide string for collation
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, except it works with wide strings.
wcscmp function, wcscoll function, strxfrm in <cstring>, <clocale>
Convert a wide character to a single byte
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.
btowc function, EOF in <cstdio>
End of file or error
const wint_t WEOF
The WEOF macro in a value that does not correspond to any valid wide character value. Unlike EOF, WEOF is not guaranteed to be negative.
EOF in <cstdio>
Integer representation of a wide character
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.
WEOF macro
Search for a wide character
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 into the mem array of the first occurrence of c, or NULL if c is not present in the first n wide characters of mem.
wcschr function, memchr in <cstring>
Compare wide strings
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 zero. Otherwise, the return value is positive if s1 is greater than s2 or negative is s1 in less than s2.
wcscmp function, wcsncmp function, memcmp in <cstring>
Copy wide strings
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.
wcscpy function, wcsncpy function, wmemmove function, memcpy in <cstring>
Copy overlapping wide strings
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.
wcscpy function, wcsncpy function, wmemcpy function, memmove in <cstring>
Fill a wide string with an integer
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 char wc. The return value is str.
wmemcpy function, memset in <cstring>
Formatted wide output
int wprintf(const wchar_t* format, ...)
The wprintf function is similar to printf, except it prints wide characters, and the format parameter is a wide string.
wfprintf function, wsprintf function, wvprintf function, printf in <cstring>
Formatted wide input
int wscanf(const wchar_t* format, ...)
The wscanf function is similar to scanf, except it reads wide characters, and the format parameter is a wide string.
wfscanf function, wsscanf function, scanf in <cstring>