size_t mbrtowc(wchar_t *pc, const char *s, size_t n, mbstate_t *ps);
size_t mbrtoc16(char16_t *pc, const char *s, size_t n, mbstate_t *ps);
size_t mbrtoc32(char32_t *pc, const char *s, size_t n, mbstate_t *ps);
size_t mbrtowc_l(wchar_t *pc, const char *s, size_t n, mbstate_t *ps, locale_t locale);
size_t mbrtoc16_l(char16_t *pc, const char *s, size_t n, mbstate_t *ps, locale_t locale);
size_t mbrtoc32_l(char32_t *pc, const char *s, size_t n, mbstate_t *ps, locale_t locale);
If s is a null pointer,
mbrtowc(NULL, "", 1, ps);
In this case, the values of the arguments pc and n are ignored.
If s is not null, the
If the specified state pointer is null, the
The behavior of
Points to a location to receive the converted wide character. This can be null if no returned wide character is desired.
Is the string whose bytes are to be counted/converted.
Specifies the maximum number of bytes to examine.
Is the conversion state. If this is null, an internal mbstate_t object is used.
If the next n or fewer bytes complete the character that corresponds to the null wide character (which is the value stored).
- positive number
If the next n or fewer bytes complete a valid character (which is the value stored); the value returned is the number of bytes that complete the character.
If the next n bytes contribute to an incomplete by potentially valid character, and all n bytes have been processed (no value is stored). When n has at least the value of MB_CUR_MAX or MB_CUR_MAX_L, this case can only occur if s points at a sequence of redundant shift sequences (for locales with state-dependent encodings).
If an encoding error occurs, in which case the next n or fewer bytes do not contribute to a complete and valid character (no value is stored). In this case, errno is set to EILSEQ, and the conversion state is undefined.
mbrtoc16()and mbrtoc16_l()functions can also return -3. This indicates that the char16_t is incomplete and must be read a second time to recover the state data stored in mbstate_t. No bytes from input have been consumed.
MT-Safe, with exceptions.
The current mbstate_t, for historical reasons, is implemented as an int (4 bytes). This is used internally as 4 multibyte characters. Code that passes one byte at a time to this function will have state problems at bytes 5 and 6 of a UTF-8 sequence. 5 and 6 byte UTF-8 sequnces are uncommon but exist. 4, 5, 6 byte UTF-8 passed as a single string or in two halves will work just fine with the newer char16_t and char32_t functions which have a viable way of representing a UTF-32 and a UTF-16 surrogate pairs (using the -3 return).
Runtime binary compatibility would need to be broken to extend the size of mbstate_t.
PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition
mbrlen(), mbrlen_l(), mbsinit(), mbsinit_l(), mbsrtowcs(), mbsrtowcs_l(), newlocale(), setlocale(), wcrtomb(), wcrtomb_l(), wcsrtombs(), wcsrtombs_l()
PTC MKS Toolkit 10.3 Documentation Build 39.