wcrtomb

Converta um caractere largo em sua representação de caracteres multibyte. Uma versão mais segura dessa função está disponível, confira wcrtomb_s.

Sintaxe

size_t wcrtomb(
   char *mbchar,
   wchar_t wchar,
   mbstate_t *mbstate
);
template <size_t size>
size_t wcrtomb(
   char (&mbchar)[size],
   wchar_t wchar,
   mbstate_t *mbstate
); // C++ only

Parâmetros

mbchar
O caractere multibyte convertido resultante.

wchar
Um caractere largo a ser convertido.

mbstate
Um ponteiro para um objeto mbstate_t.

Retornar valor

Retorna o número de bytes necessários para representar o caractere multibyte convertido, caso contrário, retorna –1 em caso de erro.

Comentários

A função wcrtomb converte um caractere largo que começa no estado da conversão especificado contido em mbstate, com base no valor contido em wchar, no endereço representado por mbchar. O valor retornado é o número de bytes necessário para representar o caractere multibyte correspondente, mas não retornará mais de MB_CUR_MAX bytes.

Se mbstate for nulo, o objeto mbstate_t interno contendo o estado da conversão de mbchar será usado. Se a sequência wchar de caracteres não tiver uma representação de caracteres multibyte correspondente, um -1 será retornado e o errno será definido como EILSEQ.

A wcrtomb função difere de , _wctomb_l por sua capacidade de wctombreinicialização. O estado da conversão é armazenado em mbstate para chamadas posteriores às mesmas funções ou a outras funções reiniciáveis. Os resultados são indefinidos ao combinar o uso de funções reiniciáveis e não reiniciáveis. Por exemplo, um aplicativo usaria wcsrlen em vez de wcsnlen se uma chamada subsequente a wcsrtombs fosse usada em vez de wcstombs.

Em C++, essa função tem uma sobrecarga de modelo que invoca os equivalentes mais recentes e seguros dessa função. Para obter mais informações, consulte Sobrecargas de modelo seguras.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, consulte Estado global na CRT.

Exceções

A função wcrtomb será multithread-safe contanto que nenhuma função no thread atual chame setlocale enquanto essa função estiver em execução e o mbstate for nulo.

Exemplo

// crt_wcrtomb.c
// compile with: /W3
// This program converts a wide character
// to its corresponding multibyte character.

#include <string.h>
#include <stdio.h>
#include <wchar.h>

int main( void )
{
    size_t      sizeOfCovertion = 0;
    mbstate_t   mbstate;
    char        mbStr = 0;
    wchar_t*    wcStr = L"Q";

    // Reset to initial conversion state
    memset(&mbstate, 0, sizeof(mbstate));

    sizeOfCovertion = wcrtomb(&mbStr, *wcStr, &mbstate); // C4996
    // Note: wcrtomb is deprecated; consider using wcrtomb_s instead
    if (sizeOfCovertion > 0)
    {
        printf("The corresponding wide character \"");
        wprintf(L"%s\"", wcStr);
        printf(" was converted to the \"%c\" ", mbStr);
        printf("multibyte character.\n");
    }
    else
    {
        printf("No corresponding multibyte character "
               "was found.\n");
    }
}

The corresponding wide character "Q" was converted to the "Q" multibyte character.

Requisitos

Rotina	Cabeçalho necessário
wcrtomb	<wchar.h>

Confira também

Conversão de dados
Localidade
Interpretação de sequências de caracteres multibyte
mbsinit