Namespaces
Variants

std:: vprintf, std:: vfprintf, std:: vsprintf, std:: vsnprintf

From cppreference.net
< cpp ‎ | io ‎ | c
C++
Input/output library
C-style I/O
Определено в заголовочном файле <cstdio>
int vprintf ( const char * format, std :: va_list vlist ) ;
(1)
int vfprintf ( std:: FILE * stream, const char * format, std :: va_list vlist ) ;
(2)
int vsprintf ( char * buffer, const char * format, std :: va_list vlist ) ;
(3)
int vsnprintf ( char * buffer, std:: size_t buf_size, const char * format, std :: va_list vlist ) ;
(4) (начиная с C++11)

Загружает данные из местоположений, определенных vlist , преобразует их в эквиваленты символьных строк и записывает результаты в различные приемники.

1) Записывает результаты в stdout .
2) Записывает результаты в файловый поток stream .
3) Записывает результаты в строку символов buffer .
4) Записывает результаты в строку символов buffer . Записывается не более buf_size - 1 символов. Результирующая строка символов будет завершена нулевым символом, если только buf_size не равен нулю. Если buf_size равен нулю, ничего не записывается и buffer может быть нулевым указателем, однако возвращаемое значение (количество байтов, которое было бы записано без учёта нулевого терминатора) всё равно вычисляется и возвращается.

Содержание

Параметры

stream - выходной файловый поток для записи
buffer - указатель на строку символов для записи
buf_size - максимальное количество символов для записи
format - указатель на строку символов с нулевым завершителем, определяющую способ интерпретации данных
vlist - список переменных аргументов, содержащий данные для вывода

Строка формата состоит из обычных символьных байтов (кроме % ), которые копируются без изменений в выходной поток, и спецификаций преобразования. Каждая спецификация преобразования имеет следующий формат:

  • вводный % символ.
  • (необязательно) один или несколько флагов, изменяющих поведение преобразования:
  • - : результат преобразования выравнивается по левому краю поля (по умолчанию выравнивается по правому краю).
  • + : знак знаковых преобразований всегда добавляется перед результатом преобразования (по умолчанию результат предваряется минусом только когда он отрицательный).
  • space : если результат знакового преобразования не начинается с символа знака или является пустым, перед результатом добавляется пробел. Игнорируется если присутствует флаг + .
  • # : альтернативная форма преобразования выполняется. Смотрите таблицу ниже для точных эффектов, иначе поведение не определено.
  • 0 : для целочисленных и преобразований чисел с плавающей точкой, ведущие нули используются для заполнения поля вместо space символов. Для целых чисел игнорируется если точность явно указана. Для других преобразований использование этого флага приводит к неопределенному поведению. Игнорируется если присутствует флаг - .
  • (необязательно) целочисленное значение или * , определяющее минимальную ширину поля. Результат дополняется символами пробела (по умолчанию) при необходимости слева при выравнивании по правому краю или справа при выравнивании по левому краю. В случае использования * , ширина задается дополнительным аргументом типа int , который указывается перед аргументом для преобразования и аргументом, задающим точность, если он предоставлен. Если значение аргумента отрицательное, это приводит к указанию флага - и положительной ширине поля (Примечание: Это минимальная ширина: значение никогда не усекается.).
  • (необязательно) . за которым следует целое число или * , либо ничего, что определяет точность преобразования. В случае, когда используется * , точность задается дополнительным аргументом типа int , который указывается перед преобразуемым аргументом, но после аргумента, задающего минимальную ширину поля, если таковой указан. Если значение этого аргумента отрицательное, оно игнорируется. Если не указано ни число, ни * , точность принимается равной нулю. Смотрите таблицу ниже для точного воздействия точности .
  • (необязательный) модификатор длины который указывает размер аргумента (в сочетании со спецификатором формата преобразования он определяет тип соответствующего аргумента).
  • спецификатор формата преобразования.

Доступны следующие спецификаторы формата:

Спецификатор
преобразования 		Объяснение Ожидаемый
тип аргумента
Модификатор длины→ hh h нет l ll j z t L
Доступно только с C++11→ Да Да Да Да Да
% Выводит символ % . Полная спецификация преобразования должна быть %% . N/A N/A N/A N/A N/A N/A N/A N/A N/A
c

Записывает один символ .

  • Аргумент сначала преобразуется в unsigned char .
  • Если используется модификатор l , аргумент сначала преобразуется в строку символов, как если бы использовался %ls с аргументом wchar_t [ 2 ] .
N/A N/A
int
std::wint_t
N/A N/A N/A N/A N/A
s

