wcsrtombs

Artigo
02/25/2013

Converta uma seqüência de caracteres longa em sua representação de seqüência de caracteres multibyte.Uma versão mais segura desta função está disponível. see wcsrtombs_s.

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

[out]mbstr
O resultante convertido a localização de endereço da seqüência de caracteres multibyte.
[in]wcstr
Indiretamente aponta para o local da seqüência de caracteres largos a ser convertido.
[in]count
O número de caracteres a ser convertido.
[in]mbstate
Um ponteiro para um mbstate_t objeto de estado de conversão.

Valor de retorno

Retorna o número de bytes convertido com êxito, não incluindo o null encerrando o byte nulo (se houver), caso contrário -1 se ocorreu um erro.

Comentários

O wcsrtombs função converte uma seqüência de caracteres de largura, começando no estado de conversão especificada contido no mbstate, dos valores indiretos apontados na wcstr, no endereço de mbstr.A conversão continuará para cada caractere até: depois que um valor nulo caractere largo de terminação é encontrado, quando um caractere correspondente não for encontrado ou quando o próximo caractere excede o limite contido no count.Se wcsrtombs encontra o caractere nulo de caractere largo (L '\0') antes ou quando count ocorre, ele converte para um 0 de 8 bits e pára.

Assim, a seqüência de caracteres multibyte em mbstr é terminada com nulo somente se wcsrtombs encontra um caractere nulo de caractere largo durante a conversão.Se as seqüências apontada por wcstr e mbstr se sobrepõem, o comportamento de wcsrtombs é indefinido.wcsrtombsé afetado pela categoria de LC_TYPE da localidade atual.

O wcsrtombs função difere wcstombs, _wcstombs_l por sua capacidade de reinicialização.O estado de conversão é armazenado em mbstate para chamadas subseqüentes para o mesmo ou outras funções reinicializáveis.Os resultados são indefinidos ao combinar o uso de funções reiniciáveis e não reiniciável.Por exemplo, um aplicativo deve usar wcsrlen em vez de wcsnlen, se uma chamada subseqüente para wcsrtombs foram usados em vez de wcstombs.

Se a mbstr argumento é NULL, wcsrtombs retorna o tamanho necessário em bytes da seqüência de caracteres de destino.Se mbstate for nulo, o interno mbstate_t estado de conversão é usado.Se a seqüência de caracteres wchar não tem um correspondente multibyte representação de caracteres, -1 é retornado e a errno for definido como EILSEQ.

No C++, essa função possui uma sobrecarga de modelo que invoca a contraparte segura, mais recente desta função.Para obter mais informações, consulte Proteger Overloads de modelo.

Exceções

O wcsrtombs função é seguro com vários threads, desde que nenhuma função no segmento atual chama setlocale enquanto esta função está sendo executado e o mbstate não é nulo.

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" );
    }
}