Namespaces
Variants

wcstombs, wcstombs_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
Определено в заголовочном файле <stdlib.h>
(1)
size_t wcstombs ( char * dst, const wchar_t * src, size_t len ) ;
(до 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 перекрываются, поведение не определено.
* следующие ошибки обнаруживаются во время выполнения и вызывают текущую установленную constraint handler функцию:
  • retval или src является нулевым указателем
  • dstsz или len больше чем RSIZE_MAX (если только dst не является нулевым)
  • dstsz не равно нулю (если только dst не является нулевым)
  • len больше чем dstsz и преобразование не встречает нулевой символ или ошибку кодирования в массиве src к моменту достижения dstsz (если только dst не является нулевым)
Как и все функции с проверкой границ, 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 не является нулевым указателем) и устанавливает dst [ 0 ] в ' \0 ' (если только dst не является нулевым указателем или dstmax не равен нулю или не больше RSIZE_MAX )

Пример

Запустить этот код 
#include <stdio.h>
#include <stdlib.h>
#include <locale.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

Ссылки

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