c16rtomb, c32rtomb Subroutine

Purpose

The c16rtomb and c32rtomb subroutines convert 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 c16rtomb (char * restrict s,  char16_t c16,
 mbstate_t * restrict ps);

size_t c32rtomb (char * restrict s,  char32_t c32,
 mbstate_t * restrict ps);

Description

If the value of the s parameter is a null pointer, the c16rtomb subroutine is equivalent to the following call, where buf is an internal buffer.
c16rtomb(buf, L'\0', ps)

If the value of the s parameter is not a null pointer, the c16rtomb subroutine determines the number of bytes needed to represent the multibyte character that corresponds to the wide character specified by the c16 parameter, including any shift sequences, and stores the multibyte character representation in an array, in which the first element is specified by the s parameter.

The value greater than the value of MB_CUR_MAX bytes is stored.

If the value of the c16 parameter is a null wide character, a null byte is stored, preceded by any shift sequence that is needed to restore the initial shift state and the resulting state is described is the initial conversion state.

If the value of the s parameter is a null pointer, the c32rtomb subroutine is equivalent to the following call, where buf is an internal buffer.
c32rtomb(buf, L'\0', ps)

If the value of the s parameter is not a null pointer, the c32rtomb subroutine determines the number of bytes needed to represent the multibyte character that corresponds to the wide character specified by the c32 parameter, including any shift sequences, and stores the multibyte character representation in an array, in which the first element is specified by the s parameter.

The value greater than the value of MB_CUR_MAX bytes is stored. If the value of the c32 parameter is a null wide character, a null byte is stored, preceded by any shift sequence that is needed to restore the initial shift state and the resulting state is described is the initial conversion state.

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

Parameters

Item Description
s Specifies the first element of an array where the multibyte character representation is stored.
c16, c32 Represents the wide character sequence.
ps Specifies the state of the multibyte conversion.

Example

  • The mbstate_t pointer can be used as follows: 
     mbstate_t ss = 0;
    int x = c16rtomb(out, in, &ss);

Return Values

The c16rtomb subroutine returns the number of bytes stored in an array object, including any shift sequences.

When the value of the c16 parameter is not a valid wide character, an encoding error occurs. The function stores the value of the EILSEQ macro in the errno variable and returns the (size_t)(-1). The conversion state is unspecified.

The c32rtomb subroutine returns the number of bytes stored in an array object, including any shift sequences.

When the value of the c32 parameter is not a valid wide character, an encoding error occurs. The function stores the value of the EILSEQ macro in the errno variable and returns (size_t)(-1). The conversion state is unspecified.

Error codes

The c16rtomb and c32rtomb subroutine is 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.