mbstowcs(3)

NOME
mbstowcs - converte uma string multibyte para uma string de caracteres largos

BIBLIOTECA
Biblioteca C Padrão (libc, -lc)

SINOPSE
#include <stdlib.h>

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

DESCRIÇÃO
Se dest não é um ponteiro NULO, a função mbstowcs() converte a string multibyte orig para uma string de caracteres largos iniciando em dest. No máximo n caracteres largos são gravados em dest. A sequência de caracteres na string orig deve começar no estado de transição inicial. A conversão começa no estado inicial. A conversão pode parar por três razões:

•   Uma sequência multibyte inválida foi encontrada. Neste caso, (size_t) -1 é retornado.

•   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.

O programador deve assegurar que há espaço para pelo menos n caracteres largos em dest.

Se dest é NULO, n é ignorado, e a conversão prossegue como acima, exceto que os caracteres largos convertidos não são gravados na memória, e que não há limite de tamanho.

A fim de evitar o caso 2 acima, o programador deve garantir que n seja maior ou igual a mbstowcs(NULL,src,0)+1.

VALOR DE RETORNO
A função mbstowcs() retorna o número de caracteres largos que perfazem a parte convertida da string de caracteres largos, não incluindo o caractere largo nulo de terminação. Se uma sequência multibyte inválida foi encontrada, (size_t) -1 é retornado.

ATRIBUTOS
Para uma explicação dos termos usados nesta seção, consulte attributes(7).
Interface | Atributo | Valor
mbstowcs() | Thread safety | MT-Safe

VERSÕES
A função mbsrtowcs() fornece uma interface melhor para a mesma funcionalidade.

PADRÕES
C11, POSIX.1-2008.

HISTÓRICO
POSIX.1-2001, C99.

NOTAS
O comportamento de mbstowcs() depende da categoria LC_CTYPE da localidade atual.

EXEMPLOS
O programa abaixo ilustra o uso de mbstowcs(), bem como algumas das funções de classificação de caracteres largos. Um exemplo de execução é o seguinte:

    $ ./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

  Fonte do programa
    #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);
    }

VEJA TAMBÉM
mblen(3), mbsrtowcs(3), mbtowc(3), wcstombs(3), wctomb(3)

TRADUÇÃO
A tradução para português brasileiro desta página man foi criada por Felipe M Pereira <Felipe.Pereira@ic.unicamp.br>, André Luiz Fassone <lonely_wolf@ig.com.br> e Rafael Fontenelle <rafaelff@gnome.org>.

Esta tradução é uma documentação livre; leia a Licença Pública Geral GNU Versão 3 (https://www.gnu.org/licenses/gpl-3.0.html) ou posterior para as condições de direitos autorais. Nenhuma responsabilidade é aceita.

Se você encontrar algum erro na tradução desta página de manual, envie um e-mail para a lista de discussão de tradutores (debian-l10n-portuguese@lists.debian.org).