std::vformat_to

Определён в заголовочном файле `<format>`
template< class OutputIt > OutputIt vformat_to( OutputIt out, std::string_view fmt, std::format_args args );	(1)	(начиная с C++20)
template< class OutputIt > OutputIt vformat_to( OutputIt out, std::wstring_view fmt, std::wformat_args args );	(2)	(начиная с C++20)
template< class OutputIt > OutputIt vformat_to( OutputIt out, const std::locale& loc, std::string_view fmt, std::format_args args );	(3)	(начиная с C++20)
template< class OutputIt > OutputIt vformat_to( OutputIt out, const std::locale& loc, std::wstring_view fmt, std::wformat_args args );	(4)	(начиная с C++20)

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

Пусть CharT — это decltype(fmt)::char_type (char для перегрузок (1,3), wchar_t для перегрузок (2,4)).

Эти перегрузки участвуют в разрешении перегрузки только в том случае, если OutputIt удовлетворяет концепту std::output_iterator<constCharT&>.

OutputIt должен соответствовать (удовлетворять семантическим требованиям) концепту std::output_iterator<constCharT&>, а std::formatter<Ti,CharT> должен удовлетворять требованиям Formatter для любого Ti в типе аргументов. В противном случае поведение не определено.

Параметры

out - итератор выходного буфера

fmt

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

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

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

`{` arg-id (необязательно) `}`	(1)
`{` arg-id (необязательно) `:` format-spec `}`	(2)

1) поле подстановки без спецификации формата 2) поле подстановки со спецификацией формата

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

Для базовых типов и стандартных строковых типов спецификация формата интерпретируется как стандартная спецификация формата.
Для типов chrono спецификация формата интерпретируется как спецификация формата chrono.

Для типов диапазонов спецификация формата интерпретируется как спецификация формата диапазона.
Для std::pair и std::tuple спецификация формата интерпретируется как спецификация формата кортежа.
Для std::thread::id и std::stacktrace_entry см. спецификацию формата идентификатора потока и спецификацию формата записи стека вызовов.
Для std::basic_stacktrace спецификатор формата не допускается.

(начиная с C++23)

Для std::filesystem::path см. спецификацию формата пути.

(начиная с C++26)

Для других форматируемых типов спецификация формата определяется пользовательскими специализациями formatter.

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

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

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

Итератор за концом выходного диапазона.

Исключения

Выбрасывает std::format_error, если fmt не является допустимой строкой формата для предоставленных аргументов. Также передаёт любые исключения, выброшенные форматтером или операциями с итератором.

Пример

Отчёты об ошибках

Следующие отчёты об ошибках, изменяющие поведение, были применены задним числом к ранее опубликованным стандартам C++.

DR	Применён к	Поведение согласно опубликованной версии	Корректное поведение
P2216R3	C++20	тип `args` параметризуется `OutputIt`	не параметризуется

См. также

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/cpp/utility/format/vformat_to