Namensräume
Varianten
Aktionen

Ranges-Bibliothek (seit C++20)

Von cppreference.com
< cpp
 
 
Bereichsbibliothek
Range-Adaptoren
 

Die Ranges-Bibliothek ist eine Erweiterung und Verallgemeinerung der Algorithmen- und Iterator-Bibliotheken, die sie leistungsfähiger macht, indem sie komponierbar und weniger fehleranfällig ist.

Die Bibliothek erstellt und manipuliert Range-Views, leichte Objekte, die iterierbare Sequenzen (Ranges) indirekt repräsentieren. Ranges sind eine Abstraktion über

  • [beginend) – Iterator-Paare, z. B. Ranges, die durch implizite Konvertierung aus Containern erstellt wurden. Alle Algorithmen, die Iterator-Paare verwenden, haben nun Überladungen, die Ranges akzeptieren (z. B. ranges::sort)
  • begin + [0size) – gezählte Sequenzen, z. B. Range, zurückgegeben von views::counted
  • [beginpredicate) – bedingt terminierte Sequenzen, z. B. Range, zurückgegeben von views::take_while
  • [begin..) – unbeschränkte Sequenzen, z. B. Range, zurückgegeben von views::iota

Die Ranges-Bibliothek enthält Range-Algorithmen, die auf Ranges eifrig angewendet werden, und Range-Adaptoren, die auf Views lazy angewendet werden. Adaptoren können zu Pipelines komponiert werden, sodass ihre Aktionen während der Iteration des Views stattfinden.

Definiert in der Header-Datei <ranges>
namespace std {

    namespace views = ranges::views;

}
(seit C++20)

Der Namespace-Alias std::views wird als Kurzform für std::ranges::views bereitgestellt.

Definiert im Namespace std::ranges

Inhalt

