std::ranges::fold_left_first_with_iter, std::ranges::fold_left_first_with_iter_result

Definiert in Header `<algorithm>`
Aufrufsignatur
template< std::input_iterator I, std::sentinel_for<I> S, /indirectly-binary-left-foldable/<std::iter_value_t<I>, I> F > requires std::constructible_from< std::iter_value_t<I>, std::iter_reference_t<I>> constexpr /* see description */ fold_left_first_with_iter( I first, S last, F f );	(1)	(seit C++23)
template< ranges::input_range R, /indirectly-binary-left-foldable/< ranges::range_value_t<R>, ranges::iterator_t<R>> F > requires std::constructible_from< ranges::range_value_t<R>, ranges::range_reference_t<R>> constexpr /* see description */ fold_left_first_with_iter( R&& r, F f );	(2)	(seit C++23)
Hilfskonzepte
template< class F, class T, class I > concept /indirectly-binary-left-foldable/ = /* see description */;	(3)	(nur zur Veranschaulichung*)
Hilfsklassen-Schablone
template< class I, class T > using fold_left_first_with_iter_result = ranges::in_value_result<I, T>;	(4)	(seit C++23)

Faltet die Elemente des gegebenen Bereichs von links, d. h. gibt das Ergebnis der Auswertung des Kettenausdrucks zurück:
f(f(f(f(x₁, x₂), x₃), ...), x_n), wobei x₁, x₂, ..., x_n die Elemente des Bereichs sind.

Informell verhält sich ranges::fold_left_first_with_iter wie die Überladung von std::accumulate, die ein binäres Prädikat akzeptiert, außer dass *first intern als Anfangselement verwendet wird.

Das Verhalten ist undefiniert, wenn [first, last) kein gültiger Bereich ist.

1) Der Bereich ist [first, last).

2) Gleich wie (1), außer dass r als Bereich verwendet wird, als ob ranges::begin(r) als first und ranges::end(r) als last verwendet würden.

3) Äquivalent zu:

Hilfskonzepte
template< class F, class T, class I, class U > concept /indirectly-binary-left-foldable-impl/ = std::movable<T> && std::movable<U> && std::convertible_to<T, U> && std::invocable<F&, U, std::iter_reference_t<I>> && std::assignable_from<U&, std::invoke_result_t<F&, U, std::iter_reference_t<I>>>;	(3A)	(nur zur Veranschaulichung*)
template< class F, class T, class I > concept /indirectly-binary-left-foldable/ = std::copy_constructible<F> && std::indirectly_readable<I> && std::invocable<F&, T, std::iter_reference_t<I>> && std::convertible_to<std::invoke_result_t<F&, T, std::iter_reference_t<I>>, std::decay_t<std::invoke_result_t<F&, T, std::iter_reference_t<I>>>> && /indirectly-binary-left-foldable-impl/<F, T, I, std::decay_t<std::invoke_result_t<F&, T, std::iter_reference_t<I>>>>;	(3B)	(nur zur Veranschaulichung*)

4) Der Rückgabetyp-Alias. Siehe Abschnitt "Rückgabewert" für Details.

Die auf dieser Seite beschriebenen funktionsähnlichen Entitäten sind Algorithmus-Funktionsobjekte (informell als Niebloids bekannt), d. h.:

Explizite Vorlagenargumentlisten können beim Aufruf keiner von ihnen angegeben werden.
Keine von ihnen ist für die argumentabhängige Namenssuche sichtbar.
Wenn eine von ihnen durch normale unqualifizierte Namenssuche als Name links vom Funktionsaufrufoperator gefunden wird, wird die argumentabhängige Namenssuche unterdrückt.

Parameter

first, last	-	das Iterator-Sentinel-Paar, das den Bereich der zu faltenden Elemente definiert
r	-	der Bereich der zu faltenden Elemente
f	-	das binäre Funktionsobjekt

Rückgabewert

Sei U gleich decltype(ranges::fold_left(std::move(first), last, std::iter_value_t<I>(*first), f)).

1) Ein Objekt vom Typ ranges::fold_left_first_with_iter_result<I, std::optional<U>>.

Das Mitglied ranges::in_value_result::in enthält einen Iterator zum Ende des Bereichs.
Das Mitglied ranges::in_value_result::value enthält das Ergebnis der Linksfaltung des gegebenen Bereichs über f.

Wenn der Bereich leer ist, ist der Rückgabewert {std::move(first), std::optional<U>()}.

2) Gleich wie (1), außer dass der Rückgabetyp ranges::fold_left_first_with_iter_result<ranges::borrowed_iterator_t<R>, std::optional<U>> ist.

Mögliche Implementierungen

class fold_left_first_with_iter_fn
{
    template<class O, class I, class S, class F>
    constexpr auto impl(I&& first, S&& last, F f) const
    {
        using U = decltype(
            ranges::fold_left(std::move(first), last, std::iter_value_t<I>(*first), f)
        );
        using Ret = ranges::fold_left_first_with_iter_result<O, std::optional<U>>;
        if (first == last)
            return Ret{std::move(first), std::optional<U>()};
        std::optional<U> init(std::in_place, *first);
        for (++first; first != last; ++first)
            *init = std::invoke(f, std::move(*init), *first);
        return Ret{std::move(first), std::move(init)};
    }

public:
    template<std::input_iterator I, std::sentinel_for<I> S,
             /*indirectly-binary-left-foldable*/<std::iter_value_t<I>, I> F>
    requires std::constructible_from<std::iter_value_t<I>, std::iter_reference_t<I>>
    constexpr auto operator()(I first, S last, F f) const
    {
        return impl<I>(std::move(first), std::move(last), std::ref(f));
    }