Записывает строку символов .

  • Аргумент должен быть указателем на начальный элемент массива символов.
  • Точность определяет максимальное количество байт для записи. Если Точность не указана, записываются все байты до первого нулевого терминатора (исключая его).
  • Если используется спецификатор l , аргумент должен быть указателем на начальный элемент массива wchar_t , который преобразуется в массив char как при вызове std::wcrtomb с обнулённым состоянием преобразования.
N/A N/A
char *
wchar_t *
N/A N/A N/A N/A N/A
d
i

Преобразует знаковое целое число в десятичное представление [-]dddd .

  • Точность определяет минимальное количество отображаемых цифр. Точность по умолчанию равна 1 .
  • Если и преобразованное значение, и точность равны ​ 0 ​ , преобразование не выводит символов.
  • Для модификатора z ожидаемый тип аргумента - знаковая версия std::size_t .
signed char
short
int
long
long long
※
N/A
o

Преобразует целое число без знака в восьмеричное представление oooo .

  • Точность определяет минимальное количество отображаемых цифр. Точность по умолчанию равна 1 .
  • Если и преобразованное значение, и точность равны ​ 0 ​ , преобразование не выводит символов.
  • В альтернативной реализации точность увеличивается при необходимости для записи одного ведущего нуля. В этом случае, если и преобразованное значение, и точность равны ​ 0 ​ , записывается один ​ 0 ​ .
unsigned char
unsigned short
unsigned int
unsigned long
unsigned long long
беззнаковая версия std::ptrdiff_t
Н/П
x
X

Преобразует целое число без знака в шестнадцатеричное представление hhhh .

  • Для преобразования x используются буквы abcdef .
  • Для преобразования X используются буквы ABCDEF .
  • Точность определяет минимальное количество отображаемых цифр. Точность по умолчанию равна 1 .
  • Если и преобразованное значение, и точность равны ​ 0 ​ , преобразование не выводит символов.
  • В альтернативной реализации к результатам добавляется префикс 0x или 0X , если преобразованное значение ненулевое.
N/A
u

Преобразует беззнаковое целое число в десятичное представление dddd .

  • Точность определяет минимальное количество отображаемых цифр.
  • Точность по умолчанию равна 1 .
  • Если и преобразованное значение, и точность равны ​ 0 ​ , преобразование не выдает символов.
N/A
f
F (C++11)

Преобразует число с плавающей запятой в десятичную запись в формате [-]ddd.ddd .

  • Точность определяет точное количество цифр, отображаемых после десятичного разделителя.
  • Точность по умолчанию составляет 6 .
  • В альтернативной реализации десятичный разделитель записывается даже если за ним не следуют цифры.
  • Для стиля преобразования бесконечности и не-числа смотрите примечания .
N/A N/A
double
double (C++11)
N/A N/A N/A N/A
long double
e
E

Преобразует число с плавающей точкой в экспоненциальную десятичную запись.

  • Для стиля преобразования e используется формат [-]d.ddd  e ±dd .
  • Для стиля преобразования E используется формат [-]d.ddd  E ±dd .
  • Экспонента содержит как минимум две цифры, дополнительные цифры используются только при необходимости.
  • Если значение равно ​ 0 ​ , экспонента также равна ​ 0 ​ .
  • Точность определяет точное количество цифр, отображаемых после десятичного разделителя.
  • Точность по умолчанию составляет 6 .
  • В альтернативной реализации десятичный разделитель записывается даже если после него не следует цифр.
  • Для преобразования бесконечности и не-числа смотрите примечания .
N/A N/A N/A N/A N/A N/A
a
A

(C++11)

Преобразует число с плавающей запятой в шестнадцатеричную экспоненциальную запись.

  • Для стиля преобразования a используется формат [-]  0x h.hhh  p ±d .
  • Для стиля преобразования A используется формат [-]  0X h.hhh  P ±d .
  • Первая шестнадцатеричная цифра не равна 0 , если аргумент является нормализованным числом с плавающей запятой.
  • Если значение равно ​ 0 ​ , экспонента также равна ​ 0 ​ .
  • Точность определяет точное количество цифр, отображаемых после символа шестнадцатеричной точки.
  • Точность по умолчанию достаточна для точного представления значения.
  • В альтернативной реализации символ десятичной точки записывается, даже если после него не следует цифр.
  • Для преобразования бесконечности и не-числа смотрите примечания .
N/A N/A N/A N/A N/A N/A
g
G

