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

🌸 NAME 🌸

okay so bestie, welcome to the std::experi...es::distance(3) page from the C++ Standard Libary manual — yes, that's the manual name, spelling and all, and we are not fixing it 💅. The NAME section is doing a little echo thing: std::experimental::ranges::distance — and then, for emphasis, std::experimental::ranges::distance again. It's giving main character energy, periodt.

This is the ranges TS distance customization point object, aka the little guy that tells you how far apart two iterators are or how big a range is. Not me being obsessed with iterators, but I am.

---

✨ Synopsis ✨

Defined in header <experimental/ranges/iterator>.

The page shows the customization point object as:

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

and tags it with (ranges TS) and (customization point object) — both annotations are right there in the original, no cap.

📞 Call signature 📞

Here are the overloads, exactly as listed:

1. Overload (1):

template< Iterator I, Sentinel<I> S >
constexpr ranges::difference_type_t<I> distance( I first, S last );

2. Overload (2):

template< Range R >
constexpr ranges::difference_type_t<ranges::iterator_t<R>>
distance( R&& r );

3. Overload (3):

template< SizedRange R >
constexpr ranges::difference_type_t<ranges::iterator_t<R>>
distance( R&& r );

So what does it do? It returns the distance between first and last, or between the beginning and the end of the range r. That's the whole vibe. 🦋

For overload (1):

• If SizedSentinel<S, I> is satisfied, it's equivalent to return last - first;.
• Otherwise, it returns the number of increments needed to get from first to last.
• If [first, last) does not denote a range, then I and S must be the same type and must model SizedSentinel, and [last, first) must denote a range. Otherwise, the behavior is undefined. Like, undefined behavior undefined. Do not play with that, bestie 😭.

For overload (2):

• It's equivalent to return ranges::distance(ranges::begin(r), ranges::end(r));.

For overload (3):

• It's equivalent to return ranges::size(r);.

⚠️ actual warning from the page: instantiating overloads (2,3) may be ill-formed if the header <experimental/ranges/range> is not included before the point of instantiation. So yes, include that header first, bestie. Fr fr.

---

💖 Return value 💖

The distance between first and last, or between the beginning and the end of the range r. That's it. That's the tea. 🍓

---

🎀 Example 🎀

This section is incomplete.

Reason: no example.

Not me staring at an empty example section like 👁️👄👁️. It's literally incomplete, so no example to copy — that's the official status, periodt.

---

🔥 See also 🔥

• distance — returns the distance between two iterators (function template).
• advance — advances an iterator by given distance (function template).
• next — increment an iterator (function template).
• prev — decrement an iterator (function template).
• size — obtains the size of a range whose size can be calculated in constant time (customization point object).

---

🦋 Category 🦋

• Todo no example.

---

okay bye bestie, stay safe and don't instantiate overloads (2,3) without <experimental/ranges/range> 🫶. This page is from cppreference.com, dated 2024.06.10 — mwah 💋✨