wcrtomb, wcrtomb_s

Определено в заголовочном файле <wchar.h>

Определено в заголовочном файле `<wchar.h>`
size_t wcrtomb( char* s, wchar_t wc, mbstate_t* ps);	(1)	(начиная с C95) (до C99 включительно)
size_t wcrtomb( char* restrict s, wchar_t wc, mbstate_t* restrict ps);		(начиная с C99)
errno_t wcrtomb_s(size_t* restrict retval, char* restrict s, rsize_t ssz, wchar_t wc, mbstate_t* restrict ps);	(2)	(начиная с C11)

size_t wcrtomb( char* s, wchar_t wc, mbstate_t* ps);

(1)

(начиная с C95)
(до C99 включительно)

size_t wcrtomb( char* restrict s, wchar_t wc, mbstate_t* restrict ps);

(начиная с C99)

errno_t wcrtomb_s(size_t* restrict retval, char* restrict s, rsize_t ssz,
                  wchar_t wc, mbstate_t* restrict ps);

(2)

(начиная с C11)

Преобразует широкий символ в его узкое многобайтовое представление.

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

Если s является нулевым указателем, вызов эквивалентен wcrtomb(buf, L'\0', ps) для некоторого внутреннего буфера buf.

Если wc является нулевым широким символом L'\0', записывается нулевой байт, которому предшествует любая последовательность переключения состояния, необходимая для восстановления исходного состояния переключения, а параметр состояния преобразования *ps обновляется, чтобы представлять исходное состояние переключения.

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

2) То же, что и (1), за исключением следующего:

если s является нулевым указателем, вызов эквивалентен wcrtomb_s(&retval, buf, sizeof buf, L'\0', ps) с внутренними переменными retval и buf (размер которой больше MB_CUR_MAX)

результат возвращается через выходной параметр retval

во время выполнения обнаруживаются следующие ошибки, и вызывается установленная в данный момент функция обработчика ограничений:

retval или ps является нулевым указателем.
ssz равно нулю или больше RSIZE_MAX (если только s не является нулевым указателем)
ssz меньше количества байтов, которые были бы записаны (если только s не является нулевым указателем)
s является нулевым указателем, но ssz не равно нулю

Как и для всех функций с проверкой границ, доступность wcrtomb_s гарантируется только в том случае, если реализация определяет __STDC_LIB_EXT1__ и пользователь задаёт __STDC_WANT_LIB_EXT1__ равным целочисленной константе 1 до включения <wchar.h>.

Параметры

s	-	указатель на массив узких символов, в котором будет сохранён многобайтовый символ
wc	-	широкий символ для преобразования
ps	-	указатель на объект состояния преобразования, используемый при интерпретации многобайтовой строки
ssz	-	максимальное количество байтов для записи (размер буфера `s`)
retval	-	указатель на выходной параметр, в который будет записан результат (количество байтов в многобайтовой строке, включая любые последовательности переключения состояния)

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

1) В случае успеха возвращает количество байтов (включая любые последовательности переключения состояния), записанных в массив символов, на первый элемент которого указывает s.

В случае ошибки (если wc не является допустимым широким символом) возвращает (size_t)-1, сохраняет EILSEQ в errno и оставляет *ps в неопределённом состоянии.

2) В случае успеха возвращает ноль, а в случае ошибки — ненулевое значение; при этом s[0] устанавливается в '\0' (если только s не является нулевым указателем и ssz не равно нулю и не больше RSIZE_MAX), а *retval устанавливается в (size_t)-1 (если только retval не является нулевым указателем)

Пример

#include <locale.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <wchar.h>

int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    mbstate_t state;
    memset(&state, 0, sizeof state);
    wchar_t in[] = L"zß水🍌"; // or "z\u00df\u6c34\U0001F34C"
    size_t in_sz = sizeof in / sizeof *in;
 
    printf("Processing %zu wchar_t units: [ ", in_sz);
    for (size_t n = 0; n < in_sz; ++n)
        printf("%#x ", (unsigned int)in[n]);
    puts("]");
 
    char out[MB_CUR_MAX * in_sz];
    char* p = out;
    for (size_t n = 0; n < in_sz; ++n)
    {
        int rc = wcrtomb(p, in[n], &state);
        if (rc == -1)
            break;
        p += rc;
    }
 
    size_t out_sz = p - out;
    printf("into %zu UTF-8 code units: [ ", out_sz);
    for (size_t x = 0; x < out_sz; ++x)
        printf("%#x ", +(unsigned char)out[x]);
    puts("]");
}

Вывод:

Processing 5 wchar_t units: [ 0x7a 0xdf 0x6c34 0x1f34c 0 ]
into 11 UTF-8 code units: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c 0 ]

Ссылки

Стандарт C23 (ISO/IEC 9899:2024):

7.29.6.3.3 Функция wcrtomb (стр.: TBD)
K.3.9.3.1.1 Функция wcrtomb_s (стр.: TBD)

Стандарт C17 (ISO/IEC 9899:2018):

7.29.6.3.3 Функция wcrtomb (стр.: TBD)
K.3.9.3.1.1 Функция wcrtomb_s (стр.: TBD)

Стандарт C11 (ISO/IEC 9899:2011):

7.29.6.3.3 Функция wcrtomb (стр.: 444)
K.3.9.3.1.1 Функция wcrtomb_s (стр.: 647-648)

Стандарт C99 (ISO/IEC 9899:1999):

7.24.6.3.3 Функция wcrtomb (стр.: 390)

См. также

wctombwctomb_s (C11)	преобразует широкий символ в его многобайтовое представление (функция)
mbrtowc (C95)	преобразует следующий многобайтовый символ в широкий символ с учётом состояния (функция)
Документация по C++ для `wcrtomb`

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/c/string/multibyte/wcrtomb