wcstombs, wcstombs_s

size_t wcstombs( char* dst, const wchar_t* src, size_t len );

size_t wcstombs( char* restrict dst, const wchar_t* restrict src, size_t len );

errno_t wcstombs_s( size_t* restrict retval, char* restrict dst, rsize_t dstsz,
                    const wchar_t* restrict src, rsize_t len );

• Нулевой символ L'\0' был преобразован и сохранён. В этом случае записанные байты представляют собой последовательность сброса (если она необходима), за которой следует '\0',
• Обнаружен wchar_t, не соответствующий допустимому символу в текущей локали C.
• Следующий многобайтовый символ, который нужно сохранить, превысит len.

• преобразование выполняется так, как если бы была вызвана 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 не является нулевым указателем)
• dstsz не равно нулю (если только dst не является нулевым указателем)
• len больше dstsz, и преобразование не встречает нулевой символ или ошибку кодирования в массиве src к моменту достижения dstsz (если только dst не является нулевым указателем)

Примечания

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

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

Параметры

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

Пример

#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

См. также