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

💅 std::experimental::ranges::next

okay bestie, welcome to the C++ Standard Library corner of the multiverse ✨ this one lives in the std::experimental::ranges namespace, so it's giving "ranges TS era" — very vintage, very cppreference dot com, 2024.06.10 vibes 🎀

---

✨ NAME ✨

std::experimental::ranges::next — literally just std::experimental::ranges::next, no notes, that's the whole name, slay 💅

---

🌸 SYNOPSIS 🌸

okay so first things first, it's Defined in header <experimental/ranges/iterator> — that's where you gotta look, don't come for me if you can't find it 🦋

Then there's this whole namespace situation:

namespace {
                                                                        (ranges
     constexpr /* unspecified */ next = /* unspecified */;
 (customization point
                                                                        object)
}

yeah it's a customization point object, note the constexpr /* unspecified */ — the standard is being mysterious on purpose, it's giving mystery, it's giving main character energy ✨ (and yes, it's marked (ranges TS) up in the corner, iykyk)

🎀 Call signature 🎀

here's the lineup, four whole overloads, no cap:

template< Iterator I >                                      (1)
constexpr I next( I i );
template< Iterator I >                                      (2)
constexpr I next( I i, ranges::difference_type_t<I> n );
template< Iterator I, Sentinel<I> S >                       (3)
constexpr I next( I i, S bound );
template< Iterator I, Sentinel<I> S >
constexpr I next( I i, ranges::difference_type_t<I> n, S    (4)
bound );

so what does it do?? it advances the iterator i n times, or until bound is reached — whichever comes first, bestie, whichever comes FIRST 💀 — and then it returns the advanced iterator. iconic behavior honestly.

• (1) — equivalent to ++i; return i;. that's it. one hop. periodt.
• (2) — equivalent to ranges::advance(i, n); return i;. scoot it n times, hand it back 🫶
• (3) — equivalent to ranges::advance(i, bound); return i;. no count, just vibes until bound shows up 🌈
• (4) — equivalent to ranges::advance(i, n, bound); return i;. n AND bound, and whoever wins, wins 🔥

---

⭐ RETURN VALUE ⭐

The advanced iterator. that's it. that's the whole thing. give it back to me 💖

---

🦋 NOTES 🦋

okay this part is lowkey important so listen up 👑

even though omitting n for overload (2) behaves as if n is 1, omitting n for overload (4) effectively behaves as if n is infinity (always advance to bound).

so like. same "missing argument" energy, WILDLY different result. one is a single step, the other runs all the way home 🏃‍♀️💨 do not confuse them fr fr, that's a trap and you deserve better 🙈

---

🎀 EXAMPLE 🎀

This section is incomplete Reason: no example

not me showing up with zero examples 😭 the cppreference girlies literally left it blank. it's giving "we'll finish this later" and later never came 💀

---

💜 SEE ALSO 💜

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

(yeah that last one has no name attached on this page, bestie — I'm not gonna invent one, I'm respectful like that 🫶)

---

🌈 CATEGORY 🌈

• * Todo no example

the todo list said what it said and honestly? she's valid for it 💅

---

Sign-off: that's the tea, bestie 💖 this little number lives over at http://cppreference.com, and this particular snapshot is stamped 2024.06.10 🎀 go forth, advance your iterators, and remember: no cap, always check your bounds ✨🦋🌸