std::ranges::end(3)

✨ std::ranges::end(3) — the C++ Standard Library glow-up ✨

Okay bestie, so this page is all about std::ranges::end from the C++ Standard Library, and it's genuinely iconic for finding where a range stops. No cap.

---

🎀 NAME 🎀

std::ranges::end — literally just std::ranges::end, the customization point object that gives you the end sentinel of a range. That's it. That's the whole name. Periodt.

---

🌸 SYNOPSIS 🌸

First things first: this lives in the header <ranges> and in the header <iterator>. Both. She's versatile.

inline namespace /* unspecified */ {
    inline constexpr /* unspecified */ end = /* unspecified */;
}

Since C++20 💖 — it's a customization point object, which is just fancy speak for "a global constexpr thingy you can call like a function". Bestie, it's giving "just vibes but make it constexpr".

Here's the call signature:

template< class T >
    requires /* see below */
constexpr std::sentinel_for<ranges::iterator_t<T>> auto end( T&& t );

Since C++20, obviously. We love a constrained template.

---

🦋 DESCRIPTION 🦋

So what does it do? It returns a sentinel (fancy iterator-ish buddy) that indicates the end of a range. The range-begin-end.svg diagram exists in the visual version of this page — picture it as the "you are here → you're done" arrow. 🌈

Here's the tea: if the argument is an lvalue, or if ranges::enable_borrowed_range<std::remove_cv_t<T>> is true, then a call to ranges::end is expression-equivalent to:

1. t + std::extent_v<T> if t has an array type of known bound. ✨
   • Watch out: if std::remove_all_extents_t<std::remove_reference_t<T>> is incomplete, then the call to ranges::end is ill-formed, no diagnostic required. 💀 That's the scary kind of ill-formed — no warning, no error, just vibes going wrong.
2. Otherwise, decay-copy(t.end()) (until C++23) or auto(t.end()) (since C++23), if that expression is valid and its type models std::sentinel_for<ranges::iterator_t<T>>. She slayed the C++23 glow-up.
3. Otherwise, decay-copy(end(t)) (until C++23) or auto(end(t)) (since C++23), if T is a class or enumeration type, that expression is valid, and its converted type models std::sentinel_for<ranges::iterator_t<T>>, where the meaning of end is established as if by performing argument-dependent lookup only. Iykyk — ADL only, no sneaky global lookups. 👑

In all other cases, a call to ranges::end is ill-formed, which can result in substitution failure when the call to ranges::end appears in the immediate context of a template instantiation. Basically: if it doesn't match any of those three, she's not available and your template SFINAE's out. 🙈

---

💅 NOTES 💅

• If the argument is an rvalue (i.e. T is an object type) and ranges::enable_borrowed_range<std::remove_cv_t<T>> is false, or if it is of an array type of unknown bound, the call to ranges::end is ill-formed — which also results in substitution failure. So no rvalue shenanigans unless she's borrowed. 🚫
• If ranges::end(std::forward<T>(t)) is valid, then decltype(ranges::end(std::forward<T>(t))) and decltype(ranges::begin(std::forward<T>(t))) model std::sentinel_for in all cases, while T models std::ranges::range. So begin and end stay matched, as they should. 💖
• The C++20 standard requires that if the underlying end function call returns a prvalue, the return value is move-constructed from the materialized temporary object. All implementations directly return the prvalue instead. The requirement is corrected by the post-C++20 proposal P0849R8 to match the implementations. So the standard was doing the most, and the implementers were like "nah, we're returning it directly". Not me defending the standard's extra paperwork. 😭

---

🔥 EXAMPLE 🔥

// Run this code — go on, bestie, compile it:

#include <algorithm>
#include <iostream>
#include <ranges>
#include <vector>

int main()
{
    std::vector<int> vec{3, 1, 4};
    if (std::ranges::find(vec, 5) != std::ranges::end(vec))
        std::cout << "found a 5 in vector vec!\n";

    int arr[]{5, 10, 15};
    if (std::ranges::find(arr, 5) != std::ranges::end(arr))
        std::cout << "found a 5 in array arr!\n";
}

Output:

found a 5 in array arr!

Notice how she found the 5 in the array but not the vector? The vector is {3, 1, 4} — no 5 in sight. The array literally starts with 5. Main character energy from arr. 👑

---

🧚 DEFECT REPORTS 🧚

The following behavior-changing defect reports were applied retroactively to previously published C++ standards. So if you read an old standard, it was lying (affectionate).

• P2602R2 — Applied to C++20. Behavior as published: there's machinery to prohibit certain non-member end found by ADL. Correct behavior: removed such machinery. So that whole "block ADL end" thing got yeeted. Good riddance, honestly. 💀

---

👑 SEE ALSO 👑

• ranges::cend (C++20) — returns a sentinel indicating the end of a read-only range. (customization point object) — she's the const version, the sensible one. 🎀
• ranges::begin (C++20) — returns an iterator to the beginning of a range. (customization point object) — the other half of the iconic duo. 🌸
• end, cend (C++11), (C++14) — returns an iterator to the end of a container or array. (function template) — the OG non-ranges versions. Vintage, but still valid. 💖

---

💜 SIGN-OFF 💜

Source: http://cppreference.com — version 2024.06.10 — page std::ranges::end(3). That's the whole footer, bestie. Stay slaying those ranges, and remember: if ranges::end is ill-formed, it's not you, it's the substitution failure. 🫶✨