Sprintf function in cpp

sprintf_s , _sprintf_s_l , swprintf_s , _swprintf_s_l

Запись форматированных данных в строку. Эти функции являются версиями sprintf , _sprintf_l , swprintf , _swprintf_l , с __swprintf_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 int sprintf_s( char (&buffer)[size], const char *format, . ); // C++ only template 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,35000000000000008) продолжает округляться до 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

Требования

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

Пример. Использование sprintf_s для форматирования данных

// crt_sprintf_s.c // This program uses sprintf_s to format various // data and place them in the string named buffer. // #include 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 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 

Источник

sprintf , _sprintf_l , swprintf , _swprintf , _swprintf_l , __swprintf_l

Запись форматированных данных в строку. Доступны более безопасные версии некоторых из этих функций; См. раздел sprintf_s , _sprintf_s_l , swprintf_s , . _swprintf_s_l Безопасные версии swprintf и _swprintf_l принимают размер буфера в качестве параметра.

Синтаксис

int sprintf( char *buffer, const char *format [, argument] . ); int _sprintf_l( char *buffer, const char *format, _locale_t locale [, argument] . ); int swprintf( wchar_t *buffer, size_t count, const wchar_t *format [, argument]. ); int _swprintf( wchar_t *buffer, const wchar_t *format [, argument]. ); int _swprintf_l( wchar_t *buffer, size_t count, const wchar_t *format, _locale_t locale [, argument] . ); int __swprintf_l( wchar_t *buffer, const wchar_t *format, _locale_t locale [, argument] . ); template int sprintf( char (&buffer)[size], const char *format [, argument] . ); // C++ only template int _sprintf_l( char (&buffer)[size], const char *format, _locale_t locale [, argument] . ); // C++ only 

Параметры

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

count
Максимальное количество символов, которое может хранить эта функция в версии Юникод.

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

argument
Необязательные аргументы

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

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

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

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

Комментарии

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

Функция sprintf не позволяет ограничить число записываемых символов, а значит, код, включающий функцию sprintf , может привести к переполнению буфера. Рассмотрите возможность использования связанной функции _snprintf , которая задает максимальное количество символов для записи buffer в , или используйте для _scprintf определения размера буфера. Кроме того, убедитесь, что format не является строкой, определяемой пользователем.

Начиная с 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,35000000000000008) по-прежнему округляется до 2,4. Округление, выполняемое этими функциями, теперь также учитывает режим округления с плавающей запятой, заданный параметром fesetround . Ранее округление всегда выбирало FE_TONEAREST поведение. Это изменение затрагивает только программы, созданные с помощью Visual Studio 2019 версии 16.2 и более поздних версий. Чтобы использовать устаревшее поведение округления с плавающей запятой, свяжите с legacy_stdio_float_rounding.obj.

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

До стандартизации сигнатуры для swprintf версия, поставляемая в старой библиотеке среды выполнения Microsoft C, которая не принимает параметр число символов. Более старая версия по-прежнему доступна в библиотеке среды выполнения Microsoft C, но она устарела и была переименована _swprintf() в . Для кода, написанного на основе старой сигнатуры, определите _CRT_NON_CONFORMING_SWPRINTFS , который сопоставляет вызовы с swprintf _swprintf . В будущей версии старое поведение может быть удалено, поэтому код необходимо изменить в соответствии с новым стандартным поведением.

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

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

TCHAR.H Обычной	_UNICODE и _MBCS не определены	_MBCS Определенные	_UNICODE Определенные
_stprintf	sprintf	sprintf	_swprintf
_stprintf_l	_sprintf_l	_sprintf_l	__swprintf_l

Требования

Подпрограмма	Обязательный заголовок
sprintf , _sprintf_l
swprintf , _swprintf , _swprintf_l	или

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

Пример. Использование sprintf для форматирования данных

// crt_sprintf.c // compile with: /W3 // This program uses sprintf to format various // data and place them in the string named buffer. #include 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( buffer, " String: %s\n", s ); // C4996 j += sprintf( buffer + j, " Character: %c\n", c ); // C4996 j += sprintf( buffer + j, " Integer: %d\n", i ); // C4996 j += sprintf( buffer + j, " Real: %f\n", fp );// C4996 // Note: sprintf is deprecated; consider using sprintf_s instead printf( "Output:\n%s\ncharacter count = %d\n", buffer, j ); >

Output: String: computer Character: l Integer: 35 Real: 1.732053 character count = 79 

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

// crt_swprintf.c // wide character example // also demonstrates swprintf returning error code #include int main( void ) < wchar_t buf[100]; int len = swprintf( buf, 100, L"%s", L"Hello world" ); printf( "wrote %d characters\n", len ); len = swprintf( buf, 100, L"%s", L"Hello\xffff world" ); // swprintf fails because string contains WEOF (\xffff) printf( "wrote %d characters\n", len ); >

wrote 11 characters wrote -1 characters 

Источник