Draft 2002-06-14

<cwchar>

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.

btowc function

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.

See Also

wctob function, WEOF macro

fgetwc function

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.

See Also

fgetws function, fputwc function, fgetc in <cstdio>

fgetws function

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.

See Also

fgetwc function, fputws function, fgets in <cstdio>

fputwc function

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.

See Also

fgetwc function, fputc in <cstdio>

fputws function

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.

See Also

fgetws function, fputwc function, fputs in <cstdio>

fwide function

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.

See Also

fopen in <cstdio>, freopen in <cstdio>

fwprintf function

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.

See Also

fprintf in <cstdio>

fwscanf function

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.

See Also

fscanf in <cstdio>

getwc macro

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.

See Also

fgetwc function, getc in <cstdio>

getwchar macro

Read a wide character

wint_t getwchar()

The getwchar macro is equivalent to getwc(stdin).

See Also

getwc function, getchar in <cstdio>

mbrlen function

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:

0
if the multibyte character represents the null wide character.
Positive # of bytes in the multibyte character
if the multibyte character is valid
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

See Also

mbrtowc function, mblen in <cstdlib>

mbrtowc function

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:

0
if the multibyte character represents the null wide character.
Positive # of bytes in the multibyte character
if the multibyte character is valid
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

See Also

mbtowc in <cstdlib>

mbsinit function

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

See Also

mbstate_t type

mbsrtowcs function

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

See Also

mbrtowc function, mbstowcs in <cstdlib>

mbstate_t type

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.

See Also

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

NULL macro

NULL pointer

#define NULL 0

The NULL macro expands to the integer 0, which represents a null pointer.

See Also

NULL in <cstddef>

putwc macro

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.

See Also

fputwc function, putc in <cstdio>

putwchar function

Print a wide character to stdout

wint_t putwchar(wchar_t wc)

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

See Also

putchar in <cstdio>

size_t type

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.

See Also

size_t in <cstddef>

tm struct

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.

See Also

tm struct in <ctime>

swprintf function

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.

See Also

fwprintf function, vswprintf function, sprintf in <cstdio>

swscanf function

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.

See Also

fwscanf function, sscanf in <cstdio>

ungetwc function

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.

See Also

fgetwc function, getwc function, ungetc in <cstdio>

vfwprintf function

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.

See Also

vfprintf in <cstdio>, <cstdarg>

vswprintf function

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.

See Also

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

vwprintf function

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.

See Also

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

WCHAR_MAX macro

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.

See Also

WCHAR_MIN macro

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.

See Also

WCHAR_MAX macro

wcrtomb function

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

See Also

mbrtowc function, wctomb in <cstdlib>

wcscat function

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.

See Also

wcscpy function, wcsncat function, strcat in <cstring>

wcschr function

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.

See Also

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

wcscmp function

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.

See Also

wmemcmp function, wcsncmp function, strcmp in <cstring>

wcscoll function

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.

See Also

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

wcscpy function

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.

See Also

wmemcpy function, wcsncpy function, strcpy in <cstring>

wcscspn function

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.

See Also

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

wcsftime function

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.

See Also

strftime in <ctime>

wcslen function

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.

See Also

strlen in <cstring>

wcsncat function

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.

See Also

wcscat function, strncat in <cstring>

wcsncmp function

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.

See Also

wcscmp function, strncmp in <cstring>

wcsncpy function

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.

See Also

wcscpy function, strncpy in <cstring>

wcspbrk function

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.

See Also

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

wcsrchr function

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.

See Also

wmemchr function, wcschr function, strrchr in <cstring>

wcsrtombs function

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

See Also

wmbsrtowcs function, wcrtomb function, wcstombs in <cstdlib>

wcsspn function

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.

See Also

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

wcsstr function

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.

See Also

wcschr function, strstr in <cstring>

wcstod function

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.

See Also

wcstol function, wcstoul function, strtod in <cstdlib>

wcstok function

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.

See Also

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

wcstol function

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.

See Also

wcstod function, wcstoul function, strtol in <cstdlib>

wcstoul function

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.

See Also

wcstod function, wcstol function, strtoul in <cstrdlib>

wcsxfrm function

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.

See Also

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

wctob function

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.

See Also

btowc function, EOF in <cstdio>

WEOF macro

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.

See Also

EOF in <cstdio>

wint_t type

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.

See Also

WEOF macro

wmemchr function

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.

See Also

wcschr function, memchr in <cstring>

wmemcmp function

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.

See Also

wcscmp function, wcsncmp function, memcmp in <cstring>

wmemcpy function

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.

See Also

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

wmemmove function

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.

See Also

wcscpy function, wcsncpy function, wmemcpy function, memmove in <cstring>

wmemset function

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.

See Also

wmemcpy function, memset in <cstring>

wprintf function

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.

See Also

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

wscanf function

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.

See Also

wfscanf function, wsscanf function, scanf in <cstring>