table of contents
std::ranges::distance(3) | C++ Standard Libary | std::ranges::distance(3) |
NAME¶
std::ranges::distance - std::ranges::distance
Synopsis¶
Defined in header <iterator>
Call signature
template< std::input_or_output_iterator I, std::sentinel_for<I> S
>
(1) (since C++20)
requires (!std::sized_sentinel_for<S, I>)
constexpr std::iter_difference_t<I> distance( I first, S last );
template< std::input_or_output_iterator I,
std::sized_sentinel_for<I> S > (2) (since C++20)
constexpr std::iter_difference_t<I> distance( const I& first,
const S& last );
template< ranges::range R > (3) (since C++20)
constexpr ranges::range_difference_t<R> distance( R&& r );
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 niebloids, that is:
* Explicit template argument lists may not be specified when calling any of
them.
* None of them is visible to argument-dependent lookup.
* When one of them is found by normal unqualified lookup for the name to the
left
of the function-call operator, it inhibits argument-dependent lookup.
In practice, they may be implemented as function objects, or with special
compiler
extensions.
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 - 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.
2) 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¶
struct distance_fn {
template<std::input_or_output_iterator 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<std::input_or_output_iterator I, std::sized_sentinel_for<I>
S>
constexpr std::iter_difference_t<I> operator()(const I& first,
const 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 <iostream>
#include <iterator>
#include <vector>
int main()
{
std::vector<int> v{ 3, 1, 4 };
namespace ranges = std::ranges;
std::cout << "distance(first, last) = "
<< ranges::distance(v.begin(), v.end()) << '\n'
<< "distance(last, first) = "
<< ranges::distance(v.end(), v.begin()) << '\n'
<< "distance(v) = " << ranges::distance(v) <<
'\n';
}
Output:¶
distance(first, last) = 3
distance(last, first) = -3
distance(v) = 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
distance takes iterator by value, thus by reference overload
LWG 3392 C++20 rejecting move-only iterator lvalue with a added
sized sentinel
See also¶
ranges::advance advances an iterator by given distance or to a
given bound
(C++20) (niebloid)
ranges::count
ranges::count_if returns the number of elements satisfying specific criteria
(C++20) (niebloid)
(C++20)
distance returns the distance between two iterators
(function template)
2022.07.31 | http://cppreference.com |