sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l

Запись форматированных данных в строку. Эти функции — это версии sprintf, __swprintf_l_swprintf_lswprintf_sprintf_lс улучшениями безопасности, как описано в функциях безопасности в CRT.

Синтаксис

int sprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   const char *format,
   ...
);
int _sprintf_s_l(
   char *buffer,
   size_t sizeOfBuffer,
   const char *format,
   _locale_t locale,
   ...
);
int swprintf_s(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   const wchar_t *format,
   ...
);
int _swprintf_s_l(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   const wchar_t *format,
   _locale_t locale,
   ...
);
template <size_t size>
int sprintf_s(
   char (&buffer)[size],
   const char *format,
   ...
); // C++ only
template <size_t size>
int swprintf_s(
   wchar_t (&buffer)[size],
   const wchar_t *format,
   ...
); // C++ only

Параметры

buffer
Место хранения выходных данных

sizeOfBuffer
Наибольшее число символов для хранения.

format
Строка управления форматом

...
Необязательные аргументы для форматирования

locale
Используемый языковой стандарт.

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

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

Число записанных символов или -1, если произошла ошибка. Если buffer или format является пустым указателем, sprintf_s и swprintf_s возвращают значение -1 и задают errno равным EINVAL.

sprintf_s возвращает число байтов, сохраненных в bufferбез учета завершающего символа null. swprintf_s возвращает число расширенных символов, сохраненных в buffer, без учета завершающего расширенного символа null.

Замечания

Функция sprintf_s форматирует и сохраняет набор символов и значений в buffer. Каждый argument (если он есть) преобразуется и выводится согласно соответствующей спецификацией формата в format. Формат состоит из обычных символов и имеет те же форму и функциональные возможности, что и аргумент format для printf. После последнего написанного символа добавляется символ null. Если копирование производится между перекрывающимися строками, поведение не определено.

Основное различие между sprintf_s и sprintf заключается в том, что sprintf_s проверяет строку форматирования на наличие допустимых символов форматирования, тогда как sprintf только проверяет, является ли строка формата или буфер указателем NULL . Если любой из проверка завершается ошибкой, вызывается обработчик недопустимых параметров, как описано в разделе "Проверка параметров". Если выполнение может быть продолжено, функция возвращает -1 и устанавливает errno в значение EINVAL.

Другое основное различие между sprintf_s и sprintf в том, что sprintf_s принимает параметр длины, определяющий размер буфера вывода в символах. Если буфер слишком мал для форматированного текста, включая завершающий символ null, то ему присваивается пустая строка путем размещения символа null в buffer[0]и вызывается обработчик недопустимого параметра. В отличие от _snprintf, sprintf_s гарантирует, что буфер будет завершен символом null (если размер буфера не равен нулю).

swprintf_s — это двухбайтовая версия sprintf_s; аргументы указателя для swprintf_s представляют собой двухбайтовые строки. Обнаружение ошибок swprintf_s кодирования может отличаться от обнаружения sprintf_s. Версии этих функций с суффиксом _l идентичны за исключением того, что они используют переданный параметр языкового стандарта вместо языкового стандарта текущего потока.

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

Существуют версии sprintf_s этого предложения более контроль над тем, что происходит, если буфер слишком мал. Дополнительные сведения см. в разделе _snprintf_s, _snprintf_s_l, _snwprintf_s. _snwprintf_s_l

Важно!

Начиная с Windows 10 версии 2004 (сборка 19041), printf семейство функций выводит точно представленные числа с плавающей запятой в соответствии с правилами IEEE 754 для округления. В предыдущих версиях Windows точно представленные числа с плавающей запятой, заканчивающиеся на "5", всегда округлялись. IEEE 754 утверждает, что они должны округлиться до ближайшей даже цифры (также известной как "Округление банкира"). Например, оба printf("%1.0f", 1.5) и printf("%1.0f", 2.5) должны округлиться до 2. Ранее 1,5 округляет до 2 и 2,5 округления до 3. Это изменение влияет только на точно представленные числа. Например, 2.35 (который при представлении в памяти приближается к 2,3500000000000000008) продолжает округляется до 2,4. Округление, выполняемое этими функциями, теперь также учитывает режим округления с плавающей запятой, заданный fesetround. Ранее округление всегда выбрало FE_TONEAREST поведение. Это изменение влияет только на программы, созданные с помощью Visual Studio 2019 версии 16.2 и более поздних версий. Чтобы использовать устаревшее поведение округления с плавающей запятой, свяжите ссылку с "legacy_stdio_float_rounding.obj".

Сопоставления подпрограмм универсального текста

Подпрограмма TCHAR.H	_UNICODE и _MBCS не определен	_MBCS Определенные	_UNICODE Определенные
_stprintf_s	sprintf_s	sprintf_s	swprintf_s
_stprintf_s_l	_sprintf_s_l	_sprintf_s_l	_swprintf_s_l

Требования

Маршрут	Обязательный заголовок
sprintf_s, _sprintf_s_l	C: <stdio.h> C++: <cstdio или <stdio.h>>
swprintf_s, _swprintf_s_l	C: <stdio.h> или <wchar.h> C++: <cstdio, cwchar>, <<stdio.h>> или <wchar.h>

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

Пример. Форматирование данных с помощью sprintf_s

// crt_sprintf_s.c
// This program uses sprintf_s to format various
// data and place them in the string named buffer.
//

#include <stdio.h>

int main( void )
{
   char  buffer[200], s[] = "computer", c = 'l';
   int   i = 35, j;
   float fp = 1.7320534f;

   // Format and print various data:
   j  = sprintf_s( buffer, 200,     "   String:    %s\n", s );
   j += sprintf_s( buffer + j, 200 - j, "   Character: %c\n", c );
   j += sprintf_s( buffer + j, 200 - j, "   Integer:   %d\n", i );
   j += sprintf_s( buffer + j, 200 - j, "   Real:      %f\n", fp );

   printf_s( "Output:\n%s\ncharacter count = %d\n", buffer, j );
}

Output:
   String:    computer
   Character: l
   Integer:   35
   Real:      1.732053

character count = 79

Пример: обработка кода ошибки

// crt_swprintf_s.c
// wide character example
// also demonstrates swprintf_s returning error code
#include <stdio.h>

int main( void )
{
   wchar_t buf[100];
   int len = swprintf_s( buf, 100, L"%s", L"Hello world" );
   printf( "wrote %d characters\n", len );
   len = swprintf_s( buf, 100, L"%s", L"Hello\xffff world" );
   // swprintf_s fails because string contains WEOF (\xffff)
   printf( "wrote %d characters\n", len );
}

wrote 11 characters
wrote -1 characters

См. также

Потоковый ввод-вывод
fprintf, _fprintf_l, fwprintf, _fwprintf_l
printf, _printf_l, wprintf, _wprintf_l
sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
scanf, _scanf_l, wscanf, _wscanf_l
sscanf, _sscanf_l, swscanf, _swscanf_l
Функции vprintf