std::printf, std::fprintf, std::sprintf, std::snprintf

int printf( const char* format, ... );

int fprintf( std::FILE* stream, const char* format, ... );

int sprintf( char* buffer, const char* format, ... );

int snprintf( char* buffer, std::size_t buf_size, const char* format, ... );

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

Если вызов sprintf или snprintf приводит к копированию между перекрывающимися объектами, поведение является неопределённым (например, sprintf(buf, "%s text", buf);).

Параметры

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

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

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

• если P > X ≥ −4, преобразование выполняется со стилем f или F и точностью P − 1 − X.
• иначе, преобразование выполняется со стилем e или E и точностью P − 1.

За исключением запроса альтернативной записи, trailing zeros удаляются, а также десятичная точка, если дробная часть отсутствует. Для бесконечности и не-числовых значений см. примечания.

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

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

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

Хотя %c ожидает аргумент int, безопасно передавать char из-за повышения типа целых чисел, происходящего при вызове функции с переменным числом аргументов.

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

Спецификатор преобразования для записи в память %n — распространенная цель эксплойтов, где строка формата зависит от пользовательского ввода, и не поддерживается семейством функций printf_s с проверкой границ.

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

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

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

Примечания

POSIX определяет, что errno устанавливается при ошибке. Он также определяет дополнительные спецификации преобразования, в частности, поддержку переупорядочивания аргументов (n$ непосредственно после % указывает на n-й аргумент).

Вызов std::snprintf с нулевым buf_size и указателем null для buffer полезен (когда допустимы накладные расходы двойного вызова) для определения необходимого размера буфера для хранения вывода:

auto fmt = "sqrt(2) = %f";
int sz = std::snprintf(nullptr, 0, fmt, std::sqrt(2));
std::vector<char> buf(sz + 1); // note +1 for null terminator
std::sprintf(buf.data(), fmt, std::sqrt(2)); // certain to fit

Пример

#include <cinttypes>
#include <cstdint>
#include <cstdio>
#include <limits>
 
int main()
{
    const char* s = "Hello";
    std::printf("Strings:\n"); // same as std::puts("Strings:");
    std::printf("\t[%10s]\n", s);
    std::printf("\t[%-10s]\n", s);
    std::printf("\t[%*s]\n", 10, s);
    std::printf("\t[%-10.*s]\n", 4, s);
    std::printf("\t[%-*.*s]\n", 10, 4, s);
 
    std::printf("Characters:\t%c %%\n", 'A');
 
    std::printf("Integers:\n");
    std::printf("\tDecimal:    \t%i %d %.6i %i %.0i %+i %i\n",
                                  1, 2,   3, 0,   0,  4,-4);
    std::printf("\tHexadecimal:\t%x %x %X %#x\n",
                                  5,10,10,  6);
    std::printf("\tOctal:      \t%o %#o %#o\n",
                                 10, 10,  4);
 
    std::printf("Floating point:\n");
    std::printf("\tRounding:\t%f %.0f %.32f\n", 1.5, 1.5, 1.3);
    std::printf("\tPadding:\t%05.2f %.2f %5.2f\n", 1.5, 1.5, 1.5);
    std::printf("\tScientific:\t%E %e\n", 1.5, 1.5);
    std::printf("\tHexadecimal:\t%a %A\n", 1.5, 1.5);
    std::printf("\tSpecial values:\t0/0=%g 1/0=%g\n", 0.0/0.0, 1.0/0.0);
 
    std::printf("Variable width control:\n");
    std::printf("\tright-justified variable width: '%*c'\n", 5, 'x');
    int r = std::printf("\tleft-justified variable width : '%*c'\n", -5, 'x');
    std::printf("(the last printf printed %d characters)\n", r);
 
    std::printf("Fixed-width types:\n");
    std::uint32_t val = std::numeric_limits<std::uint32_t>::max();
    std::printf("\tLargest 32-bit value is %" PRIu32 " or %#" PRIx32 "\n",
                                                 val,            val);
}

Strings:
        [     Hello]
        [Hello     ]
        [     Hello]
        [Hell      ]
        [Hell      ]
Characters:        A %
Integers:
        Decimal:            1 2 000003 0  +4 -4
        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
        Special values:        0/0=-nan 1/0=inf
Variable width control:
        right-justified variable width: '    x'
        left-justified variable width : 'x    '
(the last printf printed 41 characters)
Fixed-width types:
        Largest 32-bit value is 4294967295 or 0xffffffff

См. также