wcsrtombs

Artigo
08/25/2010

Converter uma seqüência de caractere longa em sua representação de seqüência de caractere multibyte.Uma versão mais segura desta função está disponível; consulte 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 endereço local da seqüência de caractere multibyte.
[in]wcstr
Indiretamente aponta para o local da ampla seqüência de caractere a ser convertido.
[in]count
O número de caractere 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 nulo de terminação byte nulo (se houver), caso contrário, -1 se tiver ocorrido um erro.

Comentários

The 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 no wcstr, no endereço de mbstr. Continuará a conversão 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 excederia o limite contido em count. If wcsrtombs encontra o caractere nulo de caractere largo (L '\0') antes ou quando count ocorre, ele converte para um 0 8 bit 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 do wcsrtombs não está definida. wcsrtombs é afetado pela categoria do LC_TYPE da localidade corrente.

The 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 Outros funções reinicializáveis. Os resultados são indefinidos ao misturar o uso de funções nonrestartable e reinicializáveis.Por exemplo, um aplicativo utilize wcsrlen em vez de wcsnlen, se uma telefonar subseqüente para wcsrtombs foi usado em vez de wcstombs.

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

No C++, essa função tem uma sobrecarga de modelo que invoca a contraparte mais recente e segura dessa função.For more information, see Proteger overloads de modelo.

Exceções

The wcsrtombs função é safe com vários threads sistema autônomo longo sistema autônomo nenhuma função nas chamadas de thread corrente setlocale durante a execução dessa função e o mbstate é 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" );
    }
}

The string was successfuly converted.