<ranges> alias templates
An alias template is an alias for another type, which can make code more readable. For example, the following alias, conditional_t, is an alias for either borrowed_range or dangling range, depending on the kind of range that's passed in:
// requires /std:c++20, or later
#include <iostream>
#include <list>
#include <span>
#include <algorithm>
#include <ranges>
#include <type_traits>
using namespace std;
// Define an alias template called my_iterator_t
// If the provided range R is a borrowed_range, then the
// returned type is iterator_t<R>; otherwise, ranges::dangling
template<ranges::range R>
using my_iterator_t = conditional_t<
ranges::borrowed_range<R>,
ranges::iterator_t<R>, ranges::dangling>;
int main()
{
my_iterator_t<list<int>> aDanglingRange; // list<> isn't a borrowed_range
constexpr bool same = same_as<
decltype(aDanglingRange),
ranges::dangling>; // true
my_iterator_t<span<int, 5>> anIterator_t; // span<> is a borrowed_range
constexpr bool same2 = same_as<
decltype(anIterator_t),
ranges::iterator_t<span<int, 5>>>; // true
cout << boolalpha << same << "," << same2; // outputs true, true
}
For more information about alias templates, see Aliases and typedefs.
The <algorithm> header defines the following alias templates that determine the types of iterators and sentinels for a range:
| Alias template | Description |
|---|---|
borrowed_iterator_tC++20 |
Determine if an iterator returned for a range refers to a range whose lifetime has ended. |
borrowed_subrange_tC++20 |
Determine if a subrange returned for a range refers to a range whose lifetime has ended. |
danglingC++20 |
Indicates that the returned iterator of a range/subrange outlives the lifetime of the range/subrange it refers to. |
iterator_tC++20 |
Returns the iterator type for the specified range. |
range_difference_tC++20 |
Returns the difference type for the specified range's iterator. |
range_reference_tC++20 |
Returns the reference type for the specified range's iterator. |
range_rvalue_reference_tC++20 |
Returns the rvalue reference type for the specified range's iterator. In other words, the rvalue reference type of the range's elements. |
range_size_tC++20 |
Returns the type used to report the specified range's size. |
range_value_tC++20 |
Returns the value type of specified range's iterator. Or in other words, the type of the elements in the range. |
sentinel_tC++20 |
Returns the sentinel type for the specified range. |
borrowed_iterator_t
When an algorithm function that returns an iterator is called with an rvalue range argument, the range's lifetime could end following the call. That means the returned iterator could refer to elements whose lifetimes have ended. Using a dangling iterator results in undefined behavior.
This template alias returns ranges::dangling to indicate that this is the situation for the given range argument, or std::ranges::iterator_t<R> to indicate that it's safe to use the returned iterator because the range it refers to models borrowed_range or the range was passed as an lvalue.
template<ranges::range R>
using borrowed_iterator_t = conditional_t<ranges::borrowed_range<R>,
ranges::iterator_t<R>, ranges::dangling>;
Parameters
R
The range to test.
Remarks
The lifetime of an rvalue range can end following a function call whether the range models borrowed_range or not. If it's a borrowed_range, you may be able to continue to use the iterators with well-defined behavior regardless of when the range's lifetime ends.
Cases where this isn't true are, for example, for containers like vector or list because when the container's lifetime ends, the iterators would refer to elements that have been destroyed.
You can continue to use the iterators for a borrowed_range, for example, for a view like iota_view<int>{0, 42} whose iterators are over set of values that aren't subject to being destroyed because they're generated on demand.
If an algorithm function is passed a range whose iterators depend on its lifetime, ranges::dangling is returned instead of an iterator or subrange, so potential misuse is detected at compile time.
Example: borrowed_iterator_t
The following example shows how borrowed_iterator_t detects a dangling iterator. The function ranges::max_element() uses this template alias to determine the return type:
// requires /std:c++20, or later
#include <vector>
#include <span>
#include <ranges>
#include <iostream>
#include <algorithm>
using namespace std;
int main()
{
// Not dangling ------------------
int a[] = {0,1,2,3};
// not dangling even though an rvalue because span models ranges::borrowed
auto result1 = ranges::max_element(span{a});
cout << boolalpha << ranges::borrowed_range<decltype(span{a})> << endl; // outputs true because the temporary models ranges::borrowed
cout << same_as<decltype(result1), ranges::dangling> << endl; // outputs false because the result isn't dangling
vector<int> v{0,1,2,3}; // doesn't model ranges::borrowed
auto result2 = ranges::max_element(v); // Yet not dangling because passed as an lvalue
cout << same_as<decltype(result2), ranges::dangling> << endl; // outputs false because the result isn't dangling
// Dangling ------------------
auto result3 = ranges::max_element(vector{0,1,2,3}); // dangling because vector doesn't model ranges::borrowed and is passed as an rvalue
cout << same_as<decltype(result3), ranges::dangling>; // outputs true because the result is dangling
}
true
false
false
true
borrowed_subrange_t
When an algorithm function that returns a subrange is called with an rvalue range argument, the range's lifetime could end following the call. That means the returned subrange could refer to elements whose lifetimes have ended. Using a dangling subrange results in undefined behavior.
This template alias either returns ranges::dangling to indicate that this could be the situation for the given range argument, or subrange<ranges::iterator_t<R>> to indicate that it's safe to use the returned subrange because either the range whose elements it refers to models borrowed_range or the range was passed as an lvalue.
template<ranges::range R>
using borrowed_subrange_t = conditional_t<ranges::borrowed_range<R>,
ranges::subrange<ranges::iterator_t<R>>, ranges::dangling>;
Parameters
R
The range to test.
Remarks
The lifetime of an rvalue range can end following a function call whether the range models borrowed_range or not. If it's a borrowed_range, you may be able to continue to use the iterators with well-defined behavior regardless of when the range's lifetime ends.
Cases where this isn't true are, for example, for containers like vector or list because when the container's lifetime ends, the iterators would refer to elements that have been destroyed.
You can continue to use the iterators for a borrowed_range, for example, for a view like iota_view<int>{0, 42} whose iterators are over set of values that aren't subject to being destroyed because they're generated on demand.
If an algorithm function is passed a range whose iterators depend on its lifetime, ranges::dangling is returned instead of a subrange so that potential misuse is detected at compile time.
Example: borrowed_subrange_t
The following example shows how borrowed_subrange_t detects a dangling iterator because equal_range() and max_element use this template alias to determine the return type:
// requires /std:c++20, or later
#include <vector>
#include <iostream>
#include <algorithm>
#include <span>
#include <ranges>
int main()
{
using namespace std;
// Not dangling ------------------
vector vec{0, 1, 1, 2};
auto result1 = ranges::equal_range(span{vec}, 1); // not dangling even though passing as an rvalue because span models borrowed_range
cout << boolalpha << ranges::borrowed_range<decltype(span{vec})> << endl; // true because the temporary is a borrowed range
cout << boolalpha << same_as<decltype(result1), ranges::dangling> << endl; // false because the result isn't dangling
// result2 isn't dangling even though vec doesn't model ranges::borrowed because it's an lvalue
auto result2 = ranges::max_element(vec);
cout << boolalpha << ranges::borrowed_range<decltype(vec)> << endl; // false because vector isn't a borrowed_range
cout << boolalpha << same_as<decltype(result2), ranges::dangling> << endl; // false because the result isn't dangling
// Dangling -----------------------
// result3 is dangling because the temporary is an rvalue that doesn't model borrowed_range
auto result3 = ranges::max_element(vector{0,1,1,2});
cout << boolalpha << same_as<decltype(result3), ranges::dangling> << endl; // true because the result is dangling
}
true
false
false
false
true
dangling
If an algorithm function that returns an iterator or a subrange is called with an rvalue range argument, the range argument's lifetime could end following the call. That means the returned iterator or subrange could refer to elements whose lifetimes have ended. Using a dangling iterator or subrange results in undefined behavior.
If an algorithm function is passed a range whose iterators depend on its lifetime, ranges::dangling is returned instead of an iterator or subrange so that potential misuse is detected at compile time.
1) constexpr dangling() noexcept = default;
2) template<class... Args>
constexpr dangling(Args&&...) noexcept {}
Parameters
Args
A variable number of non-void types. They have no effect. The arguments are a convenience so that you don't need different code paths to handle constructing the iterator type versus the dangling type. This is useful when the passed in value indicates that dangling should be returned instead of an iterator.
Example: dangling
The following example shows how max_element detects a dangling iterator.
// requires /std:c++20, or later
#include <vector>
#include <iostream>
#include <ranges>
#include <algorithm>
using namespace std;
int main()
{
auto result1 = ranges::max_element(vector{1,2,3}); // dangling because vector doesn't model ranges::borrowed and is passed as an rvalue
cout << boolalpha << same_as<decltype(result1), ranges::dangling> << endl; // outputs true because the result is dangling
vector<int> v{3,4,5};
auto result2 = ranges::max_element(v); // Not dangling because passed as an lvalue
cout << same_as<decltype(result2), ranges::dangling>; // outputs false because the result isn't dangling
}
true
false
iterator_t
This template alias returns the iterator type used to iterate over the provided range type.
template<class T>
using iterator_t = decltype(ranges::begin(declval<T&>()));
Parameters
T
The range type to get the iterator type for.
Example: iterator_t
The following example shows how iterator_t can be used to declare an iterator for a vector:
// requires /std:c++20, or later
#include <vector>
#include <ranges>
#include <iostream>
int main()
{
using namespace std;
vector<int> v{1,2,3};
ranges::iterator_t<decltype(v)> it = v.begin();
cout << *it << "\n"; // outputs 1
cout << typeid(it).name(); // outputs class _Vector_iterator<class _Vector_val<struct _Simple_types<int>>>
}
1
class std::_Vector_iterator<class std::_Vector_val<struct std::_Simple_types<int> > >
range_difference_t
Returns the difference type for the specified range's iterator.
template<range R>
using range_difference_t = iter_difference_t<iterator_t<R>>;
Parameters
R
The range whose iterator will provide the difference type.
Example: range_difference_t
The following example shows how range_difference_t is used to hold the distance between elements in a range:
// requires /std:c++20, or later
#include <vector>
#include <ranges>
#include <iostream>
int main()
{
using namespace std;
vector<int> v{1,2,3};
auto findIt = ranges::find(v, 2);
// type of distance is ptrdiff_t
ranges::range_difference_t<decltype(v)> distance = ranges::distance(v.begin(), findIt);
cout << distance << endl; // outputs 1
}
1
range_reference_t
Returns the reference type for the specified range's iterator. In other words, the reference type of the range's elements.
template <range R>
using range_reference_t = iter_reference_t<ranges::iterator_t<R>>;
Parameters
R
The range for which the reference type of its iterator type is returned.
Example: range_reference_t
The following example shows range_reference_t referring to the type of the elements in a range:
// requires /std:c++20, or later
#include <vector>
#include <ranges>
#include <iostream>
int main()
{
using namespace std;
vector<int> v{1,2,3};
ranges::range_reference_t<decltype(v)> ref = v[0];
cout << ref << endl; // outputs 1
cout << typeid(ref).name() << endl; // outputs int
}
1
int
range_rvalue_reference_t
Returns the rvalue reference type for the specified range's iterator. In other words, the rvalue reference type of the range's elements.
template <range R>
using range_rvalue_reference_t = iter_reference_t<ranges::iterator_t<R>>;
Parameters
R
The range to get the rvalue reference type to its iterator type.
Example: range_rvalue_reference_t
The following example shows range_rvalue_reference_t referring to a rvalue type of the elements in a range:
// requires /std:c++20, or later
#include <vector>
#include <ranges>
#include <iostream>
int main()
{
using namespace std;
vector<int> v{1,2,3};
ranges::range_rvalue_reference_t<decltype(v)> elementRvalueType = v[0] * 10; // elementRvalueType is int&&
cout << elementRvalueType << endl; // outputs 10
cout << typeid(elementRvalueType).name() << endl; // outputs int
}
10
int
range_size_t
Returns the type of the size function for the specified sized_range.
template <range R>
using range_size_t = iter_reference_t<ranges::iterator_t<R>>;
Parameters
R
The range to get the type of its size function.
Example: range_size_t
The following example shows range_size_t referring to the number of elements in a range:
// requires /std:c++20, or later
#include <vector>
#include <iostream>
#include <ranges>
int main()
{
using namespace std;
vector<int> v{1,2,3};
ranges::range_size_t<decltype(v)> size = v.size();
cout << size << endl; // outputs 3
cout << typeid(size).name(); // outputs unsigned __int64
}
3
unsigned __int64
range_value_t
Returns the value type of specified range's iterator. Or in other words, the type of the elements in the range.
template <ranges::range R>
using range_value_t = iter_value_t<ranges::iterator_t<R>>;
Parameters
R
The range to get the value type of its iterator.
Example: range_value_t
The following example shows how range_value_t refers to the type of elements in a range:
// requires /std:c++20, or later
#include <vector>
#include <ranges>
#include <iostream>
int main()
{
using namespace std;
vector<int> v{1,2,3};
ranges::range_value_t<decltype(v)> elementType = v[2]; // elementType is an int
cout << elementType << endl; // outputs 3
cout << typeid(elementType).name() << endl; // outputs int
}
3
unsigned int
sentinel_t
Returns the sentinel type for the specified range.
template <range R>
using sentinel_t = decltype(ranges::end(declval<R&>()));
Parameters
R
The range to get the sentinel type for.
Example: sentinel_t
The following example shows using sentinel_t to determine whether the iterator type and sentinel type are the same:
// requires /std:c++20, or later
#include <iostream>
#include <list>
#include <ranges>
int main()
{
using namespace std;
list myList{1, 2, 3};
ranges::subrange count = std::views::counted(myList.begin(), myList.size());
ranges::iterator_t<decltype(count)> first;
ranges::sentinel_t<decltype(count)> last;
// The iterator type and the sentinel type of a subrange
// obtained from views::counted are not the same
cout << boolalpha << is_same<decltype(first), decltype(last)>::value << endl; // outputs false
cout << "iter: " << typeid(first).name() << "\n\n end: " << typeid(last).name() << endl;
}
false
iter: class std::counted_iterator<class std::_List_iterator<class std::_List_val<struct std::_List_simple_types<int> > > >
end: struct std::default_sentinel_t