std::ranges::subrange<I,S,K>::advance
constexpr subrange& advance( std::iter_difference_t<I> n ); | (since C++20) |
Increments or decrements begin_ :
- If
Imodelsbidirectional_iteratorandn < 0istrue, decrementsbegin_by-nelements.
ranges::advance(begin_ ,n);
ifconstexpr(StoreSize )
size_ += to-unsigned-like (-n);
return*this;. Equivalent to: autod=n-ranges::advance(begin_ ,n, end_ );
ifconstexpr(StoreSize )
size_ -= to-unsigned-like (d);
return*this;.
According to the preconditions of ranges::advance, if n < 0 is true and begin_ cannot be decremented by -n elements, the behavior is undefined.
Parameters
| n | - | number of maximal increments of the iterator |
Return value
*this
Example
#include <algorithm>
#include <array>
#include <iostream>
#include <iterator>
#include <ranges>
void print(auto name, auto const sub)
{
std::cout << name << ".size() == " << sub.size() << "; { ";
std::ranges::for_each(sub, [](int x) { std::cout << x << ' '; });
std::cout << "}\n";
};
int main()
{
std::array arr{1, 2, 3, 4, 5, 6, 7};
std::ranges::subrange sub{std::next(arr.begin()), std::prev(arr.end())};
print("1) sub", sub);
print("2) sub", sub.advance(3));
print("3) sub", sub.advance(-2));
}
Output:
1) sub.size() == 5; { 2 3 4 5 6 }
2) sub.size() == 2; { 5 6 }
3) sub.size() == 4; { 3 4 5 6 }
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 3433 | C++20 | the behavior was undefined if n < 0 | made well-defined if begin_ can be decremented |
See also
obtains a copy of the subrange with its iterator advanced by a given distance (public member function) |
|
obtains a copy of the subrange with its iterator decremented by a given distance (public member function) |
|
| advances an iterator by given distance (function template) |
|
|
(C++20) | advances an iterator by given distance or to a given bound (algorithm function object) |
© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/cpp/ranges/subrange/advance
