wcstombs, _wcstombs_l

Artigo
02/25/2013

Converte uma seqüência de caracteres de largura para uma seqüência de correspondente de caracteres multibyte.Versões mais seguras dessas funções estão disponíveis; see 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 seqüência de caracteres multibyte.
wcstr
O endereço de uma seqüência de caracteres de largura.
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

Se wcstombs com êxito, converte a seqüência de caracteres multibyte, ele retorna o número de bytes gravados na seqüência multibyte de saída, excluindo a terminação NULL (se houver).Se a mbstr argumento é NULL, wcstombs retorna o tamanho necessário em bytes da seqüência de caracteres de destino.Se wcstombs encontra um caractere largo, ele não é possível converter um caractere multibyte, ele retorna – 1 convertida para o tipo size_t e define errno para EILSEQ.

Comentários

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

Se wcstombs 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 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 de wcstombs é indefinido.

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

wcstombsvalida os seus parâmetros.Se wcstr é NULL, ou se count é maior do queINT_MAX, essa função chama o manipulador de parâmetro inválido, conforme descrito em Validação de parâmetro .Se a execução terá permissão para continuar, a função define errno para EINVAL e retorna -1.

wcstombsusa a localidade atual para qualquer comportamento depende da localidade; _wcstombs_lé idêntica, exceto que ele usa a localidade passada em vez disso.Para obter mais informações, consulte Localidade.

No C++, essas funções têm sobrecargas de modelo que invocam as suas similares do mais recentes, seguras dessas funções.Para obter mais informações, consulte Proteger Overloads de modelo.

Requisitos

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

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

Exemplo

Este programa ilustra o comportamento da 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);
}