_mbsnbset_s, _mbsnbset_s_l

Define os primeiros n bytes de uma cadeia de caracteres de vários bytes como um caractere especificado. Essas versões do _mbsnbset, _mbsnbset_l têm aprimoramentos de segurança, conforme descrito em Recursos de segurança no CRT.

Importante

Essa API não pode ser usada em aplicativos executados no Tempo de Execução do Windows. Para obter mais informações, consulte funções CRT não suportadas 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
String a ser alterada.

size
O tamanho do buffer de cadeia de caracteres.

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

count
Número de bytes a definir.

locale
Localidade a ser usada.

Valor de retorno

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

Observações

As _mbsnbset_s funções 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 é usado em vez de count. Se c for um caractere multibyte e não puder ser definido inteiramente no último byte especificado pelo count, o último byte será 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 se assemelham _mbsnset, exceto que eles definem count bytes em vez count de caracteres de c.

Se str for NULL ou count 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 for permitida para continuar, errno é definido como EINVAL e a função retorna NULL. Além disso, se c não for um caractere multibyte válido, errno será definido como EINVAL e um espaço será usado.

O valor de saída é afetado pela configuração da LC_CTYPE categoria da localidade. Para obter mais informações, consulte setlocale. A _mbsnbset_s versão dessa função usa a localidade atual para esse comportamento dependente da localidade, a _mbsnbset_s_l versão é idêntica, exceto que, em vez disso, usa o parâmetro locale que é passado. Para obter mais informações, consulte Locale.

Em C++, o uso dessas funções é simplificado por sobrecargas de modelo; As sobrecargas podem inferir o comprimento do buffer automaticamente e, assim, eliminar a necessidade de especificar um argumento de tamanho. Para obter mais informações, consulte Sobrecargas de modelo seguro.

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

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, consulte Estado global na 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

Requerimentos

Rotina	Cabeçalho obrigatório
_mbsnbset_s	<mbstring.h>
_mbsnbset_s_l	<mbstring.h>

Para obter mais 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 );
}

Resultado

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

Ver também

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