std::ranges:: distance

From cppreference.com

Defined in header `<iterator>`
Call signature
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)	(since 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)	(since C++20)
template < ranges:: range R > constexpr ranges:: range_difference_t < R > distance ( R && r ) ;	(3)	(since C++20)

1,2) Returns the number of hops from first to last .

3) Returns the size of r as a signed integer.

The function-like entities described on this page are algorithm function objects (informally known as niebloids ), that is:

Explicit template argument lists cannot be specified when calling any of them.
None of them are visible to argument-dependent lookup .
When any of them are found by normal unqualified lookup as the name to the left of the function-call operator, argument-dependent lookup is inhibited.

Parameters

first	-	iterator pointing to the first element
last	-	sentinel denoting the end of the range first is an iterator to
r	-	range to calculate the distance of

Return value

1) The number of increments needed to go from first to last .

2) last - static_cast < const std:: decay_t < I > & > ( first ) .

3) If

models ranges:: sized_range , returns ranges:: size ( r ) ; otherwise ranges :: distance ( ranges:: begin ( r ) , ranges:: end ( r ) ) .

Complexity

1) Linear.

2) Constant.

3) If

models ranges:: sized_range or if std:: sized_sentinel_for < ranges:: sentinel_t < R > , ranges:: iterator_t < R >> is modeled, complexity is constant; otherwise linear.

Possible implementation

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{};

Example

Run this code

#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);
}

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR	Applied to	Behavior as published	Correct behavior
LWG 3392	C++20	overload (1) takes iterator by value, thus move-only iterator lvalue with a sized sentinel was rejected	added overload (2)
LWG 3664	C++20	the resolution of LWG issue 3392 made `ranges::distance` reject array arguments	accepts them

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

ranges::advance (C++20)	advances an iterator by given distance or to a given bound (algorithm function object)
ranges::count ranges::count_if (C++20) (C++20)	returns the number of elements satisfying specific criteria (algorithm function object)
distance	returns the distance between two iterators (function template)