Пространства имён
Варианты
Действия

std::format_to_n, std::format_to_n_result

Материал из cppreference.com
< cpp‎ | utility‎ | format
 
C++
Поддержка компилятором
Автономные и размещённые реализации
Язык
Стандартная библиотека
Заголовки стандартной библиотеки
Требования к именованию
Макросы тестирования функциональности (C++20)
Поддержка языка
Библиотека концептов (C++20)
Библиотека метапрограммирования (C++11)
Библиотека диагностики
Библиотека общих утилит
Библиотека строк
Библиотека контейнеров
Библиотека итераторов
Библиотека диапазонов (C++20)
Библиотека алгоритмов
Библиотека численных данных
Библиотека ввода/вывода
Библиотека локализаций
Регулярные выражения (C++11)
Атомарные операции (C++11)
Библиотека поддержки конкуренции (C++11)
Библиотека файловой системы (C++17)
Технические спецификации
Указатель символов
Внешние библиотеки
 
Библиотека утилит
Языковая поддержка
Поддержка типов (базовые типы, RTTI)
Макросы тестирования функциональности библиотеки (C++20)    
Управление динамической памятью
Программные утилиты
Поддержка сопрограмм (C++20)
Вариативные функции
(C++20)
(C++26)
(C++11)
(C++20)
Трёхстороннее сравнение (C++20)
(C++20)(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)    
(C++20)(C++20)(C++20)(C++20)(C++20)(C++20)
Общие утилиты
Дата и время
Функциональные объекты
Библиотека форматирования (C++20)
(C++11)
Операторы отношения (устарело в C++20)
Целочисленные функции сравнения
(C++20)(C++20)(C++20)    
(C++20)
Операции обмена и типа
(C++20)
(C++14)
(C++11)
(C++23)
(C++11)
(C++23)
(C++11)
(C++11)
(C++17)
Общие лексические типы
(C++11)
(C++17)
(C++17)
(C++17)
(C++11)
(C++11)
(C++17)
(C++17)
(C++23)
Элементарные преобразования строк
(C++17)
(C++17)
(C++17)
 
Библиотека форматирования
Функции форматирования
(C++20)
(C++20)
format_to_n
(C++20)
(C++20)
(C++20)
(C++20)
Концепты форматирования
(C++23)
Форматировщик
(C++20)
(C++23)
(C++20)(C++20)(C++20)
(C++20)(C++20)(C++20)
(C++23)
(C++23)
Аргументы форматирования
(C++20)
(C++20)
(C++20)(C++20)(C++20)
(C++20)(C++20)(C++20)
(C++20) (устарело в C++26)
(C++20)(C++20)
Ошибка формата
(C++20)
 
Определено в заголовочном файле <format>
template< class OutputIt, class... Args >

std::format_to_n_result<OutputIt>
    format_to_n( OutputIt out, std::iter_difference_t<OutputIt> n,

                 std::format_string<Args...> fmt, Args&&... args );
 (1) (начиная с C++20)
template< class OutputIt, class... Args >

std::format_to_n_result<OutputIt>
    format_to_n( OutputIt out, std::iter_difference_t<OutputIt> n,

                 std::wformat_string<Args...> fmt, Args&&... args );
 (2) (начиная с C++20)
template< class OutputIt, class... Args >

std::format_to_n_result<OutputIt>
    format_to_n( OutputIt out, std::iter_difference_t<OutputIt> n,
                 const std::locale& loc,

                 std::format_string<Args...> fmt, Args&&... args );
 (3) (начиная с C++20)
template< class OutputIt, class... Args >

std::format_to_n_result<OutputIt>
    format_to_n( OutputIt out, std::iter_difference_t<OutputIt> n,
                 const std::locale& loc,

                 std::wformat_string<Args...> fmt, Args&&... args );
 (4) (начиная с C++20)
Вспомогательные типы
template< class OutputIt >

struct format_to_n_result {
    OutputIt out;
    std::iter_difference_t<OutputIt> size;

};
 (5) (начиная с C++20)

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

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

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

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

5) std::format_to_n_result не имеет базовых классов или элементов, кроме out, size и неявно объявленных специальных функций-элементов.

Содержание

[править] Параметры

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

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

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

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

спецификатор-формата — спецификация формата, определённая специализацией std::formatter для соответствующего аргумента.
args... — аргументы для форматирования
loc — std::locale используется для форматирования, зависящего от локали

[править] Возвращаемое значение

format_to_n_result, такое, что элемент out является итератором за концом выходного диапазона, а элемент size представляет собой общий (не усечённый) размер вывода.

[править] Исключения

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

[править] Пример

В Обозревателе Компиляторов Godbolt: clang (trunk) + libc++, gcc (trunk) + libstdc++.

Запустить этот код
#include <format>
#include <iostream>
#include <string_view>
 
int main()
{
    char buffer[64];
 
    for (std::size_t max_chars_to_write : {std::size(buffer) - 1, 23uz})
    {
        const auto result =
            std::format_to_n(
                buffer, max_chars_to_write,
                "Hubble's H{2} {3} {0}{4}{1} км/сек/Mpc.", // 24 байта без форматтеров
                71,       // {0}, занимает 2 байта
                8,        // {1}, занимает 1 байт
                "\u2080", // {2}, занимает 3 байта, '₀' (SUBSCRIPT ZERO)
                "\u2245", // {3}, занимает 3 байта, '≅' (APPROXIMATELY EQUAL TO)
                "\u00B1"  // {4}, занимает 2 байта, '±' (PLUS-MINUS SIGN)
                ); // 24 + 2 + 1 + 3 + 3 + 2 == 35, без завершающего '\0'
 
        *result.out = '\0'; // добавляет терминатор в буфер
 
        const std::string_view str{buffer, result.out}; // использует конструктор C++20
 
        std::cout << "Буфер до '\\0': \"" << str << "\"\n"
                  << "Максимальное количество символов для записи: "
                  << max_chars_to_write << '\n'
                  << "Смещение result.out: " << result.out - buffer << '\n'
                  << "Необрезанный размер вывода: " << result.size << "\n\n";
    }
}

Вывод: 

Буфер до '\0': "Hubble's H₀ ≅ 71±8 км/сек/Mpc."
Максимальное количество символов для записи: 63
Смещение result.out: 35
Необрезанный размер вывода: 35
 
Буфер до '\0': "Hubble's H₀ ≅ 71±8"
Максимальное количество символов для записи: 23
Смещение result.out: 23
Необрезанный размер вывода: 35

[править] Отчёты о дефектах

Следующие изменения поведения были применены с обратной силой к ранее опубликованным стандартам C++:

Номер Применён Поведение в стандарте Корректное поведение
WG не указан C++20 генерирует std::format_error для неверной строки формата неверная строка формата приводит к
ошибке времени компиляции
WG не указан C++20 объекты, которые не являются ни константными, ни копируемыми
(например, объекты, подобные генераторам), не форматируются 		разрешено форматирование этих объектов
WG не указан C++20 для этого средства нет видимого пользователем имени представлено имя basic_format_string

[править] Смотрите также

(C++20)
 сохраняет форматированное представление аргументов в новой строке
(шаблон функции) [править]
(C++20)
 записывает форматированное представление своих аргументов через итератор вывода
(шаблон функции) [править]
(C++20)
 определяет количество символов, необходимых для хранения форматированного представления его аргументов
(шаблон функции) [править]
Источник — «https://ru.cppreference.com/mwiki/index.php?title=cpp/utility/format/format_to_n&oldid=63502»