mbstowcs(3) | Library Functions Manual | mbstowcs(3) |
mbstowcs - converte uma string multibyte para uma string de caracteres largos
Biblioteca C Padrão (libc, -lc)
#include <stdlib.h>
size_t mbstowcs(wchar_t dest[restrict .n], const char *restrict src, size_t n);
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:
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.
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.
Para uma explicação dos termos usados nesta seção, consulte attributes(7).
Interface | Atributo | Valor |
mbstowcs() | Thread safety | MT-Safe |
POSIX.1-2001, POSIX.1-2008, C99.
O comportamento de mbstowcs() depende da categoria LC_CTYPE da localidade atual.
A função mbsrtowcs() fornece uma interface melhor para a mesma funcionalidade.
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); }
mblen(3), mbsrtowcs(3), mbtowc(3), wcstombs(3), wctomb(3)
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.
5 fevereiro 2023 | Linux man-pages 6.03 |