std::ranges...brange::next(3)

💖 std::ranges...brange::next(3) 💖

okay bestie, this is the C++ Standard Libary manual page for std::ranges...brange::next(3) — yes, that’s the manual name, folded in right here near the top like a little name tag, mwah 💋. We’re talking about std::ranges::subrange::next, and it’s lowkey iconic.

---

🌸 NAME 🌸

• std::ranges::subrange::next — std::ranges::subrange::next

---

✨ Synopsis ✨

okay so there are two overloads, both (since C++20), both [[nodiscard]] constexpr, and both return a subrange. The default is literally n = 1 in both. Overload (1) is const& and requires std::forward_iterator<I>. Overload (2) is &&. Here they are in all their main-character glory:

[[nodiscard]] constexpr subrange next(std::iter_difference_t<I> n = 1) const&
    requires std::forward_iterator<I>;

(1) (since C++20)

[[nodiscard]] constexpr subrange next(std::iter_difference_t<I> n = 1) &&;

(2) (since C++20)

1. Overload (1) — Obtains a subrange whose iterator is incremented by min(n, size()) times or decremented by -n times respect to that of *this, when n >= 0 or n < 0 respectively. Equivalent to auto tmp = *this; tmp.advance(n); return tmp;.
2. Overload (2) — Increments the stored iterator by min(n, size()) times or decremented it by -n times, when n >= 0 or n < 0 respectively, and then move-constructs the result from *this. Equivalent to advance(n); return std::move(*this);.

The behavior is undefined if: - I does not model bidirectional_iterator and n < 0, or - the stored iterator is decremented after becoming a non-decrementable value.

bestie, that undefined-behavior bullet is not the vibe check you want to fail 😭 periodt.

---

🎀 Return value 🎀

A subrange whose iterator is incremented by min(n, size()) times or decremented by -n times respect to the original value of that of *this, when n >= 0 or n < 0 respectively. slay 🫶

---

🔥 Complexity 🔥

Generally min(n, size()) increments or -n decrements on the iterator, when n >= 0 or n < 0 respectively.

Constant if I models random_access_iterator, and either n < 0 or std::sized_sentinel_for<S, I> is modeled. that’s the whole tea ☕✨

---

🦋 Notes 🦋

A call to (2) may leave *this in a valid but unspecified state, depending on the behavior of the move constructor of I and S. ngl, “valid but unspecified” is giving mystery box energy 🎁🙈.

---

🙈 Example 🙈

This section is incomplete. Reason: no example.

literally no example, bestie — the manual said “not me leaving this blank” 💀.

---

🌈 See also 🌈

• prev (C++20) — obtains a copy of the subrange with its iterator decremented by a given distance (public member function)
• advance (C++20) — advances the iterator by given distance (public member function)
• next (C++11) — increment an iterator (function template)
• ranges::next (C++20) — increment an iterator by a given distance or to a bound (niebloid)

---

🧚 Category 🧚

• * Todo no example

---

mwah 💋 — this came from http://cppreference.com, version/date 2024.06.10, page std::ranges...brange::next(3). bye bestie, go slay those subranges! 🫶👑