wcstombs, _wcstombs_l

Artigo
08/25/2010

Converte uma sequência de caracteres largos em uma sequência de caracteres multibyte correspondente.Versões mais seguras dessas funções estão disponível; consulte wcstombs_s, _wcstombs_s_l.

size_t wcstombs(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count 
);
size_t _wcstombs_l(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
size_t wcstombs(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count 
); // C++ only
template <size_t size>
size_t _wcstombs_l(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
); // C++ only

Parâmetros

mbstr
O endereço de uma sequência de caracteres de multibyte.
wcstr
O endereço de uma sequência de caracteres largos.
count
O número máximo de bytes que podem ser armazenadas na seqüência de caracteres multibyte de saída.
locale
A localidade para usar.

Valor de retorno

If wcstombs com êxito converte a seqüência de caracteres multibyte, ela retorna o número de bytes gravados na seqüência de saída de vários bytes, excluindo a terminação NULL (se houver). Se o mbstr o argumento é NULL, wcstombs Retorna o dimensionar necessário em bytes da seqüência de caracteres de destino. If wcstombs encontrar um caractere largo não pode converter em um caractere multibyte, retornará – 1 convertido para digitar size_t e conjuntos errno para EILSEQ.

Comentários

The wcstombs função converte a seqüência de caractere largos apontada por wcstr para caractere de multibyte correspondente e armazena os resultados na mbstr matriz. The count parâmetro indica o número máximo de bytes que podem ser armazenadas na seqüência de caracteres multibyte saída (isto é, o dimensionar de mbstr). Em geral, não se sabe quantos bytes serão necessários ao converter uma seqüência de caractere largos.Alguns caracteres largos exigirá apenas um byte na cadeia de saída; outros exigem dois.Se houver dois bytes na cadeia de saída de vários bytes para cada caractere na seqüência de caracteres de entrada (incluindo o caractere largo amplaNULL), o resultado é garantido que se encaixam.

If wcstombs 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 wcstombs 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 wcstombs não está definida.

Se o mbstr o argumento é NULL, wcstombs Retorna o dimensionar necessário em bytes da seqüência de caracteres de destino.

wcstombs valida os parâmetros. If wcstr is NULL, or if count is greater thanINT_MAX, this function invokes the invalid parameter handler, as described in Validação de parâmetro .Se a execução for permitida para continuar, a função define errno para EINVAL e retorna -1.

wcstombs usa a localidade corrente para qualquer comportamento dependente de localidade; _wcstombs_l é idêntico, exceto pelo fato de que ele usa a localidade do passado em vez disso. For more information, see Localidade.

No C++, essas funções têm sobrecargas de modelo que invocam as suas similares do mais recentes, seguras dessas funções.For more information, see Proteger overloads de modelo.

Requisitos

Rotina	Cabeçalho necessário
wcstombs	<stdlib.h>
_wcstombs_l	<stdlib.h>

Para obter informações adicionais compatibilidade, consulte Compatibilidade na introdução.

Exemplo

Este programa ilustra o comportamento do wcstombs função.

// crt_wcstombs.c
// compile with: /W3
// This example demonstrates the use
// of wcstombs, which converts a string
// of wide characters to a string of 
// multibyte characters.

#include <stdlib.h>
#include <stdio.h>

#define BUFFER_SIZE 100

int main( void )
{
    size_t  count;
    char    *pMBBuffer = (char *)malloc( BUFFER_SIZE );
    wchar_t *pWCBuffer = L"Hello, world.";

    printf("Convert wide-character string:\n" );

    count = wcstombs(pMBBuffer, pWCBuffer, BUFFER_SIZE ); // C4996
    // Note: wcstombs is deprecated; consider using wcstombs_s instead
    printf("   Characters converted: %u\n",
            count );
    printf("    Multibyte character: %s\n\n",
           pMBBuffer );

    free(pMBBuffer);
}

Convert wide-character string:    Characters converted: 13     Multibyte character: Hello, world.