NOME¶

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

SINOPSE¶

#include <stdlib.h>

size_t mbstowcs(wchar_t *restrict dest, 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:

1.

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

2.

n caracteres largos diferentes de L'\0' foram gravados em dest. Neste caso o número de caracteres largos gravados em dest é retornado, mas o estado de transição neste ponto é perdido.

3.

A string multibyte foi completamente convertida, incluindo o caractere nulo de terminação ('\0'). Neste caso o número de caracteres largos gravados em dest, excluindo o caractere nulo de terminação, é retornado.

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

DE ACORDO COM¶

POSIX.1-2001, POSIX.1-2008, C99.

NOTAS¶

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

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

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

#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;      /* Número de caracteres multibyte no fonte */


    wchar_t *wcs;       /* Ponteiro para string de caracteres largos convertida */


    if (argc < 3) {


        fprintf(stderr, "Usage: %s <locale> <string>\n", argv[0]);


        exit(EXIT_FAILURE);


    }


    /* Aplica a localidade especificada. */


    if (setlocale(LC_ALL, argv[1]) == NULL) {


        perror("setlocale");


        exit(EXIT_FAILURE);


    }


    /* Calcula o tamanho necessário para manter argv[2] convertido


       para uma string da caracteres largos. */


    mbslen = mbstowcs(NULL, argv[2], 0);


    if (mbslen == (size_t) -1) {


        perror("mbstowcs");


        exit(EXIT_FAILURE);


    }


    /* Descreve a string fonte para o usuário. */


    printf("Length of source string (excluding terminator):\n");


    printf("    %zu bytes\n", strlen(argv[2]));


    printf("    %zu multibyte characters\n\n", mbslen);


    /* Aloca uma string de caracteres largos do tamanho desejado.


       Adicione 1 para permitir caractere largo nulo de terminação


       (L'\0'). */


    wcs = calloc(mbslen + 1, sizeof(*wcs));


    if (wcs == NULL) {


        perror("calloc");


        exit(EXIT_FAILURE);


    }


    /* Converte uma string da caracteres multibyte em argv[2]


       para uma string de caracteres largos. */


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


    /* Agora faz uma inspeção da classe de caracteres na string


       de caracteres largos. */


    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)

COLOFÃO¶

Esta página faz parte da versão 5.13 do projeto Linux man-pages. Uma descrição do projeto, informações sobre relatórios de bugs e a versão mais recente desta página podem ser encontradas em https://www.kernel.org/doc/man-pages/.

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