std::ranges...rowed_range(3)

💅 std::ranges::borrowed_range, std::ranges::enable_borrowed_range 💅

okay so real talk — this is the std::ranges...rowed_range(3) page from the C++ Standard Libary manual (yes that's how the header spells it, iconic typo tbh, we move), and it's about two things that are lowkey the same vibe: std::ranges::borrowed_range and std::ranges::enable_borrowed_range. Bestie, this one's a banger, let's go ✨

---

🎀 NAME 🎀

• std::ranges::borrowed_range
• std::ranges::enable_borrowed_range

that's it, those two, they're a package deal 🫶

---

✨ Synopsis ✨

bestie it's literally defined in header <ranges>:

template< class R >
concept borrowed_range =
    ranges::range<R> &&                                          (1)
    (std::is_lvalue_reference_v<R> ||
     ranges::enable_borrowed_range<std::remove_cvref_t<R>>);

template< class R >                                              (2)
inline constexpr bool enable_borrowed_range = false;

both of these are (since C++20) 💖

1. the concept borrowed_range defines the requirements of a range such that a function can take it by value and return iterators obtained from it without danger of dangling — no cap, that's the whole point, it's the "trust me, the pointers stay valid after I'm gone" concept 🦋
2. the enable_borrowed_range variable template is used to indicate whether a range is a borrowed_range. the primary template is defined as false — so by default, bestie, you are not borrowed 🙈

---

👑 Specializations 👑

okay this is the part where the standard library goes "these ones are safe fr fr". specializations of enable_borrowed_range for all specializations of the following standard templates are defined as true:

• std::basic_string_view
• std::span
• std::ranges::subrange
• std::ranges::ref_view
• std::ranges::empty_view
• std::ranges::iota_view

so iconic of them 💅

---

then, specialization of enable_borrowed_range for the following standard range adaptors are defined as true if and only if std::ranges::enable_borrowed_range<V> is true, where V is the underlying view type:

• std::ranges::owning_view
• std::ranges::take_view
• std::ranges::drop_view
• std::ranges::drop_while_view
• std::ranges::common_view
• std::ranges::reverse_view
• std::ranges::elements_view
• std::ranges::adjacent_view (since C++23)

like, they inherit the borrowed-ness of whatever they wrap? the way they just pass the vibe check along 🧚

---

specialization for std::ranges::zip_view is defined as true if and only if (std::ranges::enable_borrowed_range<Vs> && ...) is true, (since C++23) where Vs... are all view types it adapts. so it's an all-or-nothing situation, every single one has to be borrowed or nobody is 🔥

---

and now the part where YOU get to play god: a program may specialize enable_borrowed_range to true for cv-unqualified program-defined types which model borrowed_range, and false for types which do not. Such specializations shall be usable in constant expression and have type const bool. — read that carefully bestie, const bool, not bool, and it has to work in a constant expression, don't @ me 😤

---

🌸 Example 🌸

it demonstrates the specializations of enable_borrowed_range for program defined types. Such specializations protect against potentially dangling results. we love a safety feature 🫶

(there's a // Run this code link on the page, go press it and watch it slay)

#include <algorithm>
#include <array>
#include <cstddef>
#include <iostream>
#include <ranges>
#include <span>
#include <type_traits>

template<typename T, std::size_t N>
struct MyRange : std::array<T, N> {};

template<typename T, std::size_t N>
inline constexpr bool std::ranges::enable_borrowed_range<MyRange<T, N>> = false;

template<typename T, std::size_t N>
struct MyBorrowedRange : std::span<T, N> {};

template<typename T, std::size_t N>
inline constexpr bool std::ranges::enable_borrowed_range<MyBorrowedRange<T, N>> = true;

int main()
{
    static_assert(std::ranges::range<MyRange<int, 8>>);
    static_assert(std::ranges::borrowed_range<MyRange<int, 8>> == false);
    static_assert(std::ranges::range<MyBorrowedRange<int, 8>>);
    static_assert(std::ranges::borrowed_range<MyBorrowedRange<int, 8>> == true);

    auto getMyRangeByValue = []{ return MyRange<int, 4>{{1, 2, 42, 3}}; };
    auto dangling_iter = std::ranges::max_element(getMyRangeByValue());
    static_assert(std::is_same_v<std::ranges::dangling, decltype(dangling_iter)>);
//  *dangling_iter; // compilation error (i.e. dangling protection works.)

    auto my = MyRange<int, 4>{{1, 2, 42, 3}};
    auto valid_iter = std::ranges::max_element(my);
    std::cout << *valid_iter << ' '; // OK: 42

    auto getMyBorrowedRangeByValue = []
    {
        static int sa[4]{1, 2, 42, 3};
        return MyBorrowedRange<int, std::size(sa)>{sa};
    };
    auto valid_iter2 = std::ranges::max_element(getMyBorrowedRangeByValue());
    std::cout << *valid_iter2 << '\n'; // OK: 42
}

and the commented-out *dangling_iter; line? that's the compilation error doing its job. dangling protection works, bestie. it ATE 💀✨

---

💖 Output 💖

42 42

both 42s. chef's kiss. no notes. 🔥

---

🌈 See also 🌈

• ranges::dangling (C++20) — a placeholder type indicating that an iterator or a subrange should not be returned since it would be dangling (class)

the bodyguard of the group chat honestly 🫶

---

k that's the whole page, mwah 💋

shoutout to cppreference.com, dated 2024.06.10 — the source and version of this little masterpiece — catch you on the next manpage bestie, stay borrowed, stay safe, and never return an iterator to a temporary 🎀💜