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 широких символов. Преобразование начинается с начального состояния и может прекратиться по трём причинам:

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 <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)