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, используемый для форматирования с учетом локали |
Возвращаемое значение
Объект format_to_n_result, у которого член out является итератором, указывающим за конец выходного диапазона, а член size содержит общий размер выходных данных (без усечения).
Исключения
Передает любое исключение, возникшее при операциях форматтера или итератора.
Примечания
В реализации libstdc++ до GCC-13.3 была ошибка при указании правильного значения format_to_n_result::out.
Пример
В Compiler Explorer от Godbolt: clang (trunk) + libc++, GCC (trunk) + libstdc++.
#include <format>
#include <initializer_list>
#include <iomanip>
#include <iostream>
#include <string_view>
int main()
{
char buffer[64];
for (std::size_t max_chars_to_write : {std::size(buffer) - 1, 23uz, 21uz})
{
const std::format_to_n_result 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);
std::cout << "Buffer until '\\0': " << std::quoted(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 Buffer until '\0': "Hubble's H₀ ≅ 71�" Max chars to write: 21 result.out offset: 21 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/cpp/utility/format/format_to_n
