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<const CharT&>.

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

Параметры

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

fmt

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

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

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

`{` 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)

Для других форматируемых типов спецификация формата определяется пользовательскими 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/w/cpp/utility/format/vformat_to