Namespaces
Variants

std:: format_to

From cppreference.net
C++
Text processing library
Formatting library
Standard format specification
Formatting functions
(C++20)
format_to
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
Format strings
(C++20) (C++20) (C++20)
(C++26)
Formatting concepts
(C++23)
Formatter
(C++20)
(C++23)
(C++23)
(C++23)
(C++23)
(C++20) (C++20) (C++20)
(C++20) (C++20) (C++20)
(C++23)
(C++23)
Formatting arguments
(C++20)
(C++20)
(C++20) (C++20) (C++20)
(C++20) (deprecated in C++26)
(C++20) (C++20)
Format error
(C++20)
Определено в заголовочном файле <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 < const CharT & > .

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

Содержание

Параметры

out - итератор на выходной буфер
fmt -
объект, представляющий строку формата. Строка формата состоит из
  • обычных символов (кроме { и } ), которые копируются в вывод без изменений,
  • escape-последовательностей { { и } } , которые заменяются на { и } соответственно в выводе, и
  • полей замены.

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

{ arg-id (опционально) } (1)
{ arg-id (опционально) : format-spec } (2)
1) поле замены без спецификации формата
2) поле замены со спецификацией формата
arg-id - указывает индекс аргумента в args , значение которого должно использоваться для форматирования; если он опущен, аргументы используются по порядку.

Все arg-id  в строке формата должны быть либо все указаны, либо все опущены. Смешивание ручной и автоматической индексации является ошибкой.

format-spec - спецификация формата, определяемая специализацией std::formatter для соответствующего аргумента. Не может начинаться с } .

(since C++23)
(since C++26)
  • Для других форматируемых типов спецификация формата определяется пользовательскими специализациями formatter .
args... - аргументы для форматирования
loc - std::locale используемая для локале-специфичного форматирования

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

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

Исключения

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

Примечания

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

Пример

Запустить этот код 
#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++.

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

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

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