std::format — cppreference.com

Материал из cppreference.com

Определено в заголовочном файле `<format>`
`template< class... Args > std::string format( std::format_string<Args...> fmt, Args&&... args );`	(1)	(начиная с C++20)
`template< class... Args > std::wstring format( std::wformat_string<Args...> fmt, Args&&... args );`	(2)	(начиная с C++20)
`template< class... Args > std::string format( const std::locale& loc, std::format_string<Args...> fmt, Args&&... args );`	(3)	(начиная с C++20)
`template< class... Args > std::wstring format( const std::locale& loc, std::wformat_string<Args...> fmt, Args&&... args );`	(4)	(начиная с C++20)

Форматирует args в соответствии со строкой формата fmt и возвращает результат в виде строки. Если присутствует, loc используется для форматирования, зависящего от локали.

1) Эквивалентно return std::vformat(fmt.get(), std::make_format_args(args...));

2) Эквивалентно return std::vformat(fmt.get(), std::make_wformat_args(args...));

3) Эквивалентно return std::vformat(loc, fmt.get(), std::make_format_args(args...));

4) Эквивалентно return std::vformat(loc, fmt.get(), std::make_wformat_args(args...));

Поведение не определено, если std::formatter<Ti, CharT> не соответствует требованиям BasicFormatter для любого Ti в Args (как того требуют std::make_format_args и std::make_wformat_args), где CharT это char для перегрузок (1,3), wchar_t для перегрузок (2,4).

Параметры

fmt

—

объект, представляющий строку формата. Строка формата состоит из

обычных символов (кроме { и }), которые копируются в вывод без изменений,
управляющих последовательностей {{ и }}, которые заменяются на { и } соответственно в выводе, и
заменяемых полей.

Каждое поле замены имеет следующий формат:


`{` идентификатор-аргумента (необязательно) `}`	(1)

`{` идентификатор-аргумента (необязательно) `:` спецификатор-формата `}`	(2)

1) поле замены без указания формата

2) поле замены со спецификацией формата

идентификатор-аргумента	—	указывает индекс аргумента в `args`, значение которого должно использоваться для форматирования; если он опущен, аргументы используются по порядку. идентификаторы-аргументов в строке формата должны присутствовать все или быть опущены. Смешение ручной и автоматической индексации является ошибкой.
спецификатор-формата	—	спецификация формата, определённая специализацией std::formatter для соответствующего аргумента.

Для базовых типов и стандартных строковых типов спецификация формата интерпретируется как спецификация стандартного формата.
Для типов chrono спецификация формата интерпретируется как спецификация формата chrono.
Для std::thread::id спецификация формата интерпретируется как спецификация формата идентификатора потока.
Для других форматируемых типов спецификация формата определяется определяемыми пользователем специализациями formatter.

args... — аргументы для форматирования

loc — std::locale используется для форматирования, зависящего от локали

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

Строковый объект, содержащий форматированный результат.

Исключения

Генерирует std::bad_alloc при ошибке выделения памяти. Также распространяет исключение, выданное любым форматером.

Примечание

Предоставление большего количества аргументов, чем требуется для строки формата, не является ошибкой:

std::format("{} {}!", "Привет", "мир", "что-то"); // OK, производит "Привет мир!"

Начиная с P2216R3, если строка формата не является константным выражением, это ошибка. В этом случае можно использовать std::vformat.

std::string f(std::string_view runtime_format_string) {
    // return std::format(runtime_format_string, "foo", "bar"); // ошибка
    return std::vformat(runtime_format_string, std::make_format_args("foo", "bar")); // ok
}

Пример

#include <format>
#include <iostream>
#include <string>
#include <string_view>

template <typename... Args>
std::string dyna_print(std::string_view rt_fmt_str, Args&&... args) {
    return std::vformat(rt_fmt_str, std::make_format_args(args...));
}

int main() {
    std::cout << std::format("Привет {}!\n", "мир");

    std::string fmt;
    for (int i{}; i != 3; ++i) {
        fmt += "{} "; // создаёт строку форматирования
        std::cout << fmt << " : ";
        std::cout << dyna_print(fmt, "альфа", 'Z', 3.14, "не используется");
        std::cout << '\n';
    }
}

Вывод:

Привет мир!
{}  : альфа 
{} {}  : альфа Z 
{} {} {}  : альфа Z 3.14

Отчёты о дефектах

Следующие изменения поведения были применены с обратной силой к ранее опубликованным стандартам C++:

Номер	Применён	Поведение в стандарте	Корректное поведение
WG не указан	C++20	генерирует std::format_error для неверной строки формата	неверная строка формата приводит к ошибке времени компиляции
WG не указан	C++20	объекты, которые не являются ни константными, ни копируемыми (например, объекты, подобные генераторам), не форматируются	разрешено форматирование этих объектов
WG не указан	C++20	для этого средства нет видимого пользователем имени	представлено имя `basic_format_string`

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

	записывает форматированное представление своих аргументов через итератор вывода (шаблон функции) [править]
	записывает форматированное представление своих аргументов через итератор вывода, не превышая заданного размера (шаблон функции) [править]

Категории: