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

 

C++

Compiler support

Freestanding and hosted

Language

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Technical specifications

Symbols index

External libraries

 

Ranges library

Range access
begin cbegin end cend	rbegin crbegin rend crend	size ssize data cdata	empty
Range primitives
iterator_tsentinel_t	range_size_trange_difference_t	range_reference_trange_rvalue_reference_t	range_value_t
Dangling iterator handling
dangling	borrowed_iterator_t	borrowed_subrange_t
Range concepts
range borrowed_range    sized_range	common_range view viewable_range	input_range output_range forward_range	bidirectional_range random_access_range contiguous_range
Views
view_interface	subrange
Factories
empty_viewviews::empty	single_viewviews::single	iota_viewviews::iota	basic_istream_viewistream_view
Adaptors
views::all_tviews::all common_viewviews::common filter_viewviews::filter reverse_viewviews::reverse	take_viewviews::take take_while_viewviews::take_while drop_viewviews::drop drop_while_viewviews::drop_while	elements_viewviews::elements keys_viewviews::keys values_viewviews::values transform_viewviews::transform	join_viewviews::join split_viewviews::split lazy_split_viewviews::lazy_split ref_view views::counted
Range adaptor objects
Range adaptor closure objects
Helper items
copyable-box	simple-view

 

Defined in header <ranges>
template<class R> concept borrowed_range =     ranges::range<R> &&     (std::is_lvalue_reference_v<R> || ranges::enable_borrowed_range<std::remove_cvref_t<R>>);	(1)
template<class R> inline constexpr bool enable_borrowed_range = false;	(2)

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.

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.

Semantic requirements

Given an expression e such that decltype((e)) is T, T models borrowed_range only if the validity of iterators obtained from the object denoted by e is not tied to the lifetime of that object.

Specializations

Specializations of enable_borrow_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

Specialization of enable_borrow_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::take_view
• std::ranges::drop_view
• std::ranges::drop_while_view
• std::ranges::common_view
• std::ranges::reverse_view
• std::ranges::elements_view

Users 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 expressions and have type const bool.

Example

Demonstrates the specializations of enable_borrowed_range for program defined types. Such specializations protect against potentially dangling results.

Run this code

#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
}

Output:

42 42

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)