Bereichszugriff
Definiert in der Header-Datei <ranges>
Definiert in Header <iterator>
gibt einen Iterator zum Anfang eines Ranges zurück
(Customization Point Objekt)[edit]
gibt ein Sentinel zurück, das das Ende eines Ranges anzeigt
(Customization Point Objekt)[edit]
gibt einen Iterator zum Anfang eines schreibgeschützten Ranges zurück
(Customization Point Objekt)[edit]
gibt ein Sentinel zurück, das das Ende eines schreibgeschützten Ranges anzeigt
(Customization Point Objekt)[edit]
gibt einen Reverse-Iterator zu einem Range zurück
(Customization Point Objekt)[edit]
gibt einen Reverse-End-Iterator zu einem Range zurück
(Customization Point Objekt)[edit]
gibt einen Reverse-Iterator zu einem schreibgeschützten Range zurück
(Customization Point Objekt)[edit]
gibt einen Reverse-End-Iterator zu einem schreibgeschützten Range zurück
(Customization Point Objekt)[edit]
gibt eine Ganzzahl zurück, die dem von einem Range gegebenen Reserve-Hinweis entspricht
(Customization Point Objekt)[edit]
gibt eine Ganzzahl zurück, die der Größe eines Ranges entspricht
(Customization Point Objekt)[edit]
gibt eine vorzeichenbehaftete Ganzzahl zurück, die der Größe eines Ranges entspricht
(Customization Point Objekt)[edit]
prüft, ob ein Range leer ist
(Customization Point Objekt)[edit]
ruft einen Zeiger auf den Anfang eines zusammenhängenden Ranges ab
(Customization Point Objekt)[edit]
ruft einen Zeiger auf den Anfang eines schreibgeschützten zusammenhängenden Ranges ab
(Customization Point Objekt)[edit]
Range-Primitive
Definiert in der Header-Datei <ranges>
ermittelt Iterator- und Sentinel-Typen eines Ranges
(Alias-Template)[edit]
ermittelt Größen-, Differenz- und Wertetypen eines Ranges
(Alias-Template)[edit]
ermittelt Referenztypen eines Ranges
(Alias-Template)[edit]
Behandlung von hängenden Iteratoren
Definiert in der Header-Datei <ranges>
ein Platzhaltertyp, der anzeigt, dass ein Iterator oder ein subrange nicht zurückgegeben werden sollte, da er hängen würde
(Klasse) [edit]
ermittelt den Iterator- oder subrange-Typ eines borrowed_range
(Alias-Template)[edit]
Andere Hilfsprogramme
Definiert in der Header-Datei <ranges>
taggt einen Range, damit er als Sequenz und nicht als einzelner Wert behandelt wird
(Klassen-Template) [edit]
Range-Konzepte
Definiert in der Header-Datei <ranges>
spezifiziert, dass ein Typ ein Range ist, d. h. er stellt einen begin-Iterator und ein end-Sentinel bereit
(Konzept) [edit]
spezifiziert, dass ein Typ ein range ist und Iteratoren, die aus einem Ausdruck davon erhalten werden, sicher zurückgegeben werden können, ohne Gefahr des Hängens
(Konzept) [edit]
spezifiziert, dass ein Range seine Größe in konstanter Zeit schätzen kann
(Konzept) [edit]
spezifiziert, dass ein Range seine Größe in konstanter Zeit kennt
(Konzept) [edit]
spezifiziert, dass ein Range ein View ist, d. h. er hat konstante Zeit für Kopie/Verschiebung/Zuweisung
(Konzept) [edit]
spezifiziert einen Range, dessen Iteratortyp input_iterator erfüllt
(Konzept) [edit]
spezifiziert einen Range, dessen Iteratortyp output_iterator erfüllt
(Konzept) [edit]
spezifiziert einen Range, dessen Iteratortyp forward_iterator erfüllt
(Konzept) [edit]
spezifiziert einen Range, dessen Iteratortyp bidirectional_iterator erfüllt
(Konzept) [edit]
spezifiziert einen Range, dessen Iteratortyp random_access_iterator erfüllt
(Konzept) [edit]
spezifiziert einen Range, dessen Iteratortyp contiguous_iterator erfüllt
(Konzept) [edit]
spezifiziert, dass ein Range identische Iterator- und Sentinel-Typen hat
(Konzept) [edit]
spezifiziert die Anforderungen an einen range, der sicher in einen view konvertiert werden kann
(Konzept) [edit]
spezifiziert, dass ein Range schreibgeschützte Elemente hat
(Konzept) [edit]
Range-Konvertierungen
Definiert in der Header-Datei <ranges>
konstruiert ein neues Nicht-View-Objekt aus einem Input-Range
(Funktions-Template) [edit]
Ansichten
Definiert in der Header-Datei <ranges>
Hilfsklassen-Template zur Definition eines view unter Verwendung des Curiously Recurring Template Pattern
(Klassen-Template) [edit]
kombiniert ein Iterator-Sentinel-Paar zu einer view
(Klassenschablone) [edit]

[edit] Range-Fabriken

Definiert in der Header-Datei <ranges>
Definiert im Namespace std::ranges
eine leere view ohne Elemente
(class template) (variable template)[edit]
eine view, die ein einzelnes Element eines bestimmten Wertes enthält
(class template) (customization point object)[edit]
ein view, der eine Sequenz aus aufeinanderfolgenden Inkrementierungen eines Anfangswerts besteht
(Klassen-Template) (Customization Point Objekt)[edit]
ein view, der eine Sequenz aus der wiederholten Erzeugung desselben Werts besteht
(Klassen-Template) (Customization Point Objekt)[edit]
ein view, der aus den Elementen besteht, die durch sukzessive Anwendung von operator>> auf den zugehörigen Eingabestrom erhalten werden
(Klassen-Template) (Customization Point Objekt)[edit]

[edit] Range-Adaptoren

