wcsrtombs

Converte uma cadeia de caracteres largos em sua representação de cadeia de caracteres multibyte. Uma versão mais segura dessa função está disponível, confira wcsrtombs_s.

Sintaxe

size_t wcsrtombs(
   char *mbstr,
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
size_t wcsrtombs(
   char (&mbstr)[size],
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
); // C++ only

Parâmetros

mbstr
O local do endereço da cadeia de caracteres multibyte convertida resultante.

wcstr
Aponta indiretamente para o local da cadeia de caracteres largos a ser convertida.

count
O número de caracteres a serem convertidos.

mbstate
Um ponteiro para um objeto do estado da conversão mbstate_t.

Retornar valor

Retorna o número de bytes convertidos com êxito, não incluindo o byte nulo de terminação nula (se houver), caso contrário, retorna –1 em caso de erro.

Comentários

A função wcsrtombs converte uma cadeia de caracteres largos que começa no estado da conversão especificado contido em mbstate, com base nos valores indiretos apontados em wcstr, no endereço de mbstr. A conversão continuará para cada caractere até: um caractere largo de terminação nula ser encontrado, um caractere não correspondente ser encontrado ou o próximo caractere exceder o limite contido em count. Se wcsrtombs encontrar o caractere nulo de caractere largo (L'\0') antes ou quando count ocorrer, ele o converterá em um 0 de 8 bits e será interrompido.

Dessa forma, a cadeia de caracteres multibyte em mbstr será terminada em nulo somente se wcsrtombs encontrar um caractere nulo de caractere largo durante a conversão. Se as sequências apontadas por wcstr e por mbstr se sobrepuserem, o comportamento de wcsrtombs será indefinido. wcsrtombs é afetado pela categoria LC_TYPE da localidade atual.

A wcsrtombs função difere de , _wcstombs_l por sua capacidade de wcstombsreinicializaçã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.

Se o argumento mbstr for NULL, wcsrtombs retornará o tamanho necessário em bytes da cadeia de caracteres de destino. Se mbstate for nulo, o estado da conversão mbstate_t interno 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.

Em C++, essa função tem uma sobrecarga de modelo que invoca o equivalente mais recente e seguro 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 wcsrtombs função é segura para vários threads, desde que nenhuma função nas chamadas setlocale de thread atuais enquanto essa função estiver em execução e a mbstate não for nula.

Exemplo

// crt_wcsrtombs.cpp
// compile with: /W3
// This code example converts a wide
// character string into a multibyte
// character string.

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

int main()
{
    const wchar_t   wcString[] =
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    countConverted = wcsrtombs(mbString, &wcsIndirectString,
                               MB_BUFFER_SIZE, &mbstate); // C4996
    // Note: wcsrtombs is deprecated; consider using wcsrtombs_s
    if (errno == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else
    {
        printf( "The string was successfuly converted.\n" );
    }
}

The string was successfuly converted.

Requisitos

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

Confira também

Conversão de dados
Localidade
Interpretação de sequências de caracteres multibyte
wcrtomb
wcrtomb_s
wctomb, _wctomb_l
wcstombs, _wcstombs_l
mbsinit