std::format_to

Определено в заголовке `<format>`
template< class OutputIt, class... Args > OutputIt format_to( OutputIt out, std::format_string<Args...> fmt, Args&&... args );	(1)	(с C++20)
template< class OutputIt, class... Args > OutputIt format_to( OutputIt out, std::wformat_string<Args...> fmt, Args&&... args );	(2)	(с C++20)
template< class OutputIt, class... Args > OutputIt format_to( OutputIt out, const std::locale& loc, std::format_string<Args...> fmt, Args&&... args );	(3)	(с C++20)
template< class OutputIt, class... Args > OutputIt format_to( OutputIt out, const std::locale& loc, std::wformat_string<Args...> fmt, Args&&... args );	(4)	(с C++20)

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

1) эквивалентно return std::vformat_to(out, fmt.str, std::make_format_args(args...));

2) эквивалентно return std::vformat_to(std::move(out), fmt.str, std::make_wformat_args(args...));

3) эквивалентно return std::vformat_to(out, loc, fmt.str, std::make_format_args(args...));

4) эквивалентно return std::vformat_to(std::move(out), loc, fmt.str, std::make_wformat_args(args...));

Пусть CharT равно char для перегрузок (1,3), и wchar_t для перегрузок (2,4).

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

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

Параметры

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 используется для локализованного форматирования

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

Итератор, следующий за концом диапазона вывода.

Исключение

Распространяет любое исключение, брошенное операциями форматирования или итераторов.

Примечания

Начиная с P2216R3, это ошибка, если строка формата не является константным выражением. std::vformat_to или std::runtime_format(с C++26) может быть использовано в этом случае.

Пример

#include <format>
#include <iostream>
#include <iterator>
#include <string>
 
auto main() -> int
{
    std::string buffer;
 
    std::format_to(
        std::back_inserter(buffer), //< OutputIt
        "Hello, C++{}!\n",          //< fmt 
        "20");                      //< arg
    std::cout << buffer;
    buffer.clear();
 
    std::format_to(
        std::back_inserter(buffer), //< OutputIt
        "Hello, {0}::{1}!{2}",      //< fmt 
        "std",                      //< arg {0}
        "format_to()",              //< arg {1}
        "\n",                       //< arg {2}
        "extra param(s)...");       //< unused
    std::cout << buffer;
 
    std::wstring wbuffer;
    std::format_to(
        std::back_inserter(wbuffer),//< OutputIt 
        L"Hello, {2}::{1}!{0}",     //< fmt
        L"\n",                      //< arg {0}
        L"format_to()",             //< arg {1}
        L"std",                     //< arg {2}
        L"...is not..."             //< unused
        L"...an error!");           //< unused
    std::wcout << wbuffer;
}

Вывод:

Hello, C++20!
Hello, std::format_to()!
Hello, std::format_to()!

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

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

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

См. также

format (C++20)	сохраняет отформатированное представление аргументов в новой строке (функция-шаблон)
format_to_n (C++20)	записывает отформатированное представление аргументов через итератор вывода, не превышая заданного размера (функция-шаблон)

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