C Reference Β· ctype.h, math.h and others
C wchar.h: wide characters and strings
Reference for wchar.h and wctype.h: wchar_t, wide string functions like wcslen, wide output with wprintf, converting with mbstowcs and wcstombs, and stream orientation.
A char holds one byte, which is enough for ASCII but not for most of the world's writing systems. C therefore has a second family of text types and functions built around the wide character type wchar_t. A wide string is written L"text", a wide character L'x', and nearly every str... function has a wcs... twin in <wchar.h>: wcslen, wcscpy, wcscmp, wcschr, wcsstr, wcstol and so on. <wctype.h> has the matching classification functions such as iswalpha and towupper.
The size of wchar_t depends on the platform: 32 bits on Linux and macOS (one element per Unicode code point) and 16 bits on Windows (UTF-16, so some characters need two elements). That makes wide characters awkward for portable code; many programs prefer UTF-8 in plain char strings and use wchar_t only at the boundary with the operating system.
#include <wchar.h> wchar_t name[] = L"naΓ―ve"; size_t length = wcslen(name); /* counts wide characters, not bytes */
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input Β· what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input Β· what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Syntax
#include <wchar.h> #include <wctype.h> typedef /* integer */ wchar_t; /* in <stddef.h> too */ typedef /* integer */ wint_t; /* holds any wchar_t value or WEOF */ size_t wcslen(const wchar_t *s); wchar_t *wcscpy(wchar_t *restrict dest, const wchar_t *restrict src); int wcscmp(const wchar_t *a, const wchar_t *b); wchar_t *wcsstr(const wchar_t *haystack, const wchar_t *needle); size_t mbstowcs(wchar_t *restrict dest, const char *restrict src, size_t n); size_t wcstombs(char *restrict dest, const wchar_t *restrict src, size_t n); int wprintf(const wchar_t *format, ...); int fwide(FILE *stream, int mode); wint_t towupper(wint_t wc); int iswalpha(wint_t wc); /* <wctype.h> */
| Name | Description |
|---|---|
wchar_t |
Wide character type; holds one code point on Linux. |
wint_t |
Type large enough for all wchar_t values plus the end marker WEOF; used by getwc, iswalpha, towupper. |
mbstowcs, wcstombs |
Convert between multibyte strings in the current locale's encoding and wide strings. With dest set to NULL, they only count. |
fwide(stream, mode) |
Query (0), or set positive for wide and negative for byte orientation. |
Returns: wcslen returns the number of wide characters before the terminator. mbstowcs and wcstombs return the number converted without the terminator, or (size_t)-1 if an invalid sequence is found. wprintf returns the number of wide characters written, or a negative value on error. fwide returns the orientation after the call.
Errors / undefined behavior: the same buffer rules as for str functions apply: wcscpy does not check sizes, and a missing terminator is undefined. mbstowcs with a destination that is too small stops without a terminator. Using a non-ASCII character with wprintf in the "C" locale sets errno to EILSEQ.
Usage notes
- Locale first. Conversions and output of non-ASCII text work only after
setlocale(LC_CTYPE, ...)selected a suitable encoding, usually UTF-8. In the default"C"locale, only ASCII converts. See locale.h. - Stream orientation is sticky. The first operation on a stream (byte or wide) decides its orientation, and operations of the other kind then fail silently or with an error. Never mix
printfandwprintfonstdout; pick one for the whole program. wchar_tis not "Unicode characters" everywhere. Windows uses 16 bits, so a code point outside the Basic Multilingual Plane takes two units andwcslencounts those units. A "character" the user sees can also span several code points (accents, emoji sequences).%lsand%lcinprintfconvert wide data to multibyte output while keeping the stream byte-oriented. That is often the simplest bridge:printf("%ls\n", wide).- Use
wint_t, notwchar_t, for the classification functions. They acceptWEOF, and the cast avoids sign problems. - Wide string literals.
L"text"has typewchar_t[]. For 16/32-bit encoding-specific text preferu"..."andU"..."and the types in uchar.h. - Cost. Wide strings use 2 to 4 times the memory of ASCII text;
wcsfunctions are as fast asstrfunctions per element. UTF-8 incharis usually more compact and just as easy to pass around if you do not need random access by code point. - Standard version: wide-character functions were added in C95 (an amendment to C89);
<wctype.h>came with them.