Ranges library (C++20)

 

C++

Language

Standard Library Headers

Freestanding and hosted implementations

Named requirements

Language support library

Concepts library (C++20)

Diagnostics library

Utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Filesystem library (C++17)

Technical Specifications

 

Ranges library

Range access
begincbegin endcend	rbegincrbegin rendcrend	size empty datacdata
Range primitives
iterator_t	sentinel_t
Dangling iterator handling
dangling	safe_iterator_t	safe_subrange_t
Range concepts
Range SizedRange View	InputRange OutputRange ForwardRange	BidirectionalRange RandomAccessRange ContiguousRange	CommonRange ViewableRange
Views
view_interface	subrange
Semiregular wrapper
Factories
empty_viewview::empty	single_viewview::single	iota_viewview::iota	view::counted
Adaptors
all_viewview::all ref_view filter_viewview::filter	transform_viewview::transform                                take_viewview::take	join_viewview::join split_viewview::split	common_viewview::common reverse_viewview::reverse

 

The ranges library provides components for dealing with ranges of elements, including a variety of view adapters.

Defined in header <ranges>
namespace std {     namespace view = ranges::view; }

The namespace alias std::view is provided as a shorthand for std::ranges::view.

Defined in header <ranges>
Defined in namespace std::ranges
Range access
begincbegin	returns an iterator to the beginning of a range (customization point object)
endcend	returns an iterator to the end of a range (customization point object)
rbegincrbegin	returns a reverse iterator to a range (customization point object)
rendcrend	returns a reverse end iterator to a range (customization point object)
size	obtains the size of a range whose size can be calculated in constant time (customization point object)
empty	checks whether a range is empty (customization point object)
datacdata	obtains a pointer to the beginning of a contiguous range (customization point object)
Range primitives
iterator_tsentinel_t	obtains the iterator and sentinel types of a range (alias template)
Dangling iterator handling
dangling	a placeholder type indicating that an iterator or a subrange should not be returned since it would be dangling (class)
safe_iterator_tsafe_subrange_t	obtains iterator type or subrange type of a Range which also models __ForwardingRange (alias template)
Range concepts
Range	specifies that a type is a range, that is, it provides a begin iterator and an end sentinel (concept)
SizedRange	specifies that a range knows its size in constant time (concept)
View	specifies that a range is a view, that is, it has constant time copy/move/assignment (concept)
InputRange	specifies a range whose iterator type satisfies InputIterator (concept)
OutputRange	specifies a range whose iterator type satisfies OutputIterator (concept)
ForwardRange	specifies a range whose iterator type satisfies ForwardIterator (concept)
BidirectionalRange	specifies a range whose iterator type satisfies BidirectionalIterator (concept)
RandomAccessRange	specifies a range whose iterator type satisfies RandomAccessIterator (concept)
ContiguousRange	specifies a range whose iterator type satisfies ContiguousIterator (concept)
CommonRange	specifies that a range has identical iterator and sentinel types (concept)
ViewableRange	specifies the requirements for a Range to be safely convertible to a View (concept)
Views
view_interface	helper class template for defining Views, using the curiously recurring template pattern (class template)
subrange	combines an iterator-sentinel pair into a View (class template)

Range factories

Defined in header <ranges>
Defined in namespace std::ranges
empty_viewview::empty	an empty View with no elements (class template) (variable template)
single_viewview::single	a View that contains a single element of a specified value (class template) (customization point object)
iota_viewview::iota	a View consisting of a sequence generated by repeatedly incrementing an initial value (class template) (customization point object)
view::counted	creates a subrange from an iterator and a count (customization point object)

Range adaptors

Range adaptors accept ViewableRange as their first arguments and returns a View. They can also be chained using the pipe operator: if C and D are a range adaptors and R is a ViewableRange, these two expressions are equivalent:

D(C(R))
R | C | D

If an adaptor takes multiple arguments, these forms are equivalent:

adaptor(range, args...)
adaptor(args...)(range)
range | adaptor(args...)

Defined in header <ranges>
Defined in namespace std::ranges
all_viewview::all	a View that includes all elements of a Range (alias template) (range adaptor object)
ref_view	a View of the elements of some other Range (class template)
filter_viewview::filter	a View that consists of the elements of a Range that satisfies a predicate (class template) (range adaptor object)
transform_viewview::transform	a View of a sequence that applies a transformation function to each element (class template) (range adaptor object)
take_viewview::take	a View consisting of the first N elements of another View (class template) (range adaptor object)
join_viewview::join	a View consisting of the sequence obtained from flattening a View of Ranges (class template) (range adaptor object)
split_viewview::split	a View over the subranges obtained from splitting another View using a delimiter (class template) (range adaptor object)
common_viewview::common	converts a View into a CommonRange (class template) (range adaptor object)
reverse_viewview::reverse	a View that iterates over the elements of another bidirectional view in reverse order (class template) (range adaptor object)

Some range adaptors wrap their element or function object with the semiregular wrapper.

Helper concepts

Following exposition-only concepts are used for several types, but they are not parts of the interface of standard library.

template<class R>   concept __SimpleView =                         // exposition only     View<R> && Range<const R> &&     Same<std::ranges::iterator_t<R>, std::ranges::iterator_t<const R>> &&     Same<std::ranges::sentinel_t<R>, std::ranges::sentinel_t<const R>>;
template<class T, class U>   concept __NotSameAs =                          // exposition only     !Same<std::remove_cvref_t<T>, std::remove_cvref_t<U>>;

Example

Run this code

#include <vector>
#include <ranges>
#include <iostream>
 
int main()
{
  std::vector<int> ints{0,1,2,3,4,5};
  auto even = [](int i){ return 0 == i % 2; };
  auto square = [](int i) { return i * i; };
 
  for (int i : ints | std::view::filter(even) | std::view::transform(square)) {
    std::cout << i << ' ';
  }
}

Output:

0 4 16