function
<cuchar>
mbrtoc16
size_t mbrtoc16 ( char16_t * pc16, const char * pmb, size_t max, mbstate_t * ps);
Convert multibyte sequence to 16-bit character
The multibyte character pointed by pmb is converted to a 16-bit character and stored at the location pointed by pc16. The function returns the length in bytes of the multibyte character (up to max).
If the __STD_UTF_16__ macro is defined, the resulting character stored at pc16 follows UTF-16 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 16-bit character, the function resets the shift state and returns zero (after storing the null 16-bit character at pc16).
A call to the function with a null pointer as pmb also resets the shift state, ignoring parameters pc16 and max (no character is stored at pc16).
This is the char16_t version of mbrtowc (<cwchar>).
Parameters
- pc16
- Pointer to an object of type char16_t.
Alternativelly, this argument can be a null pointer, in which case the function does not store the char16_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 16-bit character.
If this was the null 16-bit character, or if pmb is a null pointer, the function returns zero (in the first case, the null 16-bit character is stored at pc16).
If the multibyte sequence needs more than one char16_t to be represented and not all have yet been stored, the function returns (size_t)-3 after storing the appropriate shift character at pc16. 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 char16_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 pc16).
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 pc16).
Notice that size_t is an unsigned integral type, and thus none of the values possibly returned is less than zero.
See also
- c16rtomb
- Convert 16-bit character to multibyte sequence (function
)
- mbrtoc32
- Convert multibyte sequence to 32-bit character (function
)
- mbrtowc
- Convert multibyte sequence to wide character (function
)