mbrtoc16, mbrtoc32 Subroutine

Purpose

The mbrtoc16 and mbrtoc32 subroutine converts a 16-bit wide character (UTF-16) and a 32-bit wide character (UTF-32) to the corresponding multibyte character of the current locale.

Library

Standard C library (libc.a)

Syntax

#include <uchar.h>
size_t mbrtoc16 (char16_t * restrict pc16,  const char * restrict s, size_t n, mbstate_t * restrict ps);

size_t mbrtoc32 (char32_t * restrict pc32,  const char * restrict s, size_t n, mbstate_t * restrict ps);

Description

If the value of the s parameter is a null pointer, the mbrtoc16 subroutine is equivalent to the following call:
mbrtoc16(NULL, "", 1, ps).
In this case, the values of the pc16 and n parameters are ignored.

If the value of the s parameter is not a null pointer, the mbrtoc16 subroutine inspects the value of n bytes beginning with the byte specified by the s parameter to determine the number of bytes that is needed to complete the next multibyte character, including any shift sequences.

If the subroutine determines that the next multibyte character is complete and valid, the subroutine determines the values of the corresponding wide characters. If the value of the pc16 subroutine is not a null pointer, the subroutine stores the value of the first character in the object specified by the pc16 parameter.

If the value of the s parameter is a null pointer, the mbrtoc32 subroutine is equivalent to the following call:
mbrtoc32(NULL, "", 1, ps).
In this case, the values of the pc32 and n parameters are ignored.

If the value of the s parameter is not a null pointer, the mbrtoc32 subroutine inspects the greater value of n bytes beginning with the byte specified by the s parameter to determine the number of bytes that is needed to complete the next multibyte character, including any shift sequences.

If the subroutine determines that the next multibyte character is complete and valid, the subroutine determines the values of the corresponding wide characters. If the value of the pc32 subroutine is not a null pointer, the subroutine stores the value of the first character in the object specified by the pc32 parameter.

Subsequent calls will store the successive wide characters without using any additional input until all the characters are stored. If the corresponding wide character is a null wide character, the resulting state that is described is the initial conversion state.

Note: The mbrtoc16 and mbrtoc32 subroutines includes the ps parameter which is of the type pointer to mbstate_t that points to an object which describes the current conversion state of the associated multibyte character sequence, which the subroutines alter as necessary. If ps is a null pointer, each subroutine uses its own internal mbstate_t object. The mbrtoc16 and mbrtoc32 subroutines do not avoid data races with other calls to the same subroutine.

Parameters

Item Description
n Specifies the number of bytes to be examined to determine the next multibyte character.
pc16, pc32 Specifies the location of the first wide character to be stored.
ps Specifies the state of the conversion.
s Specifies the beginning of the bytes that are examined.

Example

  • The mbstate_t pointer can be used as follows: 
     mbstate_t ss = 0;
    int x = mbrtoc16(&c16, mbs, MB_CUR_MAX, &ss);

Return Values

The mbrtoc16 and mbrtoc32 subroutine returns any one of the following values that applies to the current conversion state.
Item Description
0 If the next n or fewer bytes complete the multibyte character that corresponds to the null wide-character (which is the value that is stored) from 1 to n and if the next n or fewer bytes complete a valid multibyte character (which is the value that is stored), the value that is returned is the number of bytes that complete the multibyte character.
(size_t)(-3) If the next character resulting from a previous call has been stored, no bytes from the input is used by this call.
(size_t)(-2) If the next n bytes contribute to an incomplete but a valid multibyte character, and all n bytes are processed, and no value is stored.
(size_t)(-1) If an encoding error occurs, that is the next n or fewer bytes do not contribute to a complete and valid multibyte character (no value is stored), the value of the EILSEQ macro is stored in the errno variable. The conversion state is unspecified.

Error codes

The mbrtoc16 and mbrtoc32 subroutine are unsuccessful if the following error code is set.

Item Description
EILSEQ Indicates an invalid multibyte character sequence.

Files

The uchar.h file defines standard macros, data types, and subroutines.