wcstombs, _wcstombs_l

Artigo
06/09/2015

Converte uma sequência de caracteres amplos a uma sequência de correspondência de caracteres de vários bytes. Versões mais seguras dessas funções estão disponíveis; 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 vários bytes.
wcstr
O endereço de uma sequência de caracteres amplos.
count
O número máximo de bytes que pode ser armazenado na cadeia de caracteres de saída multibyte.
locale
A localidade a ser usada.

Valor de retorno

Se wcstombs converte a cadeia de caracteres multibyte, retorna o número de bytes gravados na cadeia de caracteres de saída multibyte, com exceção de NULL encerrando (se houver). Se o argumento de mbstr é NULL, wcstombs retorna o tamanho necessário em bytes da cadeia de caracteres de destino. Se wcstombs encontrar um caractere largo que não pode converter em um caracteres multibyte, retorna 1 – conversão para digitar size_t e define errno a EILSEQ.

Comentários

A função de wcstombs converte a cadeia de caracteres ampla de caracteres apontada por wcstr os caracteres correspondentes multibyte e armazena os resultados na matriz de mbstr . O parâmetro de count indica o número máximo de bytes que pode ser armazenado na cadeia de caracteres de saída multibyte (isto é, o tamanho de mbstr). Em geral, não se sabe quantos bytes serão necessários ao converter uma cadeia de caracteres de ampla caractere. Alguns caracteres amplos exigirá apenas um byte na cadeia de caracteres de saída; outros exigem dois. Se houver dois bytes na cadeia de caracteres de saída de vários bytes para cada caractere largo na cadeia de caracteres de entrada (que inclui o caractere largo NULL), o resultado é garantido para caber.

Se wcstombs encontrar o caractere nulo ampla de caracteres (L \ 0 ') ou antes ou count quando ocorrer, o converte a 0 de 8 bits e o para. Assim, a cadeia de caracteres multibyte mbstr é terminada em nulo apenas se wcstombs encontrar um caractere nulo ampla de caracteres durante a conversão. Se as sequências apontadas por wcstr e a sobreposição de mbstr , o comportamento de wcstombs são indefinidas.

Se o argumento de mbstr é NULL, wcstombs retorna o tamanho necessário em bytes da cadeia de caracteres de destino.

wcstombs valida seus parâmetros. Se wcstr é NULL, ou se count é maior queINT_MAX, essa função invoca o manipulador inválido do parâmetro, conforme descrito em Validação do parâmetro . Se a execução for permitida continuar, a função errno define a EINVAL e retorna -1.

wcstombs usa a localidade atual para qualquer comportamento dependente de localidade; _wcstombs_l é idêntico exceto que usa a localidade passada por vez. Para obter mais informações, consulte Localidade.

No C++, essas funções têm as sobrecargas de modelo que invocam as correspondentes seguras mais recentes dessas funções. Para obter mais informações, consulte Sobrecargas de modelo seguras.

Requisitos

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

Para informações adicionais de compatibilidade, consulte Compatibilidade na Introdução.

Exemplo

Esse programa ilustra o comportamento da função de wcstombs .

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