Definiert in der Header-Datei <ranges>
Definiert im Namespace std::ranges
Hilfs-Basisklassen-Template zur Definition eines Range-Adaptor-Closure-Objekts
(Klassen-Template) [edit]
ein view, der alle Elemente eines range enthält
(Alias-Template) (Range-Adaptor-Objekt)[edit]
ein view der Elemente eines anderen range
(Klassen-Template) [edit]
ein view mit exklusivem Besitz eines range
(Klassen-Template) [edit]
ein view einer Sequenz, der jedes Element in ein rvalue umwandelt
(Klassen-Template) (Range-Adaptor-Objekt)[edit]
ein view, der aus den Elementen eines range besteht, die ein Prädikat erfüllen
(Klassen-Template) (Range-Adaptor-Objekt)[edit]
ein view einer Sequenz, der eine Transformationsfunktion auf jedes Element anwendet
(Klassen-Template) (Range-Adaptor-Objekt)[edit]
ein view, der aus den ersten N Elementen eines anderen view besteht
(Klassen-Template) (Range-Adaptor-Objekt)[edit]
ein view, der aus den anfänglichen Elementen eines anderen view besteht, bis zum ersten Element, für das ein Prädikat false zurückgibt
(Klassen-Template) (Range-Adaptor-Objekt)[edit]
ein view, der aus Elementen eines anderen view besteht, wobei die ersten N Elemente übersprungen werden
(Klassen-Template) (Range-Adaptor-Objekt)[edit]
ein view, der aus den Elementen eines anderen view besteht, wobei die anfängliche Teilsequenz von Elementen übersprungen wird, bis zum ersten Element, bei dem das Prädikat false zurückgibt
(Klassen-Template) (Range-Adaptor-Objekt)[edit]
ein view, der aus der Sequenz besteht, die durch Abflachung eines view von ranges gebildet wird
(Klassen-Template) (Range-Adaptor-Objekt)[edit]
ein view, der aus der Sequenz besteht, die durch Abflachung eines Views von Ranges gebildet wird, mit dem Trennzeichen zwischen den Elementen
(Klassen-Template) (Range-Adaptor-Objekt)[edit]
ein view über die Unterbereiche, die durch Aufteilen eines anderen view mit einem Trennzeichen gebildet werden
(Klassen-Template) (Range-Adaptor-Objekt)[edit]
ein view über die Unterbereiche, die durch Aufteilen eines anderen view mit einem Trennzeichen gebildet werden
(Klassen-Template) (Range-Adaptor-Objekt)[edit]
ein view, der aus der Verkettung der adaptierten Views besteht
(Klassen-Template) (Customization Point Objekt)[edit]
erstellt einen Subrange aus einem Iterator und einer Anzahl
(Customization Point Objekt)[edit]
konvertiert einen view in einen common_range
(Klassen-Template) (Range-Adaptor-Objekt)[edit]
ein view, der über die Elemente eines anderen bidirektionalen Views in umgekehrter Reihenfolge iteriert
(Klassen-Template) (Range-Adaptor-Objekt)[edit]
konvertiert einen view in einen constant_range
(Klassen-Template) (Range-Adaptor-Objekt)[edit]
nimmt einen view von tuple-ähnlichen Werten und eine Zahl N und erzeugt einen view des N-ten Elements jedes Tupels
(Klassen-Template) (Range-Adaptor-Objekt)[edit]
nimmt einen view von Paar-ähnlichen Werten und erzeugt einen view der ersten Elemente jedes Paares
(Klassen-Template) (Range-Adaptor-Objekt)[edit]
nimmt einen view von Paar-ähnlichen Werten und erzeugt einen view der zweiten Elemente jedes Paares
(Klassen-Template) (Range-Adaptor-Objekt)[edit]
ein view, der jedes Element einer adaptierten Sequenz auf ein Tupel aus sowohl der Position als auch dem Wert des Elements abbildet
(Klassen-Template) (Range-Adaptor-Objekt)[edit]
ein view, der aus Tupeln von Referenzen auf entsprechende Elemente der adaptierten Views besteht
(Klassen-Template) (Customization Point Objekt)[edit]
ein view, der aus den Ergebnissen der Anwendung einer Transformationsfunktion auf entsprechende Elemente der adaptierten Views besteht
(Klassen-Template) (Customization Point Objekt)[edit]
ein view, der aus Tupeln von Referenzen auf benachbarte Elemente des adaptierten Views besteht
(Klassen-Template) (Range-Adaptor-Objekt)[edit]
ein view, der aus den Ergebnissen der Anwendung einer Transformationsfunktion auf benachbarte Elemente des adaptierten Views besteht
(Klassen-Template) (Range-Adaptor-Objekt)[edit]
eine Reihe von views, die N-elementige, nicht überlappende, aufeinanderfolgende Blöcke von Elementen einer anderen view sind
(Klassenschablone) (Range-Adaptor-Objekt)[bearbeiten]
eine view, deren M-tes Element eine view über die M-ten bis (M + N - 1)-ten Elemente einer anderen view ist
(Klassenschablone) (Range-Adaptor-Objekt)[bearbeiten]
teilt die view in Teilbereiche zwischen jedem Paar benachbarter Elemente auf, für die das gegebene Prädikat false zurückgibt
(Klassenschablone) (Range-Adaptor-Objekt)[bearbeiten]
eine view, die aus Elementen einer anderen view besteht und dabei jeweils N Elemente überspringt
(Klassenschablone) (Range-Adaptor-Objekt)[bearbeiten]
eine view, die aus Tupeln von Ergebnissen besteht, welche durch das n-äre kartesische Produkt der angepassten Views berechnet werden
(Klassenschablone) (Customization Point Objekt)[bearbeiten]
eine view, die das zuletzt abgerufene Element ihrer zugrundeliegenden Sequenz zwischenspeichert
(Klassenschablone) (Range-Adaptor-Objekt)[bearbeiten]
konvertiert eine view in einen Bereich, der nur input_range ist und kein common_range
(Klassenschablone) (Range-Adaptor-Objekt)[bearbeiten]

