MBSTOWCS(3)

ИМЯ
mbstowcs - преобразует многобайтовую строку в строку широких символов

ОБЗОР
#include <stdlib.h>

size_t mbstowcs(wchar_t *dest, const char *src, size_t n);

ОПИСАНИЕ
Если значение dest не равно NULL, то функция mbstowcs() преобразует многобайтовую строку src в широкосимвольную строку начиная с dest. В dest будет записано не более n широких символов. Последовательность символов в строке src должна начинаться с начального состояния. Преобразование может прекратиться по трём причинам:

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

2.  В dest было сохранено n не равных L'\0' широких символов. В этом случае будет возвращено количество широких символов, записанных в dest, но состояние сдвига в этой точке теряется.

3.  Многобайтовая строка была полностью преобразована, включая завершающий символ null ('\0'). В этом случае возвращается количество записанных в dest широких символов, не считая завершающий широкий символ null.

Программист должен проверить, что в dest есть место по крайней мере для n широких символов.

Если значение dest равно NULL, то n игнорируется и преобразование выполняется как описано выше, исключая то, что преобразованные широкие символы не записываются в память и нет ограничения по длине.

Для того, чтобы избежать ограничения пункта 2, программист должен удостовериться, что значение n больше или равно mbstowcs(NULL,src,0)+1.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Функция mbstowcs() возвращает количество широких символов, которые составили преобразованную часть широкосимвольной строки, не включая конечный широкий символ null Если обнаружена некорректная многобайтовая последовательность, то возвращается (size_t) -1.

АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).
Интерфейс | Атрибут | Значение
mbstowcs() | Безвредность в нитях | MT-Safe

СООТВЕТСТВИЕ СТАНДАРТАМ
POSIX.1-2001, POSIX.1-2008, C99.

ЗАМЕЧАНИЯ
Поведение mbstowcs() зависит от категории LC_CTYPE текущей локали.

Функция mbsrtowcs(3) предоставляет лучший интерфейс с теми же возможностями.

ПРИМЕР
В программе, представленной ниже, показано использование mbstowcs(), а также некоторые функции классификации широких символов. Пример запуска:

    $ ./t_mbstowcs de_DE.UTF-8 Grüße!
    Длина исходной строки (без конечного символа):
        8 байт
        6 многобайтовых символов
    Строка широких символов: Grüße! (6 символов)
        G буква заглавная
        r буква строчная
        ü буква строчная
        ß буква строчная
        e буква строчная
        ! !буква

  Исходный код программы
    #include <wctype.h>
    #include <locale.h>
    #include <wchar.h>
    #include <stdio.h>
    #include <string.h>
    #include <stdlib.h>
    int
    main(int argc, char *argv[])
    {
        size_t mbslen;      /* количество многобайтовых символов в источнике */
        wchar_t *wcs;       /* указатель на преобразованную строку
                               широких символов */
        wchar_t *wp;
        if (argc < 3) {
            fprintf(stderr, "Использование: %s <локаль> <строка>\n", argv[0]);
            exit(EXIT_FAILURE);
        }
        /* применяем указанную локаль */
        if (setlocale(LC_ALL, argv[1]) == NULL) {
            perror("setlocale");
            exit(EXIT_FAILURE);
        }
        /* вычисляем длину, которая требуется для хранения argv[2],
           преобразованной в строку широких символов */
        mbslen = mbstowcs(NULL, argv[2], 0);
        if (mbslen == (size_t) -1) {
            perror("mbstowcs");
            exit(EXIT_FAILURE);
        }
        /* опишем исходную строку пользователю */
        printf("Длина исходной строки (без конечного символа):\n");
        printf("    %zu байт\n", strlen(argv[2]));
        printf("    %zu многобайтовых символов\n\n", mbslen);
        /* выделим место под строку широких символов желаемого размера.
           Добавим 1 для конечного широкого символа null (L'\0'). */
        wcs = calloc(mbslen + 1, sizeof(wchar_t));
        if (wcs == NULL) {
            perror("calloc");
            exit(EXIT_FAILURE);
        }
        /* преобразуем многобайтовую строку из argv[2] в
           строку широких символов */
        if (mbstowcs(wcs, argv[2], mbslen + 1) == (size_t) -1) {
            perror("mbstowcs");
            exit(EXIT_FAILURE);
        }
        printf("Строка широких символов: %ls (%zu символов)\n",
                wcs, mbslen);
        /* теперь посмотрим на классы символов в
           строке широких символов */
        for (wp = wcs; *wp != 0; wp++) {
            printf("    %lc ", (wint_t) *wp);
            if (!iswalpha(*wp))
                printf("!");
            printf("буква ");
            if (iswalpha(*wp)) {
                if (iswupper(*wp))
                    printf("заглавная ");
                if (iswlower(*wp))
                    printf("строчная ");
            }
            putchar('\n');
        }
        exit(EXIT_SUCCESS);
    }

СМОТРИТЕ ТАКЖЕ
mblen(3), mbsrtowcs(3), mbtowc(3), wcstombs(3), wctomb(3)