_mbsnbset_s, _mbsnbset_s_l

Статья
06/09/2015

Задает первым n байтам многобайтовой строки указанное значение. В этих версиях _mbsnbset, _mbsnbset_l усовершенствована безопасность, как описано в разделе Функции безопасности в CRT.

Важно!

Этот API не может использоваться в приложениях, выполняемых в Среда выполнения Windows.Дополнительные сведения см. в статье Функции CRT, которые не поддерживаются с ключом /ZW.

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

Параметры

str
Строка, которую требуется изменить.
size
Размер строкового буфера.
c
Параметр однобайтовой или многобайтовой кодировки.
count
Число байтов для установки.
locale
Языковой стандарт, который необходимо использовать.

Возвращаемое значение

Ноль в случае успешного выполнения; в противном случае — код ошибки.

Заметки

Функции _mbsnbset_s и _mbsnbset_s_l устанавливают, по крайней мере, первые count байт str в c. Если count больше, чем длина str, длина str используется вместо count. Если c многобайтовый и не может быть полностью задан последнему байту, определенному count, последний байт дополняется с пустым символом. _mbsnbset_s и _mbsnbset_s_l не устанавливают завершающий нулевой символ в конце str.

_mbsnbset_s и _mbsnbset_s_l похожи на _mbsnset, за исключением того, что они устанавливают count байт, а не count символов c.

Если str — NULL или count — ноль, эта функция создает исключение недопустимого параметра, как описано в разделе Проверка параметров. Если продолжение выполнения разрешено, то errno устанавливается в EINVAL, и функция возвращает NULL. Кроме того, если c не является допустимым многобайтовым символом, errno устанавливается в EINVAL, и вместо него используется пробел

Выходное значение зависит от настройки категории LC_CTYPE языкового стандарта; дополнительные сведения см. в разделе setlocale, _wsetlocale. Версия _mbsnbset_s использует текущий языковой стандарт для поведения, зависящего от языкового стандарта, а _mbsnbset_s_l идентична, за исключением того, что использует переданный языковой стандарт. Для получения дополнительной информации см. Языковой стандарт.

В C++ использование этих функций упрощено шаблонными перегрузками; перегрузки могут определить длину буфера автоматически, устранена необходимость указывать аргумент size. Дополнительные сведения см. в разделе Безопасные перегрузки шаблонов.

Отладочные версии этих функций сначала заполняют буфер значением 0xFD. Для отключения данного поведения используйте _CrtSetDebugFillThreshold.

Универсальное текстовое сопоставление функций

Подпрограмма Tchar.h	_UNICODE и _MBCS не определены	_MBCS определено	_UNICODE определено
_tcsnset_s	_strnset_s	_mbsnbset_s	_wcsnset_s
_tcsnset_s_l	_strnset_s _l	_mbsnbset_s_l	_wcsnset_s_l

Требования

Подпрограмма	Обязательный заголовок
_mbsnbset_s	<mbstring.h>
_mbsnbset_s_l	<mbstring.h>

Дополнительные сведения о совместимости см. в разделе Совместимость.

Пример

// 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 );
}