Compartilhar via

wcstombs_s, _wcstombs_s_l

  • Artigo

Converte uma sequência de caracteres largos em uma sequência de caracteres multibyte correspondente. Uma versão do , com aprimoramentos de segurança, _wcstombs_lconforme descrito em Recursos de segurança no CRT.wcstombs

Sintaxe

errno_t wcstombs_s(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t *wcstr,
   size_t count
);

errno_t _wcstombs_s_l(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
);

template <size_t size>
errno_t wcstombs_s(
   size_t *pReturnValue,
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count
); // C++ only

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

Parâmetros

pReturnValue
O tamanho em bytes da cadeia de caracteres convertida, incluindo o terminador nulo.

mbstr
O endereço de um buffer da cadeia de caracteres multibyte convertida resultante.

sizeInBytes
O tamanho em bytes do buffer mbstr.

wcstr
Aponta para a cadeia de caracteres largos a ser convertida.

count
O número máximo de bytes a ser armazenado no buffer mbstr, não incluindo o caractere nulo de terminação ou em _TRUNCATE.

locale
A localidade a ser usada.

Valor retornado

Zero se for bem-sucedido ou um código de erro em caso de falha.

Condição de erro Valor retornado e errno
mbstr é NULL e sizeInBytes> 0 EINVAL
wcstr é NULL EINVAL
O buffer de destino é muito pequeno para conter a cadeia de caracteres convertida (a menos que count seja _TRUNCATE; consulte Comentários abaixo) ERANGE

Se qualquer uma dessas condições ocorrer, a exceção de parâmetro inválido será invocada conforme descrito em Validação de parâmetro. Se a execução puder continuar, a função retornará um código de erro e definirá errno conforme indicado na tabela.

Comentários

A função wcstombs_s converte uma cadeia de caracteres largos apontada por wcstr em caracteres multibyte armazenados no buffer apontado por mbstr. A conversão continuará para cada caractere até que uma das seguintes condições seja atendida:

  • Um caractere largo nulo é encontrado

  • Um caractere largo que não pode ser convertido é encontrado

  • O número de bytes armazenados no buffer mbstr é igual a count.

A cadeia de caracteres de destino é sempre terminada em nulo (mesmo se houver um erro).

Se count for o valor especial _TRUNCATE, wcstombs_s converterá o máximo da cadeia de caracteres que caberá no buffer de destino ainda deixando espaço para um terminador nulo. Se a cadeia de caracteres estiver truncada, o valor retornado será STRUNCATE e a conversão será considerada bem-sucedida.

Se wcstombs_s converter com êxito a cadeia de caracteres de origem, ele colocará o tamanho em bytes da cadeia de caracteres convertida, incluindo o terminador nulo, em *pReturnValue (provided pReturnValue isn't NULL). O tamanho é calculado mesmo se o mbstr argumento for NULL; ele fornece uma maneira de determinar o tamanho do buffer necessário. Se mbstr for NULL, count será ignorado.

Se wcstombs_s encontrar um caractere largo que não pode ser convertido em um caractere multibyte, ele coloca 0 em *ReturnValue, define o buffer de destino como uma string vazia, define errno como EILSEQe retorna EILSEQ.

Se as sequências apontadas por wcstr e por mbstr se sobrepuserem, o comportamento de wcstombs_s será indefinido.

Importante

Verifique se wcstr e mbstr não se sobrepõem e se count reflete corretamente o número de caracteres largos a ser convertido.

wcstombs_s usa a localidade atual de qualquer comportamento dependente da localidade; _wcstombs_s_l é idêntico a wcstombs, exceto que, em vez disso, ele usa a localidade passada. Para obter mais informações, consulte Localidade.

Em C++, o uso dessas funções é simplificado pelas sobrecargas de modelo; as sobrecargas podem inferir o tamanho do buffer automaticamente (eliminando a necessidade de especificar um argumento de tamanho) e podem substituir automaticamente funções mais antigas e não seguras por suas equivalentes mais recentes e seguras. 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_s <stdlib.h>

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

Exemplo

Este programa ilustra o comportamento da função wcstombs_s.

// crt_wcstombs_s.c
// This example converts a wide character
// string to a multibyte character string.
#include <stdio.h>
#include <stdlib.h>
#include <assert.h>

#define BUFFER_SIZE 100

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

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

    // Conversion
    wcstombs_s(&i, pMBBuffer, (size_t)BUFFER_SIZE,
               pWCBuffer, (size_t)BUFFER_SIZE - 1); // -1 so the appended NULL doesn't fall outside the allocated buffer

    // Output
    printf("   Characters converted: %u\n", i);
    printf("    Multibyte character: %s\n\n", pMBBuffer );

    // Free multibyte character buffer
    if (pMBBuffer)
    {
        free(pMBBuffer);
    }
    
    return 0;
}

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

Confira também

Conversão de dados
Localidade
_mbclen, mblen, _mblen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
wctomb_s, _wctomb_s_l
WideCharToMultiByte