Namespaces
Variants

    wcstombs, wcstombs_s

    С ru.cppreference.net
     
    C
     
    Библиотека строк
     
    Строки многобайтовых символов, завершающиеся нулевым символом
     
    Определено в заголовке <stdlib.h> 
    size_t wcstombs( char* dst, const wchar_t* src, size_t len );
    		(1) (до C99) 
    size_t wcstombs( char* restrict dst, const wchar_t* restrict src, size_t len );
    		(начиная с C99) 
    errno_t wcstombs_s( size_t* restrict retval, char* restrict dst, rsize_t dstsz,
                    const wchar_t* restrict src, rsize_t len );
    		(2) (начиная с C11)
    1) Преобразует последовательность широких символов из массива, первый элемент которого указывается параметром src, в её узкое многобайтовое представление, начинающееся в начальном состоянии сдвига. Преобразованные символы сохраняются в последовательных элементах массива char, на который указывает dst. В целевой массив записывается не более len байтов.
    Каждый символ преобразуется так, как если бы он был передан функции wctomb, за исключением того, что состояние преобразования wctomb не изменяется. Преобразование прекращается, если:
    • Был преобразован и сохранён нулевой символ L'\0'. В этом случае сохраняемые байты представляют собой последовательность выхода из сдвига (если необходимо), за которой следует '\0',
    • Был найден wchar_t, который не соответствует допустимому символу в текущей локали C.
    • Следующий многобайтовый символ, подлежащий сохранению, превысил бы len.
    Если src и dst перекрываются, поведение не определено.
    2) То же, что и (1), за исключением того, что
    • преобразование выполняется как при вызове wcrtomb, а не wctomb
    • функция возвращает результат через выходной параметр retval
    • если преобразование завершается без записи нулевого символа, функция сохраняет '\0' в следующем байте в dst, который может быть dst[len] или dst[dstsz], в зависимости от того, что наступит раньше (это означает, что всего может быть записано до len+1/dstsz+1 байтов). В этом случае перед завершающим нулём может не быть записано последовательности выхода из сдвига.
    • если dst является нулевым указателем, количество байтов, которое было бы создано, сохраняется в *retval
    • функция затирает целевой массив от завершающего нуля до dstsz
    • Если src и dst перекрываются, поведение не определено.
    • следующие ошибки обнаруживаются во время выполнения и вызывают текущую установленную функцию обработчика ограничений:
    • retval или src является нулевым указателем
    • dstsz или len больше RSIZE_MAX (если только dst не равен null)
    • dstsz не равно нулю (если только dst не равен null)
    • len больше dstsz и преобразование не встречает нулевой символ или ошибку кодирования в массиве src к моменту достижения dstsz (если только dst не равен null)
    Как и для всех функций с проверкой границ, wcstombs_s гарантированно доступна только в том случае, если __STDC_LIB_EXT1__ определён реализацией и пользователь определяет __STDC_WANT_LIB_EXT1__ как целочисленную константу 1 перед включением <stdlib.h>.

    Примечания

    В большинстве реализаций wcstombs обновляет глобальный статический объект типа mbstate_t по мере обработки строки, и не может вызываться одновременно двумя потоками; в таких случаях следует использовать wcsrtombs или wcstombs_s.

    POSIX определяет распространённое расширение: если dst является нулевым указателем, эта функция возвращает количество байтов, которое было бы записано в dst при преобразовании. Аналогичное поведение является стандартным для wcsrtombs и wcstombs_s.

    Параметры

    dst - указатель на массив узких символов, в который будет сохранён многобайтовый символ
    src - указатель на первый элемент широкой строки, завершающейся нулевым символом, для преобразования
    len - количество байтов, доступных в массиве, на который указывает dst
    dstsz - максимальное количество байтов, которое будет записано (размер массива dst)
    retval - указатель на объект size_t, в который будет сохранён результат

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

    1) В случае успеха возвращает количество байтов (включая любые последовательности сдвига, но исключая завершающий '\0'), записанных в массив символов, на первый элемент которого указывает dst. В случае ошибки преобразования (если встречен недопустимый широкий символ) возвращает (size_t)-1.
    2) Возвращает ноль в случае успеха (при этом количество байтов, исключая завершающий ноль, которые были или будут записаны в dst, сохраняется в *retval), ненулевое значение при ошибке. В случае нарушения ограничения времени выполнения сохраняет (size_t)-1 в *retval (если только retval не равен null) и устанавливает dst[0] в '\0' (если только dst не равен null или dstmax не равно нулю или больше RSIZE_MAX)

    Пример

    Запустить этот код
    #include <locale.h>
#include <stdio.h>
#include <stdlib.h>

int main(void)
{
    // 4 wide characters
    const wchar_t src[] = L"z\u00df\u6c34\U0001f34c";
    // they occupy 10 bytes in UTF-8
    char dst[11];

    setlocale(LC_ALL, "en_US.utf8");
    printf("wide-character string: '%ls'\n",src);
    for (size_t ndx = 0; ndx < sizeof src / sizeof src[0]; ++ndx)
        printf("   src[%2zu] = %#8x\n", ndx, src[ndx]);
    
    int rtn_val = wcstombs(dst, src, sizeof dst);
    printf("rtn_val = %d\n", rtn_val);
    if (rtn_val > 0)
        printf("multibyte string:  '%s'\n",dst);
    for (size_t ndx = 0; ndx < sizeof dst; ++ndx)
        printf("   dst[%2zu] = %#2x\n", ndx, (unsigned char)dst[ndx]);
}

    Вывод: 

    wide-character string: 'zß水🍌'
   src[ 0] =     0x7a
   src[ 1] =     0xdf
   src[ 2] =   0x6c34
   src[ 3] =  0x1f34c
   src[ 4] =        0
rtn_val = 10
multibyte string:  'zß水🍌'
   dst[ 0] = 0x7a
   dst[ 1] = 0xc3
   dst[ 2] = 0x9f
   dst[ 3] = 0xe6
   dst[ 4] = 0xb0
   dst[ 5] = 0xb4
   dst[ 6] = 0xf0
   dst[ 7] = 0x9f
   dst[ 8] = 0x8d
   dst[ 9] = 0x8c
   dst[10] =  0

    Ссылки

    • Стандарт C23 (ISO/IEC 9899:2024):
    • 7.22.8.2 Функция wcstombs (стр.: TBD)
    • K.3.6.5.2 Функция wcstombs_s (стр.: TBD)
    • Стандарт C17 (ISO/IEC 9899:2018):
    • 7.22.8.2 Функция wcstombs (стр.: TBD)
    • K.3.6.5.2 Функция wcstombs_s (стр.: TBD)
    • Стандарт C11 (ISO/IEC 9899:2011):
    • 7.22.8.2 Функция wcstombs (стр.: 360)
    • K.3.6.5.2 Функция wcstombs_s (стр.: 612-614)
    • Стандарт C99 (ISO/IEC 9899:1999):
    • 7.20.8.2 Функция wcstombs (стр.: 324)
    • Стандарт C89/C90 (ISO/IEC 9899:1990):
    • 4.10.8.2 Функция wcstombs

    См. также

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