std::format_to_n, std::format_to_n_result
Определено в заголовке <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.
std::format_to_n_result не имеет базовых классов или членов, кроме out, size и неявно объявленных специальных функций-членов.Параметры
| out | - | итератор буфера вывода | ||||||||||||||
| n | - | максимальное количество символов для записи в буфер | ||||||||||||||
| fmt | - | объект, представляющий строку форматирования. Строка форматирования состоит из
Каждое поле замены имеет следующий формат:
|
||||||||||||||
| args... | - | аргументы для форматирования | ||||||||||||||
| loc | - | std::locale для форматирования, зависящего от локали |
Возвращаемое значение
A format_to_n_result такой, что член out — итератор, указывающий на конец диапазона вывода, а член size — общий (не усечённый) размер вывода.
Исключения
Распространяет любые исключения, выброшенные операциями форматирования или итерации.
Пример
В Godbolt's Compiler Explorer: 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} km/sec/Mpc.", // 24 bytes w/o formatters
71, // {0}, occupies 2 bytes
8, // {1}, occupies 1 byte
"\u2080", // {2}, occupies 3 bytes, '₀' (SUBSCRIPT ZERO)
"\u2245", // {3}, occupies 3 bytes, '≅' (APPROXIMATELY EQUAL TO)
"\u00B1" // {4}, occupies 2 bytes, '±' (PLUS-MINUS SIGN)
); // 24 + 2 + 1 + 3 + 3 + 2 == 35, no trailing '\0'
*result.out = '\0'; // adds terminator to buffer
const std::string_view str{buffer, result.out}; // uses C++20 constructor
std::cout << "Buffer until '\\0': \"" << str << "\"\n"
<< "Max chars to write: " << max_chars_to_write << '\n'
<< "result.out offset: " << result.out - buffer << '\n'
<< "Untruncated output size: " << result.size << "\n\n";
}
}Вывод:
Buffer until '\0': "Hubble's H₀ ≅ 71±8 km/sec/Mpc." Max chars to write: 63 result.out offset: 35 Untruncated output size: 35 Buffer until '\0': "Hubble's H₀ ≅ 71±8" Max chars to write: 23 result.out offset: 23 Untruncated output size: 35
Отчёты об ошибках
Следующие отчёты об ошибках, изменяющие поведение, были применены ретроактивно к ранее опубликованным стандартам C++.
| DR | Применяется к | Поведение, как опубликовано | Корректное поведение |
|---|---|---|---|
| P2216R3 | C++20 | выбрасывает std::format_error для недопустимой строки форматирования | недопустимая строка форматирования приводит к ошибке времени компиляции |
| P2418R2 | C++20 | объекты, которые не являются константными или не копируемыми (например, объекты-генераторы) не могут быть отформатированы | разрешить форматирование этих объектов |
| P2508R1 | C++20 | нет видимого пользователю имени для этой функции | имя basic_format_string доступно |
См. также
|
(C++20) | сохраняет отформатированное представление аргументов в новой строке (шаблон функции) |
|
(C++20) | записывает отформатированное представление своих аргументов через итератор вывода (шаблон функции) |
|
(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_n