    template<ranges::input_range R, /*indirectly-binary-left-foldable*/<
        ranges::range_value_t<R>, ranges::iterator_t<R>> F>
    requires
        std::constructible_from<ranges::range_value_t<R>, ranges::range_reference_t<R>>
    constexpr auto operator()(R&& r, F f) const
    {
        return impl<ranges::borrowed_iterator_t<R>>(
            ranges::begin(r), ranges::end(r), std::ref(f)
        );
    }
};

inline constexpr fold_left_first_with_iter_fn fold_left_first_with_iter;

Komplexität

Genau ranges::distance(first, last) - 1 (sofern der Bereich nicht leer ist) Anwendungen des Funktionsobjekts f.

Anmerkungen

Die folgende Tabelle vergleicht alle eingeschränkten Faltalgorithmen:

Faltfunktionsschablone	Beginnt mit	Anfangswert	Rückgabetyp
`ranges::fold_left`	links	`init`	`U`
`ranges::fold_left_first`	links	erstes Element	`std::optional<U>`
`ranges::fold_right`	rechts	`init`	`U`
`ranges::fold_right_last`	rechts	letztes Element	`std::optional<U>`
`ranges::fold_left_with_iter`	links	`init`	(1) `ranges::in_value_result<I, U>` (2) `ranges::in_value_result<BR, U>`, wobei `BR` gleich `ranges::borrowed_iterator_t<R>`
`ranges::fold_left_first_with_iter`	links	erstes Element	(1) `ranges::in_value_result<I, std::optional<U>>` (2) `ranges::in_value_result<BR, std::optional<U>>` wobei `BR` gleich `ranges::borrowed_iterator_t<R>`

Feature-Test-Makro	Wert	Std	Feature
`__cpp_lib_ranges_fold`	`202207L`	(C++23)	`std::ranges` Faltalgorithmen

Beispiel

Diesen Code ausführen

#include <algorithm>
#include <cassert>
#include <functional>
#include <iostream>
#include <ranges>
#include <utility>
#include <vector>

int main()
{
    std::vector v{1, 2, 3, 4, 5, 6, 7, 8};

    auto sum = std::ranges::fold_left_first_with_iter
    (
        v.begin(), v.end(), std::plus<int>()
    );
    std::cout << "sum: " << sum.value.value() << '\n';
    assert(sum.in == v.end());

    auto mul = std::ranges::fold_left_first_with_iter(v, std::multiplies<int>());
    std::cout << "mul: " << mul.value.value() << '\n';
    assert(mul.in == v.end());

    // get the product of the std::pair::second of all pairs in the vector:
    std::vector<std::pair<char, float>> data {{'A', 2.f}, {'B', 3.f}, {'C', 7.f}};
    auto sec = std::ranges::fold_left_first_with_iter
    (
        data | std::ranges::views::values, std::multiplies<>()
    );
    std::cout << "sec: " << sec.value.value() << '\n';

    // use a program defined function object (lambda-expression):
    auto lambda = [](int x, int y) { return x + y + 2; };
    auto val = std::ranges::fold_left_first_with_iter(v, lambda);
    std::cout << "val: " << val.value.value() << '\n';
    assert(val.in == v.end());
}

Ausgabe:

sum: 36
mul: 40320
sec: 42
val: 50

Referenzen

C++23-Standard (ISO/IEC 14882:2024):

27.6.18 Fold [alg.fold]

Siehe auch

ranges::fold_left (C++23)	faltet einen Bereich von Elementen von links (Algorithmus-Funktionsobjekt)
ranges::fold_left_first (C++23)	faltet einen Bereich von Elementen von links unter Verwendung des ersten Elements als Anfangswert (Algorithmus-Funktionsobjekt)
ranges::fold_right (C++23)	faltet einen Bereich von Elementen von rechts (Algorithmus-Funktionsobjekt)
ranges::fold_right_last (C++23)	faltet einen Bereich von Elementen von rechts unter Verwendung des letzten Elements als Anfangswert (Algorithmus-Funktionsobjekt)
ranges::fold_left_with_iter (C++23)	faltet einen Bereich von Elementen von links und gibt ein Paar (Iterator, Wert) zurück (Algorithmus-Funktionsobjekt)
accumulate	summiert oder faltet einen Bereich von Elementen (Funktionsschablone)
reduce (C++17)	ähnlich wie std::accumulate, jedoch in beliebiger Reihenfolge (Funktionsschablone)

Compiler-Unterstützung
Freistehend und gehostet
Sprache
Standardbibliothek
Standardbibliotheks-Header
Benannte Anforderungen
Feature-Test-Makros (C++20)
Sprachunterstützungsbibliothek
Konzepte-Bibliothek (C++20)
Diagnosebibliothek
Speicherverwaltungsbibliothek
Metaprogrammierungsbibliothek (C++11)
Allgemeine Dienstprogrammbibliothek
Container-Bibliothek
Iteratoren-Bibliothek
Bereiche-Bibliothek (C++20)
Algorithmen-Bibliothek
Zeichenketten-Bibliothek
Textverarbeitungsbibliothek
Numerik-Bibliothek
Datums- und Zeitbibliothek
Ein-/Ausgabebibliothek
Dateisystembibliothek (C++17)
Nebenläufigkeitsunterstützungsbibliothek (C++11)
Ausführungssteuerungsbibliothek (C++26)
Technische Spezifikationen
Symbolverzeichnis
Externe Bibliotheken

de.cppreference.net

Namespaces

Variants