C Reference Β· stdlib.h
C multibyte conversion functions
Reference for C multibyte text conversion: mblen(), mbtowc(), mbstowcs(), wcstombs() and the restartable mbrtowc(), with setlocale() and UTF-8 examples.
C strings are arrays of bytes, but human text is made of characters, and in UTF-8 one character can take one to four bytes. The multibyte functions in <stdlib.h> (and the restartable ones in <wchar.h>) translate between the multibyte form (char strings in the current locale's encoding) and the wide form (wchar_t, one value per character).
The main functions are mblen() (how many bytes does the next character use?), mbtowc() and wctomb() (one character), and mbstowcs() and wcstombs() (whole strings). Their behavior depends on the current locale, which a program selects with setlocale().
#include <stdlib.h> int mblen(const char *s, size_t n); size_t mbstowcs(wchar_t *restrict pwcs, const char *restrict s, size_t n);
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
int mblen (const char *s, size_t n); int mbtowc (wchar_t *restrict pwc, const char *restrict s, size_t n); int wctomb (char *s, wchar_t wc); size_t mbstowcs(wchar_t *restrict pwcs, const char *restrict s, size_t n); size_t wcstombs(char *restrict s, const wchar_t *restrict pwcs, size_t n); size_t mbrtowc (wchar_t *restrict pwc, const char *restrict s, size_t n, mbstate_t *restrict ps);
| Name | Description |
|---|---|
s |
The multibyte string (or character). A null s in mblen, mbtowc and wctomb queries whether the encoding has shift states. |
n |
Maximum number of bytes (mblen, mbtowc) or output elements (mbstowcs, wcstombs) to handle. |
pwc, pwcs |
Where the wide character(s) are stored. mbstowcs(NULL, s, 0) only counts. |
ps |
Conversion state for the restartable functions; start with a zeroed mbstate_t. |
Returns: mblen and mbtowc return the number of bytes used, 0 for a null character, and -1 for an invalid sequence. mbstowcs and wcstombs return the number of elements written (not counting the terminator) or (size_t)-1 on an invalid sequence.
Errors / undefined behavior: if the output of mbstowcs or wcstombs does not fit in n, the result is not null-terminated. Passing an invalid pointer is undefined behavior.
Usage notes
- Call
setlocale(LC_ALL, "")or a named locale first. Programs start in the"C"locale, where only single-byte characters are guaranteed to work. Which locale names exist depends on the system;"C.UTF-8"worked on our runner, but check the return value. strlencounts bytes, not characters. Usembstowcs(NULL, s, 0)to count characters; this is the reason these functions matter for text in user interfaces.wchar_tis 32 bits on Linux and 16 bits on Windows, where it holds UTF-16 code units. A single user-perceived "character" can also consist of several code points (combining marks), which these functions do not join.mblenandmbtowckeep hidden state and are not thread-safe. Prefer the restartablembrtowc,wcrtombandmbsrtowcsfrom<wchar.h>in new code.- C11
<uchar.h>addsmbrtoc16,mbrtoc32and the matchingc16rtomb,c32rtombfor UTF-16 and UTF-32 conversion independent of the locale (see<uchar.h>). - Truncation: size the output buffer as
strlen(s) + 1wide characters at most, since one byte never produces more than one wide character. - Printing wide strings needs
%lsinprintforwprintf, and a stream orientation; mixing narrow and wide output on one stream is an error.
Related
<wchar.h>,<uchar.h>,<locale.h>,strlen- Lessons: Strings, Characters