| int printf( const char* format, ... ); |
(1) |
|
int fprintf( std::FILE* stream, const char* format, ... ); |
(2) |
|
| int sprintf( char* buffer, const char* format, ... ); |
(3) |
|
int snprintf( char* buffer, std::size_t buf_size, const char* format, ... ); |
(4) |
(начиная с C++11) |
| | |
Извлекает данные из заданных источников, конвертирует их в строковое представление и записывает результат в различные приёмники.
1) Записывает результат в
stdout.
2) Записывает результат в файловый поток stream.
3) Записывает результат в символьную строку buffer
4) Записывает результат в символьную строку buffer, не более buf_size - 1 входных символов. Результирующая символьная строка будет дополнена нулевым символом, если buf_size не равен нулю. Если buf_size равен нулю, ничего записано не будет, и buffer может быть нулевым указателем; возвращаемое значение (количество записанных байт) при этом вычисляется.
| stream
|
—
|
поток выходного файла, в который будет записан результат
|
| buffer
|
—
|
указатель на символьную строку, в которую будет записан результат
|
| buf_size
|
—
|
может быть записано не более buf_size - 1 символов плюс нулевой символ
|
| format
|
—
|
указатель на завершающуюся нулем строку, определяющую, как интерпретировать данные
Строка форматирования состоит из печатных и пробельных символов (кроме %), без изменения выводимых в выходной поток, и спецификаторов форматирования. Структура спецификатора:
-
- (необязательно) один или несколько флагов, которые изменяют поведение форматирования:
-
-: выравнивание по левому краю внутри поля заданной ширины (по умолчанию по правому краю)
-
+: принудительная печать знака + с положительными значениями (по умолчанию знаком дополняются только отрицательные значения)
- пробел: не дополненные знаком или отсутствующие численные значения дополняются слева пробелом. Игнорируется, если присутствует флаг
+.
-
#: выполнится альтернативное форматирование. См. таблицу ниже для подробностей: если альтернативное форматирование не определено, поведение не определено (UB).
-
0: при печати чисел в поле заданной ширины заполнение пустоты идёт нулями вместо пробелов. Для целых чисел флаг игнорируется, если задано количество выводимых знаков (точность). При печати не чисел вызывает неопределённое поведение (UB). Флаг игнорируется, если присутствует флаг -.
- (необязательно) целое число, означающее минимальную ширину поля, или
*. Свободное пространство в поле по умолчанию заполняется пробелами, выравнивание по правому краю. При использовании * ширина поля задаётся дополнительным аргументом типа int. Отрицательное значение ширины эквивалентно применению дополнительно флага -.
(Замечание: задаётся минимальная ширина поля, форматируемое значение никогда не обрезается.)
- (необязательно)
. с целым числом, * или просто .. Число определяет точность. При использовании * точность задаётся дополнительным аргументом типа int. Просто . устанавливает нулевую точность. См. таблицу ниже для подробностей о действии точности на вывод.
- (необязательно)модификатор размера: определяет размер аргумента
- спецификатор формата вывода
Доступны следующие спецификаторы формата:
| Спецификатор
|
Описание
|
Флаг размера
|
|
|
hh
|
h
|
(нет)
|
l
|
ll
|
j
|
z
|
t
|
L
|
%
|
выводит символ %. Полный спецификатор формата %%.
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
c
|
- выводит символ
Аргумент сначала приводится к unsigned char.
Если использован флаг l, аргумент сначала конвертируется в строку, как при использовании %ls с аргументом типа wchar_t[2].
|
Н/Д
|
Н/Д
|
|
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
s
|
- выводит строку
Аргумент должен быть указателем на первый элемент массива символов.
Точность определяет максимальное количество выведенных байт. Если точностьне задана, выводит всё до первого встреченного нулевого символа (не включая его).
Если использован флаг l, аргумент должен быть указателем на первый элемент массива wchar_t, который преобразуется в массив char, как при вызове wcrtomb.
|
Н/Д
|
Н/Д
|
|
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
d
i
|
- форматирует знаковое целое как десятичное число в виде [-][0-9]*
Точность определяет минимальное количество выводимых знаков. По умолчанию 1.
Если форматированное значение и точность являются 0, ничего не выводится.
|
|
|
|
|
|
|
|
|
Н/Д
|
o
|
- форматирует беззнаковое целое как восьмеричное число в виде [0-7]*
Точность определяет минимальное количество выводимых знаков. По умолчанию 1.
Если форматированное значение и точность являются 0, ничего не выводится.
Альтернативная реализация: при необходимости точность повышается, чтобы добавить ноль слева. Таким образом, если форматированное значение и точность являются 0, выводится 0.
|
|
|
|
|
|
|
|
unsigned version of ptrdiff_t |
Н/Д
|
x
X
|
- форматирует беззнаковое целое как шестнадцатеричное число в виде [0-F]*
Формат x использует буквы abcdef.
Формат X использует буквы ABCDEF.
Точность определяет минимальное количество выводимых знаков. По умолчанию 1.
Если форматированное значение и точность являются 0, ничего не выводится.
Альтернативная реализация: ненулевые значения выводятся с приставкой 0x или 0X соответственно.
|
Н/Д
|
u
|
- форматирует беззнаковое целое как десятичное число в виде [0-9]*
Точность определяет минимальное количество выводимых знаков. По умолчанию 1.
Если форматированное значение и точность являются 0, ничего не выводится.
|
Н/Д
|
f
F
|
- форматирует число с плавающей запятой в виде [-]d.d, где d - произвольные десятичные числа
Точность определяет минимальное количество выводимых знаков после запятой. По умолчанию 6.
Альтернативная реализация: выводит десятичную точку даже если число целое.
Форматирование бесконечности и NaN см. в примечаниях.
|
Н/Д
|
Н/Д
|
|
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
|
e
E
|
- форматирует число с плавающей запятой в экспоненициальной форме: AeB == A * pow (10, B)
Формат e использует букву e: AeB.
Формат E использует букву E: AEB.
Экспонента содержит не менее 2 цифр.
Точность определяет минимальное количество выводимых знаков после запятой. По умолчанию 6.
Альтернативная реализация: выводит десятичную точку даже если мантисса целая.
Форматирование бесконечности и NaN см. в примечаниях.
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
a
A
|
- форматирует число с плавающей запятой в шестнадцаеричной экспоненциальной форме
Формат a выводит [-]0xh.hhhp±d.
Формат A выводит [-]0Xh.hhhP±d.
Если число не нормализовано, первой цифрой выводится 0.
Если число 0, экпонента тоже 0.
Точность определяет минимальное количество выводимых знаков после запятой. По умолчанию выбирается значение, достаточное для полного вывода.
Альтернативная реализация: выводит десятичную точку даже если мантисса целая.
Форматирование бесконечности и NaN см. в примечаниях.
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
g
G
|
- форматирует число с плавающей запятой в десятичной или десятичной экспоненциальной форме в зависимости от значения и точности
Формат g выводит в формате e или f.
Формат G выводит в формате E или F.
Пусть P - параметр точности вывода. 0; в остальных случаях, если P. Если точность числа P, а экспонента при выводе в десятичном формате X, то:
- Если P> X ≥ -4, используется формат f / F с точностью -1 - X.
- Иначе используется формат e / E с точностью P - 1
Альтернативная реализация: выводит десятичную точку даже если мантисса целая; нули в конце не убираются.
Форматирование бесконечности и NaN см. в примечаниях.
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
n
|
- возвращает число символов, записанных данным вызовом функции к моменту
%n.
Результат записывается в переменную, на которую указывает параметр. Данный спецификатор не допускает использования каких-либо флагов и модификаторов.
|
|
|
|
|
|
|
|
|
Н/Д
|
p
|
- выводит указатель в зависящем от реализации виде.
|
Н/Д
|
Н/Д
|
void*
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
|
Формат чисел с плавающей запятой выводит бесконечность как inf или infinity в зависимости от реализации.
NaN преобразуется в nan или nan(char_sequence) в зависимости от реализации.
Форматы F, E, G, A выводят INF, INFINITY, NAN.
Несмотря на то, что %c принимает параметр типа int, передавать char безопасно из-за преобразования к int при разборе аргументов форматирования.
Корректные преобразования для типов фиксированного размера (int8_t и прочих) объявлены в <cinttypes>(C++) или<inttypes.h> (C) (вызов PRIdMAX, PRIuMAX, и прочих соответствует %jd, %ju и т.д.).
Записывающий спецификатор %n - типичная цель для атак в случаях, когда строка формата зависит от пользовательского ввода. Не поддерживается семейством функций printf_s.
Каждый спецификатор формата происводит вычисление своего аргумента в момент печати. Это позволяет вызывать %n несколько раз и выводить результат действия предыдущего вызова %n в этом же вызове функции.
Неправильный спецификатор формата вызывает неопределённое поведение (UB).
|
|
| ...
|
—
|
аргументы, определяющие данные для печати. Если тип какого-либо из аргументов не совпадает с указанным в format или аргументов меньше, чем указано в format, поведение не определено (undefined behaviour). Если агрументов больше, чем указано, неиспользованные агрументы будут вычислены и проигнорированы
|
[править] Возвращаемое значение
1-2) Количество записанных символов при успешной операции либо отрицательное значение при ошибке
3) Количество записанных символов (не включая последний нулевой) при успешной операции либо отрицательное значение при ошибке
4) Количество записанных символов (не включая последний нулевой) при успешной операции либо отрицательное значение при ошибке. Так как размер целевого буфера buf_size, успешную операцию (запись вместе с нулевым символом / бездействие) означают возвращаемые значения от 0 до buf_size - 1.
По стандарту POSIX при ошибке её код записывается в errno. Также, стандарт содержит дополнительные спецификаторы форматирования, в частности для перестановки аргументов.
Вызов std::snprintf с нулевым размером буфера и нулевым указателем на буфер может использоваться для определения требуемого размера буфера при печати:
const char *fmt = "sqrt(2) = %f";
int sz = std::snprintf(nullptr, 0, fmt, std::sqrt(2));
std::vector<char> buf(sz + 1); // sz символов + нулевой завершающий
std::snprintf(&buf[0], buf.size(), fmt, std::sqrt(2));
#include <cstdio>
int main()
{
std::printf("Strings:\n");
}Вывод:
Strings:
. Hello.
.Hello .
. Hello.
Characters: A %
Integers
Decimal: 1 2 000003 0 +4 4294967295
Hexadecimal: 5 a A 0x6
Octal: 12 012 04
Floating point
Rounding: 1.500000 2 1.30000000000000004440892098500626
Padding: 01.50 1.50 1.50
Scientific: 1.500000E+00 1.500000e+00
Hexadecimal: 0x1.8p+0 0X1.8P+0
|
|
производит форматированный вывод в stdout, файловый поток или буфер
(функция) [править]
|
|
|
записывает символьную строку в файловый поток
(функция) [править]
|
|
|
производит форматированный ввод из stdin, файлового потока или буфера
(функция) [править]
|
|
|
