function
<cuchar>
mbrtoc32
size_t mbrtoc32 ( char32_t * pc32, const char * pmb, size_t max, mbstate_t * ps);
Convert multibyte sequence to 32-bit character
The multibyte character pointed by pmb is converted to a 32-bit character and stored at the location pointed by pc32. The function returns the length in bytes of the multibyte character (up to max).
If the __STD_UTF_32__ macro is defined, the resulting character stored at pc32 follows UTF-32 encoding.
The function uses (and updates) the shift state described by ps. If ps is a null pointer, the function uses its own internal shift state, which is altered as necessary only by calls to this function.
If the character obtained is equivalent to the null 32-bit character, the function resets the shift state and returns zero (after storing the null 32-bit character at pc32).
A call to the function with a null pointer as pmb also resets the shift state, ignoring parameters pc32 and max (no character is stored at pc32).
This is the char32_t version of mbrtowc (<cwchar>).
Parameters
- pc32
- Pointer to an object of type char32_t.
Alternativelly, this argument can be a null pointer, in which case the function does not store the char32_t translation, but still returns the length in bytes of the character.
- pmb
- Pointer to the first byte of a multibyte character.
Alternativelly, the function may be called with a null pointer, in which case the function resets the shift state (either ps or its own internal state) to the initial state and returns zero.
- max
- Maximum number of bytes to read from pmb.
The macro constant MB_CUR_MAX defines the maximum number of bytes that can form a multibyte character under the current locale settings.
size_t is an unsigned integral type.
- ps
- Pointer to a mbstate_t object that defines a conversion state.
Return Value
The number of bytes from pmb used to produce the 32-bit character.
If this was the null 32-bit character, or if pmb is a null pointer, the function returns zero (in the first case, the null 32-bit character is stored at pc32).
If the multibyte sequence needs more than one char32_t to be represented (which not possible on UTF-32) and not all have yet been stored, the function returns (size_t)-3 after storing the appropriate shift character at pc32. The next call to this function with the same ps argument pointing to the same address as pmb shall produce the next character in the sequence of char32_t characters needed to represent the multibyte sequence.
If the max first characters of pmb form an incomplete (but potentially valid) multibyte character, the function returns (size_t)-2 (no value is stored at pc32).
Otherwise, if the characters pointed by pmb do not form a valid multibyte character (or the beginning of one), the function returns (size_t)-1 and sets errno to EILSEQ (no value is stored at pc32).
Notice that size_t is an unsigned integral type, and thus none of the values possibly returned is less than zero.
See also
- c32rtomb
- Convert 32-bit character to multibyte sequence (function
)
- mbrtoc16
- Convert multibyte sequence to 16-bit character (function
)
- mbrtowc
- Convert multibyte sequence to wide character (function
)