wcrtomb

Artigo
06/09/2015

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

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

[saída] mbchar
O caractere convertido multibyte resultante.
[entrada] wchar
Um caractere largo a ser convertida.
[entrada] mbstate
Um ponteiro para um objeto mbstate_t.

Valor de retorno

Retorna o número de bytes necessários para representar o caracteres multibyte, caso contrário A-1 convertidos se ocorrer um erro.

Comentários

A função de wcrtomb converte um caractere largo, começando no estado especificado de conversão contido em mbstate, do valor contido em wchar, no endereço representado por mbchar. O valor de retorno é o número de bytes necessários para representar o caractere correspondente multibyte, mas não retornará mais de bytes de MB_CUR_MAX .

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

A função de wcrtomb difere de wctomb, _wctomb_l por seu restartability. O estado da conversão é armazenado em mbstate para chamadas subsequentes à mesma ou a outras funções restartable. Os resultados são definidos ao misturar o uso de funções restartable e nonrestartable. Por exemplo, um aplicativo use wcsrlen em vez de wcsnlen, se uma chamada subsequente a wcsrtombs foi usado em vez de wcstombs.

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

Exceções

A função de wcrtomb é seguro multi-threaded desde que nenhuma função no thread atual chama setlocale quando essa função é executada e quando mbstate é 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");
    }
}