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)
Definiert im Header <format>
template < class T, class CharT = char >

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

class range_formatter ;
(seit C++23)

std::range_formatter ist eine Hilfsklassen-Vorlage zur Implementierung von Bereichs- std::formatter Spezialisierungen.

Inhaltsverzeichnis

Bereichsformat-Spezifikation

Die Syntax von range-format-spec lautet:

range-fill-and-align  (optional) width  (optional) n (optional) range-type  (optional) range-underlying-spec  (optional)

Das range-fill-and-align wird auf die gleiche Weise interpretiert wie ein fill-and-align , mit der Ausnahme, dass das fill in range-fill-and-align ein beliebiges Zeichen außer { , } oder : ist.

Die width wird in der standard format width specification beschrieben.

Die n Option bewirkt, dass der Bereich ohne die öffnenden und schließenden Klammern formatiert wird. 

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

Das format-spec in einem range-underlying-spec (seine Syntax entspricht : format-spec ), falls vorhanden, wird durch den Bereichselement-Formatierer std::formatter<T, CharT> interpretiert. 

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_");

Der range-type ändert die Art und Weise, wie ein Bereich formatiert wird, wobei bestimmte Optionen nur mit bestimmten Argumenttypen gültig sind.

Die verfügbaren Bereichsdarstellungstypen sind:

  • m : Gibt an, dass die öffnende Klammer "{" sein soll, die schließende Klammer "}" sein soll, das Trennzeichen ", " sein soll und jedes Bereichselement so formatiert werden soll, als ob m für seinen tuple-type angegeben wurde (in tuple-format-spec ).
  • Wenn m als der range-type gewählt wird, ist das Programm fehlerhaft, es sei denn, T ist entweder eine Spezialisierung von: 
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 : Gibt an, dass der Bereich als String formatiert werden soll.
  • ?s : Gibt an, dass der Bereich als escaped string formatiert werden soll.
  • Wenn s oder ?s als range-type gewählt wird, dürfen sowohl die n -Option als auch range-underlying-spec nicht im Formatbezeichner enthalten sein, und
  • das Programm ist fehlerhaft, es sei denn, T ist 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\"");

Datenmitglieder

Member name Definition
std:: formatter < T, CharT > underlying_ (private) der zugrunde liegende Formatter für Elemente
( exposition-only member object* )
std:: basic_string_view < CharT > separator_ (private) eine Zeichenkette, die den Separator des formatierten Bereichsergebnisses darstellt. Der Standardseparator ist ", " .
( exposition-only member object* )
std:: basic_string_view < CharT > opening-bracket_ (private) eine Zeichenkette, die die öffnende Klammer des formatierten Bereichsergebnisses darstellt. Die Standard-öffnende Klammer ist "[" .
( exposition-only member object* )
std:: basic_string_view < CharT > closing-bracket_ (private) eine Zeichenkette, die die schließende Klammer des formatierten Bereichsergebnisses darstellt. Die Standard-schließende Klammer ist "]" .
( exposition-only member object* )

Memberfunktionen

set_separator
setzt einen bestimmten Separator für das formatierte Bereichsergebnis
(public member function)
set_brackets
setzt bestimmte öffnende und schließende Klammern für das formatierte Bereichsergebnis
(public member function)
underlying
gibt den zugrundeliegenden Formatter zurück
(public member function)
parse
parst den Formatbezeichner wie in range-format-spec angegeben
(public member function)
format
schreibt die formatierte Bereichsausgabe wie in range-format-spec angegeben
(public member function)

std::range_formatter:: set_separator

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

Weist sep dem separator_ zu.

std::range_formatter:: set_brackets

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

Weist opening und closing jeweils opening-bracket_ und closing-bracket_ zu.

std::range_formatter:: underlying

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

Gibt underlying_ (den zugrunde liegenden Formatierer) zurück.

std::range_formatter:: parse

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

Parst die Formatbezeichner als range-format-spec und speichert die geparsten Bezeichner im aktuellen Objekt.

Ruft underlying_ . parse ( ctx ) auf, um format-spec in range-format-spec zu parsen oder, falls letzteres nicht vorhanden ist, einen leeren format-spec .

Falls range-type oder die n -Option vorhanden sind, werden die Werte von opening-bracket_ , closing-bracket_ und separator_ entsprechend angepasst.

Es ruft underlying_ . set_debug_format ( ) auf, wenn:

  • der range-type weder s noch ?s ist,
  • underlying_ . set_debug_format ( ) ein gültiger Ausdruck ist, und
  • kein range-underlying-spec vorhanden ist.

Gibt einen Iterator zurück, der hinter das Ende des range-format-spec zeigt.

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 ;

Wenn der range-type entweder s oder ?s war, schreibt es den formatierten std:: basic_string < CharT > ( std:: from_range , r ) als String bzw. als escaped String in ctx. out ( ) .

Andernfalls schreibt es Folgendes in ctx. out ( ) gemäß range-format-spec in dieser Reihenfolge:

  • opening-bracket_ ,
  • für jedes formatierbare Element e des Ranges r :
  • das Ergebnis des Schreibens von e über underlying_ , und
  • separator_ , außer e ist das letzte Element von r , und
  • closing-bracket_ .

Gibt einen Iterator hinter das Ende des Ausgabebereichs zurück.

Fehlerberichte

Die folgenden verhaltensändernden Fehlerberichte wurden rückwirkend auf zuvor veröffentlichte C++-Standards angewendet.

DR Angewendet auf Veröffentlichtes Verhalten Korrigiertes Verhalten
LWG 3892 C++23 die Formatierung verschachtelter Bereiche war fehlerhaft korrigiert

Siehe auch

(C++20)
definiert Formatierungsregeln für einen gegebenen Typ
(Klassentemplate)