_mbsnbset_s, _mbsnbset_s_l

Define os primeiros n bytes de uma cadeia de caracteres multibyte como um caractere especificado. Essas versões do , _mbsnbset_ltêm aprimoramentos de_mbsnbset segurança, conforme descrito em Recursos de segurança no CRT.

Importante

Esta API não pode ser usada em aplicativos executados no Windows Runtime. Para obter mais informações, confira Funções do CRT sem suporte em aplicativos da Plataforma Universal do Windows.

Sintaxe

errno_t _mbsnbset_s(
   unsigned char *str,
   size_t size,
   unsigned int c,
   size_t count
);
errno_t _mbsnbset_s_l(
   unsigned char *str,
   size_t size,
   unsigned int c,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t _mbsnbset_s(
   unsigned char (&str)[size],
   unsigned int c,
   size_t count
); // C++ only
template <size_t size>
errno_t _mbsnbset_s_l(
   unsigned char (&str)[size],
   unsigned int c,
   size_t count,
   _locale_t locale
); // C++ only

Parâmetros

str
Cadeia de caracteres a ser alterada.

size
O tamanho do buffer da cadeia de caracteres.

c
Configuração de caractere multibyte ou de byte único.

count
Número de bytes a serem definidos.

locale
Localidade a usar.

Valor retornado

Zero se for bem-sucedido, caso contrário, um código de erro.

Comentários

As funções _mbsnbset_s e _mbsnbset_s_l definem, no máximo, os primeiros count bytes de str para c. Se count for maior que o comprimento de str, o comprimento de str será usado ao invés de count. Se c for um caractere multibyte e não puder ser definido inteiramente no último byte especificado por count, o último byte é preenchido com um caractere em branco. _mbsnbset_s e _mbsnbset_s_l não coloque um nulo de terminação no final de str.

_mbsnbset_s e _mbsnbset_s_l lembram _mbsnset, exceto que elas configuram count bytes em vez de count caracteres de c.

Se str for ou count NULL for zero, essa função gerará uma exceção de parâmetro inválida, conforme descrito em Validação de parâmetro. Se a execução tiver permissão para continuar, errno será definido como EINVAL e a função retornará NULL. Além disso, if c não é um caractere multibyte válido, errno é definido como EINVAL e um espaço é usado.

O valor de saída é afetado pela configuração da categoria LC_CTYPE da localidade. Para obter mais informações, consulte setlocale. A versão _mbsnbset_s dessa função usa a localidade atual desse comportamento dependente da localidade. A versão _mbsnbset_s_l é idêntica, exceto por usar o parâmetro de localidade passado em seu lugar. Para obter mais informações, consulte Localidade.

No C++, o uso dessas funções é simplificado por sobrecargas de modelo. As sobrecargas podem inferir o tamanho do buffer automaticamente, eliminando a necessidade de especificar um argumento de tamanho. Para obter mais informações, consulte Sobrecargas de modelo seguras.

As versões de biblioteca de depuração dessas funções preenchem o buffer com 0xFE. Para desabilitar esse comportamento, use _CrtSetDebugFillThreshold.

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

Mapeamentos de rotina de texto genérico

Rotina Tchar.h	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
_tcsnset_s	_strnset_s	_mbsnbset_s	_wcsnset_s
_tcsnset_s_l	_strnset_s _l	_mbsnbset_s_l	_wcsnset_s_l

Requisitos

Rotina	Cabeçalho necessário
_mbsnbset_s	<mbstring.h>
_mbsnbset_s_l	<mbstring.h>

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

Exemplo

// crt_mbsnbset_s.c
#include <mbstring.h>
#include <stdio.h>

int main( void )
{
   char string[15] = "This is a test";
   /* Set not more than 4 bytes of string to be *'s */
   printf( "Before: %s\n", string );
   _mbsnbset_s( string, sizeof(string), '*', 4 );
   printf( "After:  %s\n", string );
}

Saída

Before: This is a test
After:  **** is a test

Confira também

Manipulação de cadeia de caracteres
_mbsnbcat, _mbsnbcat_l
_strnset, _strnset_l, _wcsnset, _wcsnset_l, _mbsnset, , _mbsnset_l
_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, , _mbsset_l