7.24.6 Extended multibyte/wide character conversion utilities

• 7.24.6.1 Single-byte/wide character conversion functions
  • 7.24.6.1.1 The btowc function
  • 7.24.6.1.2 The wctob function
• 7.24.6.2 Conversion state functions
  • 7.24.6.2.1 The mbsinit function
• 7.24.6.3 Restartable multibyte/wide character conversion functions
  • 7.24.6.3.1 The mbrlen function
  • 7.24.6.3.2 The mbrtowc function
  • 7.24.6.3.3 The wcrtomb function
• 7.24.6.4 Restartable multibyte/wide string conversion functions
  • 7.24.6.4.1 The mbsrtowcs function
  • 7.24.6.4.2 The wcsrtombs function

1

The header <wchar.h> declares an extended set of functions useful for conversion between multibyte characters and wide characters.

2

Most of the following functions – those that are listed as “restartable”, 7.24.6.3 and 7.24.6.4 – take as a last argument a pointer to an object of type mbstate_t that is used to describe the current conversion state from a particular multibyte character sequence to a wide character sequence (or the reverse) under the rules of a particular setting for the LC_CTYPE category of the current locale.

3

The initial conversion state corresponds, for a conversion in either direction, to the beginning of a new multibyte character in the initial shift state. A zero-valued mbstate_t object is (at least) one way to describe an initial conversion state. A zero- valued mbstate_t object can be used to initiate conversion involving any multibyte character sequence, in any LC_CTYPE category setting. If an mbstate_t object has been altered by any of the functions described in this subclause, and is then used with a different multibyte character sequence, or in the other conversion direction, or with a different LC_CTYPE category setting than on earlier function calls, the behavior is undefined.[1]

4

On entry, each function takes the described conversion state (either internal or pointed to by an argument) as current. The conversion state described by the pointed-to object is altered as needed to track the shift state, and the position within a multibyte character, for the associated multibyte character sequence.

Footnotes

[1]

Thus, a particular mbstate_t object can be used, for example, with both the mbrtowc and mbsrtowcs functions as long as they are used to step sequentially through the same multibyte character string.