mbrtoc32

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

Преобразует одиночный код символа из его многобайтового узкого представления в его многобайтовое 32-битное широкое представление (но обычно UTF-32).

Если s не является нулевым указателем, проверяет не более n байтов строки многобайтовых символов, начиная с байта, на который указывает s, чтобы определить количество байтов, необходимое для завершения следующего многобайтового символа (включая любые последовательности смены состояния и учитывая текущее состояние многобайтовой кодировки *ps). Если функция определяет, что следующий многобайтовый символ в s завершён и корректен, преобразует его в соответствующий 32-битный широкий символ и сохраняет его в *pc32 (если pc32 не является нулевым указателем).

Если многобайтовый символ в *s соответствует последовательности многосимвольных значений char32_t (что невозможно с UTF-32), то после первого вызова этой функции *ps обновляется таким образом, что следующие вызовы mbrtoc32 будут записывать дополнительные char32_t, не учитывая *s.

Если s является нулевым указателем, значения n и pc32 игнорируются, и вызов эквивалентен mbrtoc32(NULL, "", 1, ps).

Если полученный широкий символ — это нулевой символ, состояние кодирования *ps представляет начальное состояние смены состояния.

Если макрос __STDC_UTF_32__ определён, 32-битная кодировка, используемая этой функцией, — UTF-32; в противном случае она определяется реализацией. Макрос всегда определён, а кодировка всегда UTF-32.(с C23) В любом случае многобайтовая кодировка, используемая этой функцией, задаётся текущим активным языковым стандартом C.

Параметры

Возвращаемое значение

Первое из следующих, что применимо:

• ​0​ если символ, преобразованный из s (и сохранённый в *pc32 если он не нулевой), был нулевым символом
• количество байтов [1...n] многобайтового символа, успешно преобразованного из s
• (size_t)-3 если следующий char32_t из много-char32_t символьного знака теперь был записан в *pc32.
• (size_t)-2 если следующие n байта составляют неполный, но до сих пор допустимый, многобайтовый символ. Ничего не записывается в *pc32.
• (size_t)-1 если произошла ошибка кодирования. Ничего не записывается в *pc32, значение EILSEQ сохраняется в errno, а значение *ps не определено.

Пример

#include <stdio.h>
#include <locale.h>
#include <string.h>
#include <uchar.h>
#include <assert.h>
 
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    char in[] = u8"zß水🍌"; // or "z\u00df\u6c34\U0001F34C"
    const size_t in_size = sizeof in / sizeof *in;
 
    printf("Processing %zu UTF-8 code units: [ ", in_size);
    for (size_t i = 0; i < in_size; ++i)
        printf("0x%02x ", (unsigned char)in[i]);
 
    puts("]");
 
    char32_t out[in_size];
    char32_t *p_out = out;
    char *p_in = in, *end = in + in_size;
    mbstate_t state;
    memset(&state, 0, sizeof(state));
    size_t rc;
    while ((rc = mbrtoc32(p_out, p_in, end - p_in, &state)))
    {
        assert(rc != (size_t)-3); // no surrogate pairs in UTF-32
        if (rc == (size_t)-1) break; // invalid input
        if (rc == (size_t)-2) break; // truncated input
        p_in += rc;
        ++p_out;
    }
 
    size_t out_size = p_out+1 - out;
    printf("into %zu UTF-32 code units: [ ", out_size);
    for (size_t i = 0; i < out_size; ++i)
        printf("0x%08X ", out[i]);
 
    puts("]");
}

Processing 11 UTF-8 code units: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c 0x00 ]
into 5 UTF-32 code units: [ 0x0000007A 0x000000DF 0x00006C34 0x0001F34C 0x00000000 ]

Ссылки

• Стандарт C23 (ISO/IEC 9899:2023):
• 7.30.1.5 Функция mbrtoc32 (стр. 410)
• Стандарт C17 (ISO/IEC 9899:2018):
• 7.28.1.3 Функция mbrtoc32 (стр. 293-294)
• Стандарт C11 (ISO/IEC 9899:2011):
• 7.28.1.3 Функция mbrtoc32 (стр. 400-401)

См. также