Skip to content
Tutorials Center
My learning

Topics

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.

C
#include <wchar.h>

wchar_t name[] = L"naΓ―ve";
size_t length = wcslen(name);          /* counts wide characters, not bytes */

Try it

C Wide strings, conversion and character classes

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.

C Stream orientation: do not mix printf and wprintf

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

C
#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 printf and wprintf on stdout; pick one for the whole program.
  • wchar_t is not "Unicode characters" everywhere. Windows uses 16 bits, so a code point outside the Basic Multilingual Plane takes two units and wcslen counts those units. A "character" the user sees can also span several code points (accents, emoji sequences).
  • %ls and %lc in printf convert wide data to multibyte output while keeping the stream byte-oriented. That is often the simplest bridge: printf("%ls\n", wide).
  • Use wint_t, not wchar_t, for the classification functions. They accept WEOF, and the cast avoids sign problems.
  • Wide string literals. L"text" has type wchar_t[]. For 16/32-bit encoding-specific text prefer u"..." and U"..." and the types in uchar.h.
  • Cost. Wide strings use 2 to 4 times the memory of ASCII text; wcs functions are as fast as str functions per element. UTF-8 in char is 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.