Namespaces
Variants

std:: range_formatter

From cppreference.net
C++
Text processing library
Formatting library
Standard format specification
Formatting functions
(C++20)
(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)
range_formatter
(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 T, class CharT = char >

requires std:: same_as < std:: remove_cvref_t < T > , T > && std:: formattable < T, CharT >

class range_formatter ;
(начиная с C++23)

std::range_formatter является вспомогательным шаблоном класса для реализации специализаций std::formatter для диапазонов.

Содержание

Спецификация формата диапазона

Синтаксис range-format-spec следующий:

range-fill-and-align  (необязательно) width  (необязательно) n (необязательно) range-type  (необязательно) range-underlying-spec  (необязательно)

range-fill-and-align интерпретируется так же, как fill-and-align , за исключением того, что fill в range-fill-and-align является любым символом, кроме { , } или : .

width описывается в стандартной спецификации ширины формата .

Опция n приводит к форматированию диапазона без открывающих и закрывающих скобок. 

assert(std::format("{}", views::iota(1, 5)) == "[1, 2, 3, 4]");
assert(std::format("{:n}", views::iota(1, 5)) == "1, 2, 3, 4");

Форматная спецификация format-spec в range-underlying-spec (её синтаксис эквивалентен : format-spec ), если она присутствует, интерпретируется форматтером элементов диапазона std::formatter<T, CharT> . 

std::array ints{12, 10, 15, 14};
assert(std::format("{}", ints) == "[12, 10, 15, 14]");
assert(std::format("{::X}", ints) == "[C, A, F, E]");
assert(std::format("{:n:_^4}", ints) == "_12_, _10_, _15_, _14_");
**Примечание:** Весь код C++ оставлен без изменений, как и требовалось, поскольку: - HTML теги и атрибуты не переведены - Текст внутри тегов ` 
` сохранен в оригинале
- C++ специфические термины не переведены
- Форматирование полностью сохранено
В данном случае переводить нечего, так как весь текст представляет собой код C++.

range-type изменяет способ форматирования диапазона, при этом некоторые опции допустимы только с определенными типами аргументов.

Доступные типы представления диапазонов:

  • m : Указывает, что открывающая скобка должна быть "{" , закрывающая скобка должна быть "}" , разделитель должен быть ", " , и каждый элемент диапазона должен форматироваться как если бы для его tuple-type был указан m (в tuple-format-spec ).
  • Если m выбран в качестве range-type , программа является некорректной, если только T не является специализацией: 
std::array char_pairs
{
    std::pair{'A', 5}, std::pair{'B', 10}, std::pair{'C', 12}
};
assert(std::format("{}", char_pairs) == "[('A', 5), ('B', 10), ('C', 12)]");
assert(std::format("{:m}", char_pairs) == "{'A': 5, 'B': 10, 'C': 12}");
  • s : Указывает, что диапазон должен быть отформатирован как строка.
  • ?s : Указывает, что диапазон должен быть отформатирован как экранированная строка .
  • Если выбран s или ?s в качестве range-type , то ни опция n , ни range-underlying-spec не должны включаться в спецификатор формата, и
  • программа является некорректной, если T не является CharT . 
std::array star{'S', 'T', 'A', 'R'};
assert(std::format("{}", star) == "['S', 'T', 'A', 'R']");
assert(std::format("{:s}", star) == "STAR");
assert(std::format("{:?s}", star) == "\"STAR\"");

Члены данных

Название члена Определение
std:: formatter < T, CharT > underlying_ (приватный) базовый форматтер для элементов
( объект-член только для демонстрации* )
std:: basic_string_view < CharT > separator_ (приватный) строка, представляющая разделитель форматированного результата диапазона. Разделитель по умолчанию - ", " .
( объект-член только для демонстрации* )
std:: basic_string_view < CharT > opening-bracket_ (приватный) строка, представляющая открывающую скобку форматированного результата диапазона. Открывающая скобка по умолчанию - "[" .
( объект-член только для демонстрации* )
std:: basic_string_view < CharT > closing-bracket_ (приватный) строка, представляющая закрывающую скобку форматированного результата диапазона. Закрывающая скобка по умолчанию - "]" .
( объект-член только для демонстрации* )

Функции-члены

set_separator
устанавливает указанный разделитель для форматированного результата диапазона
(public member function)
set_brackets
устанавливает указанные открывающие и закрывающие скобки для форматированного результата диапазона
(public member function)
underlying
возвращает базовый форматтер
(public member function)
parse
анализирует спецификатор формата, как указано в range-format-spec
(public member function)
format
записывает форматированный вывод диапазона, как указано в range-format-spec
(public member function)

std::range_formatter:: set_separator

constexpr void set_separator ( std:: basic_string_view < CharT > sep ) noexcept ;

Присваивает sep переменной separator_ .

std::range_formatter:: set_brackets

constexpr void set_brackets ( std:: basic_string_view < CharT > opening,
std:: basic_string_view < CharT > closing ) noexcept ;

Присваивает opening и closing значения opening-bracket_ и closing-bracket_ соответственно.

std::range_formatter:: underlying

constexpr std:: formatter < T, CharT > & underlying ( ) ;
(1)
constexpr const std:: formatter < T, CharT > & underlying ( ) const ;
(2)

Возвращает underlying_ (базовый форматтер).

std::range_formatter:: parse

template < class ParseContext >
constexpr auto parse ( ParseContext & ctx ) - > ParseContext :: iterator ;

Анализирует спецификаторы формата как range-format-spec и сохраняет проанализированные спецификаторы в текущем объекте.

Вызывает underlying_ . parse ( ctx ) для анализа format-spec в range-format-spec или, если последний отсутствует, пустой format-spec .

Если присутствует range-type или опция n , значения opening-bracket_ , closing-bracket_ и separator_ изменяются соответствующим образом.

Вызывает underlying_ . set_debug_format ( ) если:

  • range-type не является ни s , ни ?s ,
  • underlying_ . set_debug_format ( ) является допустимым выражением, и
  • отсутствует range-underlying-spec .

Возвращает итератор за концом range-format-spec .

std::range_formatter:: format

template < ranges:: input_range R, class FormatContext >

requires std:: formattable < ranges:: range_reference_t < R > , CharT > &&
std:: same_as < std:: remove_cvref_t < ranges:: range_reference_t < R >> , T >

auto format ( R && r, FormatContext & ctx ) const - > FormatContext :: iterator ;

Если тип-диапазона был либо s , либо ?s , он записывает форматированную std:: basic_string < CharT > ( std:: from_range , r ) как строку или экранированную строку соответственно в ctx. out ( ) .

В противном случае он записывает следующее в ctx. out ( ) в соответствии с спецификацией-формата-диапазона , в следующем порядке:

  • opening-bracket_ ,
  • для каждого форматируемого элемента e диапазона r :
  • результат записи e через underlying_ , и
  • separator_ , если только e не является последним элементом r , и
  • closing-bracket_ .

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

Отчеты о дефектах

Следующие отчеты об изменениях поведения, влияющие на дефекты, были применены ретроактивно к ранее опубликованным стандартам C++.

DR Applied to Behavior as published Correct behavior
LWG 3892 C++23 форматирование вложенных диапазонов было некорректным исправлено

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

(C++20)
определяет правила форматирования для заданного типа
(шаблон класса)