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(std::move(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(std::move(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<constCharT&>.

Если выполняется любое из следующих условий, поведение не определено:

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

Параметры

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

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

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

Исключения

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

Примечания

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

Пример

#include <format>
#include <iostream>
#include <iterator>
#include <string>

int main()
{
    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::flush;
    
    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++.

Отчёт об ошибке	Применён к	Опубликованное поведение	Корректное поведение
LWG 3539	C++20	`out` не мог быть перемещаемым итератором	может быть
P2216R3	C++20	выбрасывает `std::format_error` для некорректной строки форматирования	вместо этого приводит к ошибке компиляции
P2418R2	C++20	объекты, которые нельзя использовать как const и которые нельзя копировать (например, объекты, подобные генераторам), не поддерживают форматирование	разрешает форматирование этих объектов
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/cpp/utility/format/format_to