Namespaces
Variants

std::ranges:: distance

From cppreference.net
C++
Iterator library
Iterator concepts
Iterator primitives
Algorithm concepts and utilities
Indirect callable concepts
Common algorithm requirements
(C++20)
(C++20)
(C++20)
Utilities
(C++20)
Iterator adaptors
Range access
(C++11) (C++14)
(C++14) (C++14)
(C++11) (C++14)
(C++14) (C++14)
(C++17) (C++20)
(C++17)
(C++17)
Definiert im Header <iterator>
Aufrufsignatur
template < class I, std:: sentinel_for < I > S >

requires ( ! std:: sized_sentinel_for < S, I > )
constexpr std:: iter_difference_t < I >

distance ( I first, S last ) ;
(1) (seit C++20)
template < class I, std:: sized_sentinel_for < std:: decay_t < I >> S >

constexpr std:: iter_difference_t < std:: decay_t < I >>

distance ( I && first, S last ) ;
(2) (seit C++20)
template < ranges:: range R >

constexpr ranges:: range_difference_t < R >

distance ( R && r ) ;
(3) (seit C++20)
1,2) Gibt die Anzahl der Sprünge von first bis last zurück.
3) Gibt die Größe von r als vorzeichenbehaftete Ganzzahl zurück.

Die auf dieser Seite beschriebenen funktionsähnlichen Entitäten sind algorithm function objects (informell bekannt als niebloids ), das heißt:

Inhaltsverzeichnis

Parameter

first - Iterator, der auf das erste Element zeigt
last - Sentinel, der das Ende des Bereichs kennzeichnet first ist ein Iterator zu
r - Bereich, für den die Distanz berechnet werden soll

Rückgabewert

1) Die Anzahl der Inkremente, die benötigt werden, um von first bis zu last zu gelangen.
2) last - static_cast < const std:: decay_t < I > & > ( first ) .
3) Falls R das Konzept ranges:: sized_range modelliert, gibt ranges:: size ( r ) zurück; andernfalls ranges :: distance ( ranges:: begin ( r ) , ranges:: end ( r ) ) .

Komplexität

1) Linear.
2) Konstante.
3) Falls R das Konzept ranges:: sized_range modelliert oder falls std:: sized_sentinel_for < ranges:: sentinel_t < R > , ranges:: iterator_t < R >> modelliert wird, ist die Komplexität konstant; andernfalls linear.

Mögliche Implementierung 

struct distance_fn
{
    template<class I, std::sentinel_for<I> S>
        requires (!std::sized_sentinel_for<S, I>)
    constexpr std::iter_difference_t<I> operator()(I first, S last) const
    {
        std::iter_difference_t<I> result = 0;
        while (first != last)
        {
            ++first;
            ++result;
        }
        return result;
    }
    template<class I, std::sized_sentinel_for<std::decay<I>> S>
    constexpr std::iter_difference_t<I> operator()(const I& first, S last) const
    {
        return last - first;
    }
    template<ranges::range R>
    constexpr ranges::range_difference_t<R> operator()(R&& r) const
    {
        if constexpr (ranges::sized_range<std::remove_cvref_t<R>>)
            return static_cast<ranges::range_difference_t<R>>(ranges::size(r));
        else
            return (*this)(ranges::begin(r), ranges::end(r));
    }
};
inline constexpr auto distance = distance_fn{};

Beispiel

Diesen Code ausführen 
#include <cassert>
#include <forward_list>
#include <iterator>
#include <vector>
int main() 
{
    std::vector<int> v{3, 1, 4};
    assert(std::ranges::distance(v.begin(), v.end()) == 3);
    assert(std::ranges::distance(v.end(), v.begin()) == -3);
    assert(std::ranges::distance(v) == 3);
    std::forward_list<int> l{2, 7, 1};
    // auto size = std::ranges::size(l); // error: not a sizable range
    auto size = std::ranges::distance(l); // OK, but aware O(N) complexity
    assert(size == 3);
}

Fehlerberichte

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

DR Angewendet auf Verhalten wie veröffentlicht Korrektes Verhalten
LWG 3392 C++20 Überladung (1) nimmt Iterator als Wert, daher wurde move-only
Iterator-Lvalue mit sized Sentinel abgelehnt 		Überladung (2) hinzugefügt
LWG 3664 C++20 Die Lösung von LWG Issue 3392 führte dazu, dass
ranges::distance Array-Argumente ablehnte 		akzeptiert sie

Siehe auch

(C++20)
bewegt einen Iterator um eine gegebene Distanz oder bis zu einer gegebenen Grenze
(Algorithmus-Funktionsobjekt)
(C++20) (C++20)
gibt die Anzahl der Elemente zurück, die bestimmte Kriterien erfüllen
(Algorithmus-Funktionsobjekt)
gibt den Abstand zwischen zwei Iteratoren zurück
(Funktionstemplate)