ИМЯ

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

ИМЯ