View source for c/string/multibyte

{{title|Null-terminated multibyte strings}}
{{c/string/multibyte/navbar}}

A null-terminated multibyte string (NTMBS), or "multibyte string", is a sequence of nonzero bytes followed by a byte with value zero (the terminating null character).

Each character stored in the string may occupy more than one byte. The encoding used to represent characters in a multibyte character string is locale-specific: it may be UTF-8, GB18030, EUC-JP, Shift-JIS, etc. For example, the char array {{c|{'\xe4','\xbd','\xa0','\xe5','\xa5','\xbd','\0'}}} is an NTMBS holding the string {{c|"你好"}} in UTF-8 multibyte encoding: the first three bytes encode the character 你, the next three bytes encode the character 好. The same string encoded in GB18030 is the char array {{c|{'\xc4', '\xe3', '\xba', '\xc3', '\0'}}}, where each of the two characters is encoded as a two-byte sequence.

In some multibyte encodings, any given multibyte character sequence may represent different characters depending on the previous byte sequences, known as "shift sequences". Such encodings are known as state-dependent: knowledge of the current shift state is required to interpret each character. An NTMBS is only valid if it begins and ends in the initial shift state: if a shift sequence was used, the corresponding unshift sequence has to be present before the terminating null character. Examples of such encodings are BOCU-1 and [http://www.unicode.org/reports/tr6 SCSU].

A multibyte character string is layout-compatible with [[c/string/byte|null-terminated byte string]] (NTBS), that is, can be stored, copied, and examined using the same facilities, except for calculating the number of characters. If the correct locale is in effect, I/O functions also handle multibyte strings. Multibyte strings can be converted to and from wide strings using the following locale-dependent conversion functions:

===Multibyte/wide character conversions===
{{dsc begin}}
{{dsc header | stdlib.h}}
{{dsc inc | c/string/multibyte/dsc mblen}}
{{dsc inc | c/string/multibyte/dsc mbtowc}}
{{dsc inc | c/string/multibyte/dsc wctomb}}
{{dsc inc | c/string/multibyte/dsc mbstowcs}}
{{dsc inc | c/string/multibyte/dsc wcstombs}}
{{dsc header | wchar.h}}
{{dsc inc | c/string/multibyte/dsc mbsinit}}
{{dsc inc | c/string/multibyte/dsc btowc}}
{{dsc inc | c/string/multibyte/dsc wctob}}
{{dsc inc | c/string/multibyte/dsc mbrlen}}
{{dsc inc | c/string/multibyte/dsc mbrtowc}}
{{dsc inc | c/string/multibyte/dsc wcrtomb}}
{{dsc inc | c/string/multibyte/dsc mbsrtowcs}}
{{dsc inc | c/string/multibyte/dsc wcsrtombs}}
{{dsc header | uchar.h}}
{{dsc inc | c/string/multibyte/dsc mbrtoc8}}
{{dsc inc | c/string/multibyte/dsc c8rtomb}}
{{dsc inc | c/string/multibyte/dsc mbrtoc16}}
{{dsc inc | c/string/multibyte/dsc c16rtomb}}
{{dsc inc | c/string/multibyte/dsc mbrtoc32}}
{{dsc inc | c/string/multibyte/dsc c32rtomb}}
{{dsc end}}

===Types===
{{dsc begin}}
{{dsc header | wchar.h}}
{{dsc inc | c/string/multibyte/dsc mbstate_t}}
{{dsc header | uchar.h}}
{{dsc inc | c/string/multibyte/dsc char8_t}}
{{dsc inc | c/string/multibyte/dsc char16_t}}
{{dsc inc | c/string/multibyte/dsc char32_t}}
{{dsc end}}

===Macros===
{{dsc begin}}
{{dsc header | limits.h}}
{{dsc inc | c/string/multibyte/dsc MB_LEN_MAX}}
{{dsc header | stdlib.h}}
{{dsc inc | c/string/multibyte/dsc MB_CUR_MAX}}
{{dsc end}}

===References===
{{ref std c11}}
{{ref std | section=7.10    | title=Sizes of integer types <limits.h>| p=222}}
{{ref std | section=7.22    | title=General utilities <stdlib.h> | p=340-360}}
{{ref std | section=7.28    | title=Unicode utilities <uchar.h> | p=398-401}}
{{ref std | section=7.29    | title=Extended multibyte and wide character utilities <wchar.h> | p=402-446}}
{{ref std | section=7.31.12 | title=General utilities <stdlib.h> | p=456}}
{{ref std | section=7.31.16 | title=Extended multibyte and wide character utilities <wchar.h> | p=456}}
{{ref std | section=K.3.6   | title=General utilities <stdlib.h> | p=604-614}}
{{ref std | section=K.3.9   | title=Extended multibyte and wide character utilities <wchar.h> | p=627-651}}
{{ref std c99}}
{{ref std | section=7.10    | title=Sizes of integer types <limits.h>| p=203}}
{{ref std | section=7.20    | title=General utilities <stdlib.h> | p=306-324}}
{{ref std | section=7.24    | title=Extended multibyte and wide character utilities <wchar.h> | p=348-392}}
{{ref std | section=7.26.10 | title=General utilities <stdlib.h> | p=402}}
{{ref std | section=7.26.12 | title=Extended multibyte and wide character utilities <wchar.h> | p=402}}
{{ref std c89}}
{{ref std | section=4.1.4  | title=Limits <float.h> and <limits.h>}}
{{ref std | section=4.10   | title=GENERAL UTILITIES <stdlib.h>}}
{{ref std | section=4.13.7 | title=General utilities <stdlib.h>}}
{{ref std end}}

===See also===
{{dsc begin}}
{{dsc see cpp | cpp/string/multibyte | Null-terminated multibyte strings}}
{{dsc end}}

[[ar:c/string/multibyte]]
[[cs:c/string/multibyte]]
[[de:c/string/multibyte]]
[[es:c/string/multibyte]]
[[fr:c/string/multibyte]]
[[it:c/string/multibyte]]
[[ja:c/string/multibyte]]
[[ko:c/string/multibyte]]
[[pl:c/string/multibyte]]
[[pt:c/string/multibyte]]
[[ru:c/string/multibyte]]
[[tr:c/string/multibyte]]
[[zh:c/string/multibyte]]