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

PADRÕES

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

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.