[bearbeiten] Range-Generatoren (seit C++23)

Definiert in Header <generator>
Definiert im Namespace std
(C++23)
Eine view, die einen synchronen Coroutine-Generator repräsentiert
(Klassentemplate) [bearbeiten]

[bearbeiten] Hilfselemente

[bearbeiten] Range-Adaptor-Objekte

Siehe RangeAdaptorObject (RAO).

[bearbeiten] Range-Adaptor-Closure-Objekte

Siehe RangeAdaptorClosureObject (RACO).

[bearbeiten] Customization Point Objekte

Siehe Customization Point Objekt (CPO).

[bearbeiten] Zuweisbarer Wrapper

Einige Range-Adaptoren umschließen ihre Elemente oder Funktions-Objekte mit dem copyable-box(bis C++23)movable-box(seit C++23). Der Wrapper ergänzt das umschlossene Objekt bei Bedarf um Zuweisbarkeit.

[bearbeiten] Nicht-propagierender Cache

Einige Range-Adaptoren werden im Sinne einer Exposition-only Klassenschablone non-propagating-cache beschrieben, die sich fast wie std::optional<T> verhält (siehe Beschreibung für Unterschiede).

[bearbeiten] Bedingt-const Typ

template< bool Const, class T >
using /*maybe-const*/ = std::conditional_t<Const, const T, T>;
(nur Exposition*)

Die Alias-Schablone /*maybe-const*/ ist eine Abkürzung, die verwendet wird, um bedingt einen const-Qualifikator auf den Typ T anzuwenden.

[bearbeiten] Integer-ähnliche Typ-Hilfsschablonen

template< /*is-integer-like*/ T >
using /*make-signed-like-t*/<T> = /* siehe Beschreibung */;
(1) (nur Exposition*)
template< /*is-integer-like*/ T >
using /*make-unsigned-like-t*/<T> = /* siehe Beschreibung */;
(2) (nur Exposition*)
template< /*is-integer-like*/ T >

/*make-unsigned-like-t*/<T> /*to-unsigned-like*/( T t )
{
    return static_cast</*make-unsigned-like-t*/<T>>(t);

}
(3) (nur Exposition*)
1) Für einen integer-ähnlichen Typ T
  • Wenn T ein ganzzahliger Typ ist, ist /*make-signed-like-t*/<T> std::make_signed_t<T>.
  • Andernfalls ist /*make-signed-like-t*/<T> ein entsprechender, nicht spezifizierter vorzeichenbehafteter Integer-ähnlicher Typ gleicher Breite wie T.
