Difference between revisions of "cpp/iterator/ranges/advance"
From cppreference.com
m |
m (minor tweaked possible implementation) |
||
| Line 75: | Line 75: | ||
} | } | ||
else if constexpr (std::sized_sentinel_for<S, I>) { | else if constexpr (std::sized_sentinel_for<S, I>) { | ||
| − | + | (*this)(i, bound - i); | |
} | } | ||
else { | else { | ||
| Line 89: | Line 89: | ||
{ | { | ||
if constexpr (std::sized_sentinel_for<S, I>) { | if constexpr (std::sized_sentinel_for<S, I>) { | ||
| − | // std::abs isn't constexpr | + | // std::abs isn't constexpr until C++23 |
auto abs = [](const std::iter_difference_t<I> x) { return x < 0 ? -x : x; }; | auto abs = [](const std::iter_difference_t<I> x) { return x < 0 ? -x : x; }; | ||
const auto dist = abs(n) - abs(bound - i); | const auto dist = abs(n) - abs(bound - i); | ||
if (dist < 0) { | if (dist < 0) { | ||
| − | + | (*this)(i, bound); | |
return -dist; | return -dist; | ||
} | } | ||
| − | + | (*this)(i, n); | |
return 0; | return 0; | ||
} | } | ||
Revision as of 02:05, 4 May 2022
| Defined in header <iterator>
|
||
| Call signature |
||
| template< std::input_or_output_iterator I > constexpr void advance( I& i, std::iter_difference_t<I> n ); |
(1) | (since C++20) |
| template< std::input_or_output_iterator I, std::sentinel_for<I> S > constexpr void advance( I& i, S bound ); |
(2) | (since C++20) |
| template< std::input_or_output_iterator I, std::sentinel_for<I> S > constexpr std::iter_difference_t<I> advance( I& i, std::iter_difference_t<I> n, S bound ); |
(3) | (since C++20) |
1) Increments given iterator
i for n times.2) Increments given iterator
i until i == bound.3) Increments given iterator
i for n times, or until i == bound, whichever comes first.If n is negative, the iterator is decremented. In this case, I must model std::bidirectional_iterator, and S must be the same type as I if bound is provided, otherwise the behavior is undefined.
The function-like entities described on this page are 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.
In practice, they may be implemented as function objects, or with special compiler extensions.
Contents |
Parameters
| i | - | iterator to be advanced |
| bound | - | sentinel denoting the end of the range i is an iterator to
|
| n | - | number of maximal increments of i
|
Return value
3) The difference between
n and the actual distance i traversed.Complexity
Linear.
However, if I additionally models std::random_access_iterator, or S models std::sized_sentinel_for<I>, or I and S model std::assignable_from<I&, S>, complexity is constant.
Notes
The behavior is undefined if the specified sequence of increments or decrements would require that a non-incrementable iterator (such as the past-the-end iterator) is incremented, or that a non-decrementable iterator (such as the front iterator or the singular iterator) is decremented.
Possible implementation
struct advance_fn { template<std::input_or_output_iterator I> constexpr void operator()(I& i, std::iter_difference_t<I> n) const { if constexpr (std::random_access_iterator<I>) { i += n; } else { while (n > 0) { --n; ++i; } if constexpr (std::bidirectional_iterator<I>) { while (n < 0) { ++n; --i; } } } } template<std::input_or_output_iterator I, std::sentinel_for<I> S> constexpr void operator()(I& i, S bound) const { if constexpr (std::assignable_from<I&, S>) { i = std::move(bound); } else if constexpr (std::sized_sentinel_for<S, I>) { (*this)(i, bound - i); } else { while (i != bound) { ++i; } } } template<std::input_or_output_iterator I, std::sentinel_for<I> S> constexpr std::iter_difference_t<I> operator()(I& i, std::iter_difference_t<I> n, S bound) const { if constexpr (std::sized_sentinel_for<S, I>) { // std::abs isn't constexpr until C++23 auto abs = [](const std::iter_difference_t<I> x) { return x < 0 ? -x : x; }; const auto dist = abs(n) - abs(bound - i); if (dist < 0) { (*this)(i, bound); return -dist; } (*this)(i, n); return 0; } else { while (n > 0 && i != bound) { --n; ++i; } if constexpr (std::bidirectional_iterator<I>) { while (n < 0 && i != bound) { ++n; --i; } } return n; } } }; inline constexpr auto advance = advance_fn(); |
Example
Run this code
#include <iomanip> #include <iostream> #include <iterator> #include <vector> int main() { std::vector<int> v{ 3, 1, 4 }; auto vi = v.begin(); std::ranges::advance(vi, 2); std::cout << "value: " << *vi << '\n'; { std::ranges::advance(vi, v.end()); std::cout << std::boolalpha; std::cout << "vi == v.end(): " << (vi == v.end()) << '\n'; std::ranges::advance(vi, -3); std::cout << "value: " << *vi << '\n'; std::cout << "diff: " << std::ranges::advance(vi, 2, v.end()) << ", "; std::cout << "value: " << *vi << '\n'; std::cout << "diff: " << std::ranges::advance(vi, 4, v.end()) << ", "; std::cout << "vi == v.end(): " << (vi == v.end()) << '\n'; std::cout << std::noboolalpha; } }
Output:
value: 4 vi == v.end(): true value: 3 diff: 0, value: 4 diff: 3, vi == v.end(): true
See also
| (C++20) |
increment an iterator by a given distance or to a bound (niebloid) |
| (C++20) |
decrement an iterator by a given distance or to a bound (niebloid) |
| (C++20) |
returns the distance between an iterator and a sentinel, or between the beginning and end of a range (niebloid) |
| advances an iterator by given distance (function template) |
