Namensräume
Varianten
Aktionen

std::range_formatter

Von cppreference.com
< cpp‎ | utility‎ | format
 
C++
 
Textverarbeitungsbibliothek
 
Formatierungsbibliothek
Standardformat-Spezifikation
Formatierungsfunktionen
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
Format-Strings
(C++20)(C++20)(C++20)
(C++26)
Formatierungs-Konzepte
(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)
Formatierungs-Argumente
(C++20)
(C++20)
(C++20)(C++20)(C++20)
(C++20) (veraltet in C++26)
(C++20)(C++20)
Format-Fehler
(C++20)
 
Definiert in 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-Template zur Implementierung von Bereichs-std::formatter-Spezialisierungen.

Inhalt

[bearbeiten] Bereichsformatierungsspezifikation

Die Syntax von range-format-spec ist

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

Die range-fill-and-align wird genauso interpretiert wie eine fill-and-align, außer dass das fill in range-fill-and-align jedes Zeichen außer {, } oder : sein kann.

Die width wird in der Standard-Breitenformatierungsspezifikation beschrieben.

Die Option n formatiert den Bereich ohne öffnende und schließende Klammern.

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

Die format-spec in einer range-underlying-spec (deren Syntax äquivalent zu : format-spec ist), falls vorhanden, wird vom Bereichselement-Formatter 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. Bestimmte Optionen sind nur mit bestimmten Argumenttypen gültig.

Die verfügbaren Bereichspräsentationstypen sind

  • m: Gibt an, dass die öffnende Klammer "{", die schließende Klammer "}" und der Trennstrich ", " ist und jedes Bereichselement so formatiert wird, als ob m für seinen tuple-type angegeben wurde (in tuple-format-spec).
  • Wenn m als range-type gewählt wird, ist das Programm ill-formed, 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 die Option n und die range-underlying-spec nicht im Formatierungs-Spezifizierer enthalten sein, und
  • das Programm ist ill-formed, 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\"");

[bearbeiten] Datenmember

Member-Name Definition
std::formatter<T, CharT> underlying_ (privat) der zugrundeliegende Formatter für Elemente
((exposition-only member object*)
std::basic_string_view<CharT> separator_ (privat) ein String, der den Trennstrich des formatierten Bereichsergebnisses darstellt. Der Standard-Trennstrich ist ", ".
((exposition-only member object*)
std::basic_string_view<CharT> opening-bracket_ (privat) ein String, der die öffnende Klammer des formatierten Bereichsergebnisses darstellt. Die Standard-Öffnungsklammer ist "[".
((exposition-only member object*)
std::basic_string_view<CharT> closing-bracket_ (privat) ein String, der die schließende Klammer des formatierten Bereichsergebnisses darstellt. Die Standard-Schließungsklammer ist "]".
((exposition-only member object*)

[bearbeiten] Memberfunktionen

set_separator
 legt einen angegebenen Trennstrich für das formatierte Bereichsergebnis fest
(öffentliche Memberfunktion)
set_brackets
 legt eine angegebene öffnende und schließende Klammer für das formatierte Bereichsergebnis fest
(öffentliche Memberfunktion)
underlying
 gibt den zugrundeliegenden Formatter zurück
(öffentliche Memberfunktion)
parse
 parst den Formatierungs-Spezifizierer gemäß range-format-spec
(öffentliche Memberfunktion)
format
 schreibt die formatierte Bereichsausgabe gemäß range-format-spec
(öffentliche Memberfunktion)

std::range_formatter::set_separator

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

Weist sep 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 den Membern opening-bracket_ bzw. 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 zugrundeliegenden Formatter) zurück.

std::range_formatter::parse

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

Parst die Formatierungs-Spezifizierer als range-format-spec und speichert die geparsten Spezifizierer im aktuellen Objekt.

Ruft underlying_.parse(ctx) auf, um format-spec in range-format-spec oder, falls letztere nicht vorhanden ist, eine leere format-spec zu parsen.

Wenn range-type oder die Option n vorhanden ist, werden die Werte von opening-bracket_, closing-bracket_ und separator_ entsprechend geändert.

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
  • keine range-underlying-spec vorhanden ist.

Gibt einen Iterator hinter dem Ende der range-format-spec zurück.

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 er den formatierten std::basic_string<CharT>(std::from_range, r) als String bzw. als escaped string in ctx.out().

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

  • opening-bracket_,
  • für jedes formatierbare Element e des Bereichs r
  • das Ergebnis des Schreibens von e über underlying_ und
  • separator_, es sei denn, e ist das letzte Element von r, und
  • closing-bracket_.

Gibt einen Iterator nach dem Ende des Ausgabe-Bereichs zurück.

[bearbeiten] Fehlerberichte

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

DR angewendet auf Verhalten wie veröffentlicht Korrigiertes Verhalten
LWG 3892 C++23 die Formatierung verschachtelter Bereiche war fehlerhaft korrigiert

[bearbeiten] Siehe auch

(C++20)
 definiert Formatierungsregeln für einen gegebenen Typ
(Klassentemplate) [bearbeiten]
Abgerufen von "https://cppreference.de/mwiki/index.php?title=cpp/utility/format/range_formatter&oldid=178385"