| 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
R models ranges::sized_range, returns ranges::size(r); otherwise ranges::distance(ranges::begin(r), ranges::end(r)).Complexity
1) Linear.
2) Constant.
3) If
R 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
|
Example
#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 maderanges::distance reject array arguments
|
accepts them |
See also
| (C++20) |
advances an iterator by given distance or to a given bound (algorithm function object) |
| (C++20)(C++20) |
returns the number of elements satisfying specific criteria (algorithm function object) |
| returns the distance between two iterators (function template) |
Content from this page on cppreference.com, licensed under CC-BY-SA 3.0 and GFDL. Modified: restyled, site navigation removed, code windows added. Offline snapshot of 9 February 2025.