mbstowcs(3)

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

LIBRARY
Standard C library (libc, -lc)

СИНТАКСИС
#include <stdlib.h>

size_t mbstowcs(wchar_t dest[restrict .n], const char *restrict src,
                size_t n);

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

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

•   n non-L'\0' wide characters have been stored at dest. In this case, the number of wide characters written to dest is returned, but the shift state at this point is lost.

•   The multibyte string has been completely converted, including the terminating null character ('\0'). In this case, the number of wide characters written to dest, excluding the terminating null wide character, is returned.

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

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

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

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

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

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

СТАНДАРТЫ
C11, POSIX.1-2008.

ИСТОРИЯ
POSIX.1-2001, C99.

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

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

    $ ./t_mbstowcs de_DE.UTF-8 Grüße!
    Length of source string (excluding terminator):
        8 bytes
        6 multibyte characters

    Wide character string is: Grüße! (6 characters)
        G alpha upper
        r alpha lower
        ü alpha lower
        ß alpha lower
        e alpha lower
        ! !alpha

  Исходный код программы
    #include <locale.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>
    #include <wchar.h>
    #include <wctype.h>

    int
    main(int argc, char *argv[])
    {
        size_t mbslen;      /* Number of multibyte characters in source */
        wchar_t *wcs;       /* Pointer to converted wide character string */

        if (argc < 3) {
            fprintf(stderr, "Usage: %s <locale> <string>\n", argv[0]);
            exit(EXIT_FAILURE);
        }

        /* Apply the specified locale. */

        if (setlocale(LC_ALL, argv[1]) == NULL) {
            perror("setlocale");
            exit(EXIT_FAILURE);
        }

        /* Calculate the length required to hold argv[2] converted to
           a wide character string. */

        mbslen = mbstowcs(NULL, argv[2], 0);
        if (mbslen == (size_t) -1) {
            perror("mbstowcs");
            exit(EXIT_FAILURE);
        }

        /* Describe the source string to the user. */

        printf("Length of source string (excluding terminator):\n");
        printf("    %zu bytes\n", strlen(argv[2]));
        printf("    %zu multibyte characters\n\n", mbslen);

        /* Allocate wide character string of the desired size.  Add 1
           to allow for terminating null wide character (L'\0'). */

        wcs = calloc(mbslen + 1, sizeof(*wcs));
        if (wcs == NULL) {
            perror("calloc");
            exit(EXIT_FAILURE);
        }

        /* Convert the multibyte character string in argv[2] to a
           wide character string. */

        if (mbstowcs(wcs, argv[2], mbslen + 1) == (size_t) -1) {
            perror("mbstowcs");
            exit(EXIT_FAILURE);
        }

        printf("Wide character string is: %ls (%zu characters)\n",
               wcs, mbslen);

        /* Now do some inspection of the classes of the characters in
           the wide character string. */

        for (wchar_t *wp = wcs; *wp != 0; wp++) {
            printf("    %lc ", (wint_t) *wp);

            if (!iswalpha(*wp))
                printf("!");
            printf("alpha ");

            if (iswalpha(*wp)) {
                if (iswupper(*wp))
                    printf("upper ");

                if (iswlower(*wp))
                    printf("lower ");
            }

            putchar('\n');
        }

        exit(EXIT_SUCCESS);
    }

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

ПЕРЕВОД
Русский перевод этой страницы руководства был сделан aereiae <aereiae@gmail.com>, Alexey <a.chepugov@gmail.com>, Azamat Hackimov <azamat.hackimov@gmail.com>, Dmitriy S. Seregin <dseregin@59.ru>, Dmitry Bolkhovskikh <d20052005@yandex.ru>, ITriskTI <ITriskTI@gmail.com>, Max Is <ismax799@gmail.com>, Yuri Kozlov <yuray@komyakino.ru>, Иван Павлов <pavia00@gmail.com> и Малянов Евгений Викторович <maljanow@outlook.com>

Этот перевод является бесплатной документацией; прочитайте Стандартную общественную лицензию GNU версии 3 (https://www.gnu.org/licenses/gpl-3.0.html) или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ.

Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на man-pages-ru-talks@lists.sourceforge.net.