Преобразует число с плавающей точкой в десятичную запись или запись с десятичным экспоненциальным представлением в зависимости от значения и точности .

  • Для стиля преобразования g будет выполнено преобразование со стилем e или f .
  • Для стиля преобразования G будет выполнено преобразование со стилем E или f (until C++11) F (since C++11) .
  • Пусть P равно точности, если она ненулевая, 6 если точность не указана, или 1 если точность равна ​ 0 ​ . Тогда, если преобразование со стилем E будет иметь экспоненту X :
    • Если P > X ≥ −4 , преобразование выполняется со стилем f или F (since C++11) и точностью P − 1 − X .
    • В противном случае преобразование выполняется со стилем e или E и точностью P − 1 .
  • Если не запрошено альтернативное представление , конечные нули удаляются, также удаляется символ десятичной точки, если не осталось дробной части.
  • Для преобразования бесконечности и не-числа смотрите примечания .
N/A N/A N/A N/A N/A N/A
n

Возвращает количество символов, записанных на данный момент этим вызовом функции.

  • Результат записывается в значение, на которое указывает аргумент.
  • Спецификатор не может содержать никаких флагов , ширины поля или точности .
  • Для модификатора z ожидаемый тип аргумента - S * , где S - это знаковая версия std:: size_t .
signed char *
short *
int *
long *
long long *
※
N/A
p

Выводит определяемую реализацией последовательность символов, определяющую указатель .

N/A N/A
void *
N/A N/A N/A N/A N/A N/A
Примечания

Функции преобразования чисел с плавающей точкой преобразуют бесконечность в inf или infinity . Какой именно вариант используется, определяется реализацией.

Не-число (NaN) преобразуется в nan или nan( char_sequence ) . Какой именно вариант используется, определяется реализацией.

Преобразования F , E , G , A выводят INF , INFINITY , NAN вместо этого.

Спецификатор преобразования, используемый для вывода char , unsigned char , signed char , short и unsigned short , ожидает продвинутые типы стандартных продвижений аргументов , но перед выводом его значение будет преобразовано в char , unsigned char , signed char , short и unsigned short . Безопасно передавать значения этих типов из-за продвижения, которое происходит при вызове вариативной функции.

Правильные спецификаторы преобразования для типов символов фиксированной ширины ( std::int8_t и т.д.) определены в заголовочном файле <cinttypes> (хотя PRIdMAX , PRIuMAX и т.д. являются синонимами для %jd , %ju и т.д.).

Спецификатор преобразования с записью в память %n является частой целью атак безопасности, когда строки формата зависят от пользовательского ввода.

Существует точка следования после действия каждого спецификатора преобразования; это позволяет сохранять несколько результатов %n в одной переменной или, как крайний случай, выводить строку, измененную предыдущим %n в том же вызове.

Если спецификация преобразования неверна, поведение не определено.

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

1-3) Количество записанных символов при успешном выполнении или отрицательное значение при возникновении ошибки.
4) Количество записанных символов в случае успеха или отрицательное значение при ошибке. Если результирующая строка обрезается из-за ограничения buf_size , функция возвращает общее количество символов (не включая завершающий нулевой байт), которое было бы записано, если бы ограничение не было наложено.

Примечания

Все эти функции вызывают va_arg как минимум один раз, значение arg становится неопределённым после возврата. Эти функции не вызывают va_end , и это должно быть выполнено вызывающей стороной.

Пример

Запустить этот код 
#include <cstdarg>
#include <cstdio>
#include <ctime>
#include <vector>
void debug_log(const char *fmt, ...)
{
    std::time_t t = std::time(nullptr);
    char time_buf[100];
    std::strftime(time_buf, sizeof time_buf, "%D %T", std::gmtime(&t));
    std::va_list args1;
    va_start(args1, fmt);
    std::va_list args2;
    va_copy(args2, args1);
    std::vector<char> buf(1 + std::vsnprintf(nullptr, 0, fmt, args1));
    va_end(args1);
    std::vsnprintf(buf.data(), buf.size(), fmt, args2);
    va_end(args2);
    std::printf("%s [debug]: %s\n", time_buf, buf.data());
}
int main()
{
    debug_log("Logging, %d, %d, %d", 1, 2, 3);
}

Вывод: 

04/13/15 15:09:18 [debug]: Logging, 1, 2, 3

Смотрите также

(C++11)
выводит форматированные данные в stdout , файловый поток или буфер
(функция)
(C++11) (C++11) (C++11)
считывает форматированные данные из stdin , файлового потока или буфера
используя список переменных аргументов
(функция)
(C++23)
выводит в поддерживающий Unicode stdout или файловый поток, используя type-erased представление аргументов
(функция)
(C++23)
выводит в stdout или файловый поток, используя type-erased представление аргументов
(функция)
Документация C для vprintf , vfprintf , vsprintf , vsnprintf