Namespaces
Variants

wcrtomb, wcrtomb_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
Определено в заголовочном файле <wchar.h>
(1)
size_t wcrtomb ( char * s, wchar_t wc, mbstate_t * ps ) ;
(начиная с C95)
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 <stdio.h>
#include <locale.h>
#include <string.h>
#include <wchar.h>
#include <stdlib.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("Обработка %zu единиц wchar_t: [ ", 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("в %zu единиц UTF-8: [ ", out_sz);
    for(size_t x = 0; x < out_sz; ++x) printf("%#x ", +(unsigned char)out[x]);
    puts("]");
}

Вывод: 

Обработка 5 единиц wchar_t: [ 0x7a 0xdf 0x6c34 0x1f34c 0 ]
в 11 единиц UTF-8: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c 0 ]

Ссылки

  • Стандарт 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)

Смотрите также

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