Функция sprintf и swprintf

Функции производят форматированный вывод в символьную строку (функция библиотеки С и С++).

Синтаксис

Параметры

Указатель на строку, в которую осуществляется вывод.

Максимальное число символов, которое сохраняется в версии Unicode этой функции.

Переменное число параметров (дополнительные параметры).

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

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

Функция sprintf возвращает число байтов, сохраненное в буфере, не считая символ завершающего нуля. Функция swprintf возвращает число "широких " символов, сохраненных в буфере, не считая "широкого " завершающегося нулевого символа.

Замечания

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

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

Функция swprintf - широкосимвольная версия sprintf (для Unicode); format - широкосимвольная строка. Функции swprintf и sprintf во всем остальном ведут себя тождественно.

Параметр format состоит из обычных символов, последовательностей escape, и (если параметры следуют за параметром format) спецификаций формата. Обычные символы и последовательности escape копируются в строке в порядке их поступления. Например, строка

Спецификации формата всегда начинаются со знака процента (%) и читается слева направо. Когда функция sprintf встречается с первой спецификацией формата (если она есть), то преобразует значение первого параметра после format и выводит его соответственно. Вторая спецификация формата заставляет второй параметр быть преобразованным и выведенным и так далее. Если имеется больше параметров, чем есть их спецификаций, дополнительные параметры игнорируются. Результаты не определяются, если недостаточно параметров для всех спецификаций формата.

Демонстрационный пример

Смотри также

Требования

Процедуры	Требуется заголовочный файл	Совместимость
sprintf	<stdio.h>	ANSI, Win 98, Win Me, Win NT, Win 2000, Win XP
swprintf	<stdio.h> или <wchar.h>	ANSI, Win 98, Win Me, Win NT, Win 2000, Win XP

Дополнительную информацию о совместимости см. в статье Совместимость в главе Введение.

Библиотеки

Все версии библиотек времени исполнения программы C.

Функции sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l, swprintf и _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_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 <size_t size>
int sprintf(
   char (&buffer)[size],
   const char *format [,
      argument] ... 
); // только для C++
template <size_t size>
int _sprintf_l(
   char (&buffer)[size],
   const char *format,
   locale_t locale [,
      argument] ... 
); // только для C++
template <size_t size>
int swprintf(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format [,
      argument]...
); // только для C++
template <size_t size>
int _swprintf_l(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format,
   locale_t locale [,
      argument] ... 
); // только для C++

Параметры

Максимальное число символов, которое хранится в версии Unicode этой функции.

Параметр строки управления форматом. Это дополнительные (необязательные) параметры.

Для получения дополнительной информации, см. статью Спецификации формата.

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

Возвращаемых значений нет

Замечания

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

В Visual C++ 2005, функция swprintf приведена в соответствие со Стандартом C Международной Организации по Стандартизации (ISO), который требует второго параметра count, типа size_t. Чтобы заставить действовать старое нестандартное поведение функции, определите флажок _CRT_NON_CONFORMING_SWPRINTFS. В будущей версии может быть удалено старое поведение функции, таким образом код должен меняться для использования нового соответствующего стандарту поведения.

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

Унифицированно-текстовые стандартные отображения

Требования

СтандартныйTCHAR.H	_UNICODE & _MBCS не определен	_MBCS определен	_UNICODE определен
_stprintf	sprintf	sprintf	swprintf
_stprintf_l	_sprintf_l	_sprintf_l	__swprintf_l

Процедура	Требуется заголовочный файл
sprintf, _sprintf_l	<stdio.h>
swprintf, _swprintf_l	<stdio.h> или <wchar.h>

Для дополнительной информации о совместимости, см. статью Совместимость во Введении.

Пример

// crt_sprintf.c
// компиляция с ключом: /W3
// Эта программа использует sprintf, чтобы форматировать различные
// данные и поместить их в строку, названную буфером.

#include <stdio.h>

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

   // Форматирование и распечатка различных данных: 
   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
   // Обратите внимание: функцию sprintf не рекомендуется применять; вместо неё используйте лучше sprintf_s

   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
// пример с широкими символами
// также демонстрирует возвращение swprintf кода ошибки
#include <stdio.h>

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 завершается ошибкой, потому что строка содержит WEOF (\xffff)
   printf( "wrote %d characters\n", len );
}

wrote 11 characters
wrote -1 characters

Эквивалент в .NET Framework

Смотри также

Библиотеки

Все версии библиотек времени исполнения программы C.