wcsrtombs_s

Converte uma cadeia de caracteres largos em sua representação de cadeia de caracteres multibyte. Uma versão de wcsrtombs com aprimoramentos de segurança, conforme descrito em Recursos de segurança no CRT.

Sintaxe

errno_t wcsrtombs_s(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
errno_t wcsrtombs_s(
   size_t *pReturnValue,
   char (&mbstr)[size],
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
); // 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 serem armazenados no mbstr buffer ou _TRUNCATE.

mbstate
Um ponteiro para um objeto do estado da conversão mbstate_t.

Valor retornado

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

Se qualquer uma dessas condições ocorrer, a exceção de parâmetro inválido será chamada 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 wcsrtombs_s converte uma cadeia de caracteres largos apontada por wcstr em caracteres multibyte armazenados no buffer apontado por mbstr usando o estado da conversão contido em mbstate. 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, wcsrtombs_s converterá o máximo da cadeia de caracteres que caberá no buffer de destino ainda deixando espaço para um terminador nulo.

Se wcsrtombs_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 wcsrtombs_s encontrar um caractere largo que não pode ser convertido em um caractere multibyte, ele coloca -1 em *pReturnValue, 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 wcsrtombs_s será indefinido. wcsrtombs_s é afetado pela categoria LC_TYPE da localidade atual.

A wcsrtombs_s função difere de , _wcstombs_s_l por sua capacidade de wcstombs_sreinicialização. O estado da conversão é armazenado em mbstate para chamadas posteriores às mesmas funções ou a outras funções reiniciáveis. Os resultados são indefinidos ao combinar o uso de funções reiniciáveis e não reiniciáveis. Por exemplo, um aplicativo usaria wcsrlen em vez de wcslen se uma chamada subsequente a wcsrtombs_s fosse usada em vez de wcstombs_s.

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.

Exceções

A função wcsrtombs_s será multithread-safe contanto que nenhuma função no thread atual chame setlocale enquanto essa função estiver em execução e o mbstate for nulo.

Exemplo

// crt_wcsrtombs_s.cpp
//
// This code example converts a wide
// character string into a multibyte
// character string.
//

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

int main()
{
    const wchar_t   wcString[] =
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    errno_t         err;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    err = wcsrtombs_s(&countConverted, mbString, MB_BUFFER_SIZE,
                      &wcsIndirectString, MB_BUFFER_SIZE, &mbstate);
    if (err == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else
    {
        printf( "The string was successfully converted.\n" );
    }
}

The string was successfully converted.

Requisitos

Confira também

Conversão de dados
Localidade
Interpretação de sequências de caracteres multibyte
wcrtomb
wcrtomb_s
wctomb, _wctomb_l
wcstombs, _wcstombs_l
mbsinit