mbstowcs(3)

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

БИБЛИОТЕКА
Стандартная библиотека языка C (libc, -lc)

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

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

ОПИСАНИЕ
If dest is not NULL, convert the multibyte string src to a wide-character string starting at dest. At most dsize wide characters are written to dest. The sequence of characters in the string src shall begin in the initial shift state. The conversion can stop for three reasons:

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

•   dsize 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 равно NULL, dsize игнорируется, и преобразование продолжается, как описано выше, за исключением того, что преобразованные широкие символы не записываются в память, и что ограничений по длине не существует.

In order to avoid the case 2 above, the programmer should make sure dsize is greater than or equal to mbstowcs(NULL,src,0)+1.

Программист должен убедиться, что в dest есть место для символов шириной не менее dsize.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
The number of wide characters that make up the converted part of the wide-character string, not including the terminating null wide character. If an invalid multibyte sequence was encountered, (size_t) -1 is returned.

АТРИБУТЫ
Описание терминов данного раздела смотрите в 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> и Kirill Rekhov <krekhov.dev@gmail.com>

Этот перевод является свободной программной документацией; он распространяется на условиях общедоступной лицензии GNU (GNU General Public License - GPL, https://www.gnu.org/licenses/gpl-3.0.html версии 3 или более поздней) в отношении авторского права, но БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ.

Если вы обнаружите какие-либо ошибки в переводе этой страницы руководства, пожалуйста, сообщите об этом разработчику(ам) по его(их) адресу(ам) электронной почты или по адресу списка рассылки русских переводчиков (<debian-l10n-russian@lists.debian.org>).