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>