2) Für einen Integer-ähnlichen Typ T
  • Wenn T ein ganzzahliger Typ ist, ist /*make-unsigned-like-t*/<T> std::make_unsigned_t<T>.
  • Andernfalls ist /*make-signed-like-t*/<T> ein entsprechender, nicht spezifizierter vorzeichenloser Integer-ähnlicher Typ gleicher Breite wie T.
3) Konvertiert explizit t in /*make-unsigned-like-t*/<T>.

[bearbeiten] Customization Point Objekt-Helfer

template< ranges::input_range R >

constexpr auto& /*possibly-const-range*/(R& r) noexcept
{
    if constexpr (ranges::input_range<const R>)
        return const_cast<const R&>(r);
    else
        return r;

}
(1) (nur Exposition*)
template< class T >

constexpr auto /*as-const-pointer*/( const T* p ) noexcept
{
    return p;

}
(2) (nur Exposition*)

Einige Range-Access-Customization-Point-Objekte werden im Sinne dieser Exposition-only Funktionsschablonen beschrieben.

1) /*possibly-const-range*/ gibt die const-qualifizierte Version von r zurück, wenn const R eine input_range modelliert; andernfalls gibt es r ohne Casting zurück.
2) /*as-const-pointer*/ gibt einen Zeiger auf ein Objekt vom konstanten Typ zurück.

[bearbeiten] Range-Adaptor-Helfer

template< class F, class Tuple >

constexpr auto /*tuple-transform*/( F&& f, Tuple&& tuple )
{
    return std::apply([&]<class... Ts>(Ts&&... args)
    {
        return std::tuple<std::invoke_result_t<F&, Ts>...>
            (std::invoke(f, std::forward<Ts>(args))...);
    }, std::forward<Tuple>(tuple));

}
(1) (nur Exposition*)
template< class F, class Tuple >

constexpr void /*tuple-for-each*/( F&& f, Tuple&& tuple )
{
    std::apply([&]<class... Ts>(Ts&&... args)
    {
        (static_cast<void>(std::invoke(f, std::forward<Ts>(args))), ...);
    }, std::forward<Tuple>(tuple));

}
(2) (nur Exposition*)
template< class T >

constexpr T& /*as-lvalue*/( T&& t )
{
    return static_cast<T&>(t);

}
(3) (nur Exposition*)

Einige Range-Adaptoren werden im Sinne dieser Exposition-only Funktionsschablonen beschrieben.

1) /*tuple-transform*/ gibt ein neues Tupel zurück, das durch Anwenden von f auf jedes Element von tuple erstellt wird.
2) /*tuple-for-each*/ wendet f auf jedes Element von tuple an und gibt nichts zurück.
3) /*as-lvalue*/ leitet einen Rvalue t als Lvalue weiter.

[bearbeiten] Hilfs-Konzepte

Die folgenden Exposition-only Konzepte werden für mehrere Typen verwendet, sind aber keine Bestandteile der Schnittstelle der Standardbibliothek.

template< class R >

concept /*simple-view*/ =
    ranges::view<R> && ranges::range<const R> &&
    std::same_as<ranges::iterator_t<R>, ranges::iterator_t<const R>> &&

    std::same_as<ranges::sentinel_t<R>, ranges::sentinel_t<const R>>;
(1) (nur Exposition*)
template< class I >

concept /*has-arrow*/ =
    ranges::input_iterator<I> &&

    (std::is_pointer_v<I> || requires(const I i) { i.operator->(); });
(2) (nur Exposition*)
template< class T, class U >

concept /*different-from*/ =

    !std::same_as<std::remove_cvref_t<T>, std::remove_cvref_t<U>>;
(3) (nur Exposition*)
template< class R >

concept /*range-with-movable-references*/ =
    ranges::input_range<R> &&
    std::move_constructible<ranges::range_reference_t<R>> &&

    std::move_constructible<ranges::range_rvalue_reference_t<R>>;
(4) (nur Exposition*)
template< bool C, class... Views >

concept /*all-random-access*/ =
    (ranges::random_access_range

         <std::conditional_t<C, const Views, Views>> && ...);
(5) (nur Exposition*)
template< bool C, class... Views >

concept /*all-bidirectional*/ =
    (ranges::bidirectional_range

         <std::conditional_t<C, const Views, Views>> && ...);
(6) (nur Exposition*)
template< bool C, class... Views >

concept /*all-forward*/ =
    (ranges::forward_range

         <std::conditional_t<C, const Views, Views>> && ...);
(7) (nur Exposition*)

[bearbeiten] Hinweise

Feature-Test-Makro Wert Std Feature
__cpp_lib_generator 202207L (C++23) std::generator – synchrone Coroutine-Generator für Ranges
__cpp_lib_ranges 201911L (C++20) Ranges-Bibliothek und eingeschränkte Algorithmen
202106L (C++23)
(DR20)
Nicht standardmäßig initialisierbare Views
202110L (C++23)
(DR20)
Views mit Eigentümerschaft
202202L (C++23) ranges::range_adaptor_closure
202207L (C++23) Lockerung von Range-Adaptoren zur Erlaubnis von nur-verschiebbar (move-only) Typen
202211L (C++23) Entfernen von "Poison Pills" (P2602)-Überladungen in ranges::begin usw.
202302L (C++23) Lockerung von Ranges zur Erlaubnis bestimmter Projektionen
202406L (C++26)
(DR20)
Entfernen der Common-Reference-Anforderung aus den indirekt aufrufbaren Konzepten
__cpp_lib_ranges_as_const 202207L (C++23) std::const_iterator, ranges::as_const_view
__cpp_lib_ranges_as_rvalue 202207L (C++23) ranges::as_rvalue_view
__cpp_lib_ranges_cache_latest 202411L (C++26) ranges::cache_latest_view
__cpp_lib_ranges_cartesian_product 202207L (C++23) ranges::cartesian_product_view
__cpp_lib_ranges_chunk 202202L (C++23) ranges::chunk_view
__cpp_lib_ranges_chunk_by 202202L (C++23) ranges::chunk_by_view
__cpp_lib_ranges_concat 202403L (C++26) ranges::concat_view
__cpp_lib_ranges_enumerate 202302L (C++23) ranges::enumerate_view
__cpp_lib_ranges_join_with 202202L (C++23) ranges::join_with_view
__cpp_lib_ranges_repeat 202207L (C++23) ranges::repeat_view
__cpp_lib_ranges_reserve_hint 202502L (C++26) ranges::reserve_hint und ranges::approximately_sized_range
__cpp_lib_ranges_slide 202202L (C++23) ranges::slide_view
__cpp_lib_ranges_stride 202207L (C++23) ranges::stride_view
__cpp_lib_ranges_to_container 202202L (C++23) ranges::to
__cpp_lib_ranges_to_input 202502L (C++26) ranges::to_input_view
__cpp_lib_ranges_zip 202110L (C++23) ranges::zip_view,
ranges::zip_transform_view,
ranges::adjacent_view,
ranges::adjacent_transform_view

[bearbeiten] Beispiel

#include <iostream>
#include <ranges>
 
int main()
{
    auto const ints = {0, 1, 2, 3, 4, 5};
    auto even = [](int i) { return 0 == i % 2; };
    auto square = [](int i) { return i * i; };
 
    // the "pipe" syntax of composing the views:
    for (int i : ints | std::views::filter(even) | std::views::transform(square))
        std::cout << i << ' ';
 
    std::cout << '\n';
 
    // a traditional "functional" composing syntax:
    for (int i : std::views::transform(std::views::filter(ints, even), square))
        std::cout << i << ' ';
}

Ausgabe

0 4 16
0 4 16

[bearbeiten] Defect reports

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 3509
(P2281R1)
C++20 war unklar, wie Range-Adaptor-Objekte nachfolgende Argumente binden sie werden gebunden
per Wert
LWG 3948 C++23 possibly-const-range und as-const-pointer
waren nicht als noexcept deklariert
als noexcept deklariert
LWG 4027 C++23 possibly-const-range würde keine const-Qualifikation hinzufügen
für Ranges, die bereits constant_range modelliert haben
fügt const-Qualifikation hinzu
für solche Ranges
LWG 4112 C++20 has-arrow erforderte nicht, dass i const-qualifiziert ist requires

[bearbeiten] Siehe auch