std::experi...es::advance(3)

💖 NAME 💖

Okay so this page is std::experi...es::advance(3) from the C++ Standard Libary manual, section 3 — and the name is std::experimental::ranges::advance, which is also std::experimental::ranges::advance. Yes bestie, it said the same thing twice, and honestly? iconic 💅.

✨ Synopsis ✨

Defined in header <experimental/ranges/iterator>.

namespace {
    constexpr /* unspecified */ advance = /* unspecified */;
}

The namespace block is tagged (ranges TS), and the advance thing is a (customization point object).

🦋 Call signature 🦋

(1)

template< Iterator I >
constexpr void advance( I& i, ranges::difference_type_t<I> n );

(2)

template< Iterator I, Sentinel<I> S >
constexpr void advance( I& i, S bound );

(3)

template< Iterator I, Sentinel<I> S >
constexpr ranges::difference_type_t<I> advance( I& i,       ranges::difference_type_t<I> n, S bound );

Advances the iterator i n times, or until bound is reached, whichever comes first. 💫

1. Overload (1) — If I models RandomAccessIterator, it’s equivalent to i += n. Otherwise, it increments (or decrements if n is negative) i n times.

The behavior is undefined if n is negative and I does not model BidirectionalIterator. 😭

2. Overload (2) — If Assignable<I&, S> is satisfied, it’s equivalent to i = std::move(bound). Otherwise, if [i, bound) does not denote a range, the behavior is undefined. Otherwise, if SizedSentinel<S, I> is satisfied, it’s equivalent to ranges::advance(i, bound - i). Otherwise, it increments i until i == bound.
3. Overload (3) — If SizedSentinel<S, I> is satisfied, it’s equivalent to ranges::advance(i, bound) if |n| >= |bound - i|, and ranges::advance(i, n) otherwise. Otherwise, it increments (or decrements if n is negative) i either n times or until i == bound, whichever comes first.

If n > 0, [i, bound) shall denote a range; if n == 0, either [i, bound) or [bound, i) shall denote a range; if n < 0, [bound, i) shall denote a range, I and S shall be the same type, and I must model BidirectionalIterator. Otherwise, the behavior is undefined.

🌸 Return value 🌸

• 1, 2) — (none)
• 3) — The number of increment/decrements not performed due to reaching bound. In other words, n - M, where M is the distance from the starting position of i to the ending position and is negative if the ending position is before the starting position.

🦋 Example 🦋

This section is incomplete.

Reason: no example

🌈 See also 🌈

• advance — advances an iterator by given distance (function template)
• distance — returns the distance between an iterator and a sentinel, or between the beginning and the end of a range (function template)
• next — increment an iterator (function template)
• prev — decrement an iterator (function template)

👑 Category 👑

• Todo no example

---

okay that’s the whole page, bestie 💅 — source: http://cppreference.com, version/date: 2024.06.10, page: std::experi...es::advance(3). mwah 🫶