wcstombs, _wcstombs_l

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íveis; confira wcstombs_s, _wcstombs_s_l.

Sintaxe

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 multibyte.

wcstr
O endereço de uma sequência de caracteres largos.

count
O número máximo de bytes que pode ser armazenado na cadeia de caracteres multibyte de saída.

locale
A localidade a ser usada.

Valor retornado

Se wcstombs converter com êxito a cadeia de caracteres multibyte, será retornado o número de bytes gravados na cadeia de caracteres multibyte de saída, excluindo a terminação NULL (se houver). Se o argumento mbstr for NULL, wcstombs retornará o tamanho necessário em bytes da cadeia de caracteres de destino. Se wcstombs encontrar um caractere largo, ele não pode converter em um caractere multibyte, ele retorna -1 cast para type size_t e define errno como EILSEQ.

Comentários

A função wcstombs converte a cadeia de caracteres largos apontada por wcstr nos caracteres multibyte correspondentes e armazena os resultados na matriz mbstr. O parâmetro count indica o número máximo de bytes que pode ser armazenado na cadeia de caracteres multibyte de saída (ou seja, o tamanho de mbstr). Em geral, a quantidade de bytes necessária ao converter uma cadeia de caracteres largos não é conhecida. Alguns caracteres largos exigirão apenas um único byte na cadeia de caracteres de saída; outros requerem 2 bytes. Se houver 2 bytes na cadeia de caracteres de saída multibyte para cada caractere largo na cadeia de caracteres de entrada (incluindo o caractere NULLlargo), o resultado será garantido.

A partir da versão 1803 do Windows 10 (10.0.17134.0), o Universal C Runtime dá suporte ao uso de uma página de código UTF-8. Use wcstombs(NULL, wcstr, 0) para obter o tamanho correto necessário para a conversão, pois supor que você precisará de dois bytes para cada caractere largo pode não ser suficiente. Para obter mais informações sobre o suporte a UTF-8, consulte Suporte a UTF-8

Se wcstombs encontrar o caractere nulo de caractere largo (L'\0') NULL antes ou quando count ocorrer, ele o converterá em um 0 de 8 bits e será interrompido. Dessa forma, a cadeia de caracteres multibyte em mbstr será terminada em nulo somente se wcstombs encontrar um caractere nulo de caractere largo NULL durante a conversão. Se as sequências apontadas por wcstr e por mbstr se sobrepuserem, o comportamento de wcstombs será indefinido.

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

wcstombs valida seus parâmetros. Se wcstr for NULL, ou se count for maior que INT_MAX, essa função invocará o manipulador de parâmetro inválido, conforme descrito em Validação de parâmetro. Se a execução puder continuar, a função definirá errno como EINVAL e retornará –1.

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

No C++, essas funções têm sobrecargas de modelo que invocam os equivalentes mais novos e seguros dessas funções. Para obter mais informações, consulte Sobrecargas de modelo seguras.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, confira Estado global no CRT.

Requisitos

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

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo

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

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

Confira também

Conversão de dados
Localidade
_mbclen, mblen, _mblen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
wctomb, _wctomb_l
WideCharToMultiByte