std::ranges::subrange<I,S,K>::advance - cppreference.com (original) (raw)

Increments or decrements _[begin](../subrange.html#begin "cpp/ranges/subrange")_ :

• If I models bidirectional_iterator and n < 0 is true, decrements _[begin](../subrange.html#begin "cpp/ranges/subrange")_ by -n elements.

Equivalent to: ranges::advance(_[begin](../subrange.html#begin "cpp/ranges/subrange")_ , n);
if constexpr (_[StoreSize](../subrange.html#StoreSize "cpp/ranges/subrange")_ )
`` _[size](../subrange.html#size "cpp/ranges/subrange")_ += _[to-unsigned-like](../../ranges.html#to-unsigned-like "cpp/ranges")_ (-n);
return *this;.

• Otherwise, increments _[begin](../subrange.html#begin "cpp/ranges/subrange")_ by n elements, or until _[end](../subrange.html#end "cpp/ranges/subrange")_ is reached.

Equivalent to: auto d = n - ranges::advance(_[begin](../subrange.html#begin "cpp/ranges/subrange")_ , n, _[end](../subrange.html#end "cpp/ranges/subrange")_ );
if constexpr (_[StoreSize](../subrange.html#StoreSize "cpp/ranges/subrange")_ )
`` _[size](../subrange.html#size "cpp/ranges/subrange")_ -= _[to-unsigned-like](../../ranges.html#to-unsigned-like "cpp/ranges")_ (d);
return *this;.

According to the preconditions of ranges::advance, if n < 0 is true and _[begin](../subrange.html#begin "cpp/ranges/subrange")_ cannot be decremented by -n elements, the behavior is undefined.

[edit] Parameters

[edit] Return value

*this

[edit] Example

#include #include #include #include #include   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 }

[edit] Defect reports

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

[edit] See also

| | obtains a copy of the subrange with its iterator advanced by a given distance (public member function) [edit] | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | obtains a copy of the subrange with its iterator decremented by a given distance (public member function) [edit] | | | advances an iterator by given distance (function template) [edit] | | | advances an iterator by given distance or to a given bound(algorithm function object)[edit] |