Standard library header <experimental/ranges/iterator>

 

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

 

Standard Library headers

Language Support
<cstddef> <limits> <climits> <contract>	<cfloat> <cstdint> <new> <coroutine>	<typeinfo> <exception> <initializer_list> <version>	<csignal> <csetjmp> <cstdarg>
Concepts
<concepts>
Diagnostics
<stdexcept>	<cassert>	<cerrno>	<system_error>
General utilities
<utility> <memory> <memory_resource> <scoped_allocator>     <compare>	<bitset> <tuple> <optional> <any> <variant>	<type_traits> <ratio> <chrono> <typeindex> <functional>	<ctime> <cstdlib>
Strings
<string> <string_view>	<cctype> <cwctype>	<cwchar> <cuchar>	<cstring> <charconv>
Localization
<locale>	<codecvt>	<clocale>
Containers
<span> <array> <vector>	<deque> <forward_list> <list>	<map> <set> <queue>	<unordered_map> <unordered_set> <stack>
Iterators
<iterator>
Ranges
<ranges>
Algorithms
<algorithm>	<execution>
Numerics
<complex> <random>	<valarray> <numeric>	<cfenv> <cmath>	<bit>
Input/Output
<iosfwd> <ios> <iomanip> <streambuf>	<istream> <ostream> <iostream>	<sstream> <fstream> <syncstream>	<cstdio> <cinttypes> <strstream>
Regular expressions
<regex>
Filesystem support
<filesystem>
Thread support
<thread> <atomic>	<mutex> <shared_mutex>	<condition_variable> <future>
C compatibility
<ciso646> <cstdalign>	<cstdbool> <ccomplex>	<ctgmath>

 

This header is part of the ranges library.

Iterator-related concepts

Defined in namespace std::experimental::ranges

Iterator concepts

Readable	specifies that a type is readable by applying operator * (concept)
Writable	specifies that a value can be written to an iterator's referenced object (concept)
WeaklyIncrementable	specifies that a Semiregular type can be incremented with pre- and post-increment operators (concept)
Incrementable	specifies that the increment operation on a WeaklyIncrementable type is equality-preserving and that the type is EqualityComparable (concept)
Iterator	specifies that objects of a type can be incremented and dereferenced (concept)
Sentinel	specifies that objects of a type is a sentinel for an Iterator type (concept)
SizedSentinel	specifies that the - operator can be applied to an iterator and a sentinel to calculate their difference in constant time (concept)
InputIterator	specifies that a type is an input iterator, that is, its referenced values can be read and it can be both pre- and post-incremented (concept)
OutputIterator	specifies that a type is an output iterator for a given value type, that is, values of that type can be written to it and it can be both pre- and post-incremented (concept)
ForwardIterator	specifies that an InputIterator is a forward iterator, supporting equality comparison and multi-pass (concept)
BidirectionalIterator	specifies that a ForwardIterator is a bidirectional iterator, supporting movement backwards (concept)
RandomAccessIterator	specifies that a BidirectionalIterator is a random-access iterator, supporting advancement in constant time and subscripting (concept)

Indirect callable concepts

IndirectUnaryInvocableIndirectRegularUnaryInvocable	specifies that a callable type can be invoked with the result of dereferencing a Readable type (concept)
IndirectUnaryPredicate	specifies that a callable object, when invoked with the result of dereferencing a Readable type, satisfies Predicate (concept)
IndirectRelation	specifies that a callable object, when invoked with the result of dereferencing some Readable types, satisfies Relation (concept)
IndirectStrictWeakOrder	specifies that a callable object, when invoked with the result of dereferencing some Readable types, satisfies StrictWeakOrder (concept)

Common algorithm requirements

IndirectlyMovable	specifies that values may be moved from a Readable type to a Writable type (concept)
IndirectlyMovableStorable	specifies that values may be moved from a Readable type to a Writable type and that the move may be performed via an intermediate object (concept)
IndirectlyCopyable	specifies that values may be copied from a Readable type to a Writable type (concept)
IndirectlyCopyableStorable	specifies that values may be copied from a Readable type to a Writable type and that the copy may be performed via an intermediate object (concept)
IndirectlySwappable	specifies that the values referenced by two Readable types can be swapped (concept)
IndirectlyComparable	specifies that the values referenced by two Readable types can be compared (concept)
Permutable	specifies the common requirements of algorithms that reorder elements in place (concept)
Mergeable	specifies the requirements of algorithms that merge sorted sequences into an output sequence by copying elements (concept)
Sortable	specifies the common requirements of algorithms that permute sequences into ordered sequences (concept)

Concept utilities

indirect_result_of	compute the result of invoking a callable object on the result of dereferencing some set of Readable types (class template)
projected	helper template for specifying the constraints on algorithms that accept projections (class template)

Iterator primitives

Iterator utilities

Defined in namespace std::experimental::ranges
iter_move	casts the result of dereferencing an object to its associated rvalue reference type (customization point object)
iter_swap	swap the values referenced by two dereferenceable objects (customization point object)

Iterator traits

Defined in namespace std::experimental::ranges
difference_type	obtains the difference type of a WeaklyIncrementable type (class template)
value_type	obtains the value type of a Readable type (class template)
iterator_category	obtains the iterator category of an input iterator type (class template)
iterator_traits	compatibility traits class that collects an iterator’s associated types (alias template)
reference_trvalue_reference_titer_common_reference_t	obtains a dereferenceable object's associated reference types (alias template)

Iterator category tags

Defined in namespace std::experimental::ranges
input_iterator_tagoutput_iterator_tagforward_iterator_tagbidirectional_iterator_tagrandom_access_iterator_tag	empty class types used to indicate iterator categories (class)

std::iterator_traits specializations

Defined in namespace std
std::iterator_traits<InputIterator>std::iterator_traits<OutputIterator>	specializes std::iterator_traits for ranges TS iterators (class template specialization)

Iterator operations

Defined in namespace std::experimental::ranges
advance	advances an iterator by given distance (function template)
distance	returns the distance between an iterator and a sentinel, or between the beginning and the end of a range (function template)
next	increment an iterator (function template)
prev	decrement an iterator (function template)

Iterator adaptors

Defined in namespace std::experimental::ranges
reverse_iterator	iterator adaptor for reverse-order traversal (class template)
back_insert_iterator	iterator adaptor for insertion at the end of a container (class template)
front_insert_iterator	iterator adaptor for insertion at the front of a container (class template)
insert_iterator	iterator adaptor for insertion into a container (class template)
move_iterator	iterator adaptor which dereferences to an rvalue reference (class template)
move_sentinel	sentinel adaptor for use with move_iterator (class template)
common_iterator	adapt an iterator-sentinel pair into a common iterator type for use with legacy algorithms (class template)
counted_iterator	iterator adaptor that keeps track of its distance from its starting position (class template)
default_sentinel	empty sentinel type for use with iterator types that know the bound of their range (class)
dangling	wrapper for a possibly dangling iterator (class template)
safe_iterator_t	alias template that wraps the iterator type of an rvalue range with dangling (alias template)
unreachable	sentinel type used with any iterator to denote an infinite range (class)

Stream iterators

Defined in namespace std::experimental::ranges
istream_iterator	input iterator that reads from std::basic_istream (class template)
ostream_iterator	output iterator that writes to std::basic_ostream (class template)
istreambuf_iterator	input iterator that reads from std::basic_streambuf (class template)
ostreambuf_iterator	output iterator that writes to std::basic_streambuf (class template)

Synopsis

namespace std { namespace experimental { namespace ranges { inline namespace v1 {
 
template <class T> concept bool /* dereferenceable */ // exposition only
  = requires(T& t) { {*t} -> auto&&; };
 
namespace {
  constexpr /* unspecified */ iter_move = /* unspecified */;
  constexpr /* unspecified */ iter_swap = /* unspecified */;
}
 
template <class> struct difference_type;
template <class T> using difference_type_t
  = typename difference_type<T>::type;
 
template <class> struct value_type;
template <class T> using value_type_t
  = typename value_type<T>::type;
 
template <class> struct iterator_category;
template <class T> using iterator_category_t
  = typename iterator_category<T>::type;
 
template </* dereferenceable */ T> using reference_t
  = decltype(*declval<T&>());
 
template </* dereferenceable */ T>
    requires /* see definition */ using rvalue_reference_t
  = decltype(ranges::iter_move(declval<T&>()));
 
template <class In>
concept bool Readable = /* see definition */;
 
template <class Out, class T>
concept bool Writable = /* see definition */;
 
template <class I>
concept bool WeaklyIncrementable = /* see definition */;
 
template <class I>
concept bool Incrementable = /* see definition */;
 
template <class I>
concept bool Iterator = /* see definition */;
 
template <class S, class I>
concept bool Sentinel = /* see definition */;
 
template <class S, class I>
  constexpr bool disable_sized_sentinel = false;
 
template <class S, class I>
concept bool SizedSentinel = /* see definition */;
 
template <class I>
concept bool InputIterator = /* see definition */;
 
template <class I>
concept bool OutputIterator = /* see definition */;
 
template <class I>
concept bool ForwardIterator = /* see definition */;
 
template <class I>
concept bool BidirectionalIterator = /* see definition */;
 
template <class I>
concept bool RandomAccessIterator = /* see definition */;
 
template <class F, class I>
concept bool IndirectUnaryInvocable = /* see definition */;
 
template <class F, class I>
concept bool IndirectRegularUnaryInvocable = /* see definition */;
 
template <class F, class I>
concept bool IndirectUnaryPredicate = /* see definition */;
 
template <class F, class I1, class I2 = I1>
concept bool IndirectRelation = /* see definition */;
 
template <class F, class I1, class I2 = I1>
concept bool IndirectStrictWeakOrder = /* see definition */;
 
template <class> struct indirect_result_of;
 
template <class F, class... Is>
  requires Invocable<F, reference_t<Is>...>
struct indirect_result_of<F(Is...)>;
 
template <class F>
using indirect_result_of_t
  = typename indirect_result_of<F>::type;
 
template <Readable I, IndirectRegularUnaryInvocable<I> Proj>
struct projected;
 
template <WeaklyIncrementable I, class Proj>
struct difference_type<projected<I, Proj>>;
 
template <class In, class Out>
concept bool IndirectlyMovable = /* see definition */;
 
template <class In, class Out>
concept bool IndirectlyMovableStorable = /* see definition */;
 
template <class In, class Out>
concept bool IndirectlyCopyable = /* see definition */;
 
template <class In, class Out>
concept bool IndirectlyCopyableStorable = /* see definition */;
 
template <class I1, class I2 = I1>
concept bool IndirectlySwappable = /* see definition */;
 
template <class I1, class I2, class R = equal_to<>, class P1 = identity,
    class P2 = identity>
concept bool IndirectlyComparable = /* see definition */;
 
template <class I>
concept bool Permutable = /* see definition */;
 
template <class I1, class I2, class Out,
    class R = less<>, class P1 = identity, class P2 = identity>
concept bool Mergeable = /* see definition */;
 
template <class I, class R = less<>, class P = identity>
concept bool Sortable = /* see definition */;
 
template <class Iterator> using iterator_traits = /* see definition */;
 
template <Readable T> using iter_common_reference_t
  = common_reference_t<reference_t<T>, value_type_t<T>&>;
 
struct output_iterator_tag { };
struct input_iterator_tag { };
struct forward_iterator_tag : input_iterator_tag { };
struct bidirectional_iterator_tag : forward_iterator_tag { };
struct random_access_iterator_tag : bidirectional_iterator_tag { };
 
namespace {
  constexpr /* unspecified */ advance = /* unspecified */;
  constexpr /* unspecified */ distance = /* unspecified */;
  constexpr /* unspecified */ next = /* unspecified */;
  constexpr /* unspecified */ prev = /* unspecified */;
}
 
template <BidirectionalIterator I> class reverse_iterator;
 
template <class I1, class I2>
    requires EqualityComparableWith<I1, I2>
  constexpr bool operator==(
    const reverse_iterator<I1>& x,
    const reverse_iterator<I2>& y);
template <class I1, class I2>
    requires EqualityComparableWith<I1, I2>
  constexpr bool operator!=(
    const reverse_iterator<I1>& x,
    const reverse_iterator<I2>& y);
template <class I1, class I2>
    requires StrictTotallyOrderedWith<I1, I2>
  constexpr bool operator<(
    const reverse_iterator<I1>& x,
    const reverse_iterator<I2>& y);
template <class I1, class I2>
    requires StrictTotallyOrderedWith<I1, I2>
  constexpr bool operator>(
    const reverse_iterator<I1>& x,
    const reverse_iterator<I2>& y);
template <class I1, class I2>
    requires StrictTotallyOrderedWith<I1, I2>
  constexpr bool operator>=(
    const reverse_iterator<I1>& x,
    const reverse_iterator<I2>& y);
template <class I1, class I2>
    requires StrictTotallyOrderedWith<I1, I2>
  constexpr bool operator<=(
    const reverse_iterator<I1>& x,
    const reverse_iterator<I2>& y);
 
template <class I1, class I2>
    requires SizedSentinel<I1, I2>
  constexpr difference_type_t<I2> operator-(
    const reverse_iterator<I1>& x,
    const reverse_iterator<I2>& y);
template <RandomAccessIterator I>
  constexpr reverse_iterator<I> operator+(
    difference_type_t<I> n,
    const reverse_iterator<I>& x);
 
template <BidirectionalIterator I>
constexpr reverse_iterator<I> make_reverse_iterator(I i);
 
template <class Container> class back_insert_iterator;
template <class Container>
  back_insert_iterator<Container> back_inserter(Container& x);
 
template <class Container> class front_insert_iterator;
template <class Container>
  front_insert_iterator<Container> front_inserter(Container& x);
 
template <class Container> class insert_iterator;
template <class Container>
  insert_iterator<Container> inserter(Container& x, iterator_t<Container> i);
 
template <InputIterator I> class move_iterator;
 
template <class I1, class I2>
    requires EqualityComparableWith<I1, I2>
  constexpr bool operator==(
    const move_iterator<I1>& x, const move_iterator<I2>& y);
template <class I1, class I2>
    requires EqualityComparableWith<I1, I2>
  constexpr bool operator!=(
    const move_iterator<I1>& x, const move_iterator<I2>& y);
template <class I1, class I2>
    requires StrictTotallyOrderedWith<I1, I2>
  constexpr bool operator<(
    const move_iterator<I1>& x, const move_iterator<I2>& y);
template <class I1, class I2>
    requires StrictTotallyOrderedWith<I1, I2>
  constexpr bool operator<=(
    const move_iterator<I1>& x, const move_iterator<I2>& y);
template <class I1, class I2>
    requires StrictTotallyOrderedWith<I1, I2>
  constexpr bool operator>(
    const move_iterator<I1>& x, const move_iterator<I2>& y);
template <class I1, class I2>
    requires StrictTotallyOrderedWith<I1, I2>
  constexpr bool operator>=(
    const move_iterator<I1>& x, const move_iterator<I2>& y);
 
template <class I1, class I2>
    requires SizedSentinel<I1, I2>
  constexpr difference_type_t<I2> operator-(
    const move_iterator<I1>& x,
    const move_iterator<I2>& y);
template <RandomAccessIterator I>
  constexpr move_iterator<I> operator+(
    difference_type_t<I> n,
    const move_iterator<I>& x);
 
template <InputIterator I>
  constexpr move_iterator<I> make_move_iterator(I i);
 
template <Semiregular S> class move_sentinel;
 
template <class I, Sentinel<I> S>
  constexpr bool operator==(
    const move_iterator<I>& i, const move_sentinel<S>& s);
template <class I, Sentinel<I> S>
  constexpr bool operator==(
    const move_sentinel<S>& s, const move_iterator<I>& i);
template <class I, Sentinel<I> S>
  constexpr bool operator!=(
    const move_iterator<I>& i, const move_sentinel<S>& s);
template <class I, Sentinel<I> S>
  constexpr bool operator!=(
    const move_sentinel<S>& s, const move_iterator<I>& i);
 
template <class I, SizedSentinel<I> S>
  constexpr difference_type_t<I> operator-(
    const move_sentinel<S>& s, const move_iterator<I>& i);
template <class I, SizedSentinel<I> S>
  constexpr difference_type_t<I> operator-(
    const move_iterator<I>& i, const move_sentinel<S>& s);
 
template <Semiregular S>
  constexpr move_sentinel<S> make_move_sentinel(S s);
 
template <Iterator I, Sentinel<I> S>
  requires !Same<I, S>
class common_iterator;
 
template <Readable I, class S>
struct value_type<common_iterator<I, S>>;
 
template <InputIterator I, class S>
struct iterator_category<common_iterator<I, S>>;
 
template <ForwardIterator I, class S>
struct iterator_category<common_iterator<I, S>>;
 
template <class I1, class I2, Sentinel<I2> S1, Sentinel<I1> S2>
bool operator==(
  const common_iterator<I1, S1>& x, const common_iterator<I2, S2>& y);
template <class I1, class I2, Sentinel<I2> S1, Sentinel<I1> S2>
  requires EqualityComparableWith<I1, I2>
bool operator==(
  const common_iterator<I1, S1>& x, const common_iterator<I2, S2>& y);
template <class I1, class I2, Sentinel<I2> S1, Sentinel<I1> S2>
bool operator!=(
  const common_iterator<I1, S1>& x, const common_iterator<I2, S2>& y);
 
template <class I2, SizedSentinel<I2> I1, SizedSentinel<I2> S1, SizedSentinel<I1> S2>
difference_type_t<I2> operator-(
  const common_iterator<I1, S1>& x, const common_iterator<I2, S2>& y);
 
class default_sentinel;
 
template <Iterator I> class counted_iterator;
 
template <class I1, class I2>
    requires Common<I1, I2>
  constexpr bool operator==(
    const counted_iterator<I1>& x, const counted_iterator<I2>& y);
constexpr bool operator==(
  const counted_iterator<auto>& x, default_sentinel);
constexpr bool operator==(
  default_sentinel, const counted_iterator<auto>& x);
template <class I1, class I2>
    requires Common<I1, I2>
  constexpr bool operator!=(
    const counted_iterator<I1>& x, const counted_iterator<I2>& y);
constexpr bool operator!=(
  const counted_iterator<auto>& x, default_sentinel y);
constexpr bool operator!=(
  default_sentinel x, const counted_iterator<auto>& y);
template <class I1, class I2>
    requires Common<I1, I2>
  constexpr bool operator<(
    const counted_iterator<I1>& x, const counted_iterator<I2>& y);
template <class I1, class I2>
    requires Common<I1, I2>
  constexpr bool operator<=(
    const counted_iterator<I1>& x, const counted_iterator<I2>& y);
template <class I1, class I2>
    requires Common<I1, I2>
  constexpr bool operator>(
    const counted_iterator<I1>& x, const counted_iterator<I2>& y);
template <class I1, class I2>
    requires Common<I1, I2>
  constexpr bool operator>=(
    const counted_iterator<I1>& x, const counted_iterator<I2>& y);
 
template <class I1, class I2>
    requires Common<I1, I2>
  constexpr difference_type_t<I2> operator-(
    const counted_iterator<I1>& x, const counted_iterator<I2>& y);
template <class I>
  constexpr difference_type_t<I> operator-(
    const counted_iterator<I>& x, default_sentinel y);
template <class I>
  constexpr difference_type_t<I> operator-(
    default_sentinel x, const counted_iterator<I>& y);
template <RandomAccessIterator I>
  constexpr counted_iterator<I>
    operator+(difference_type_t<I> n, const counted_iterator<I>& x);
 
template <Iterator I>
  constexpr counted_iterator<I> make_counted_iterator(I i, difference_type_t<I> n);
 
class unreachable;
template <Iterator I>
  constexpr bool operator==(const I&, unreachable) noexcept;
template <Iterator I>
  constexpr bool operator==(unreachable, const I&) noexcept;
template <Iterator I>
  constexpr bool operator!=(const I&, unreachable) noexcept;
template <Iterator I>
  constexpr bool operator!=(unreachable, const I&) noexcept;
 
template <class T> class dangling;
 
template <class T, class charT = char, class traits = char_traits<charT>,
    class Distance = ptrdiff_t>
  class istream_iterator;
 
template <class T, class charT, class traits, class Distance>
  bool operator==(const istream_iterator<T, charT, traits, Distance>& x,
    const istream_iterator<T, charT, traits, Distance>& y);
template <class T, class charT, class traits, class Distance>
  bool operator==(default_sentinel x,
    const istream_iterator<T, charT, traits, Distance>& y);
template <class T, class charT, class traits, class Distance>
  bool operator==(const istream_iterator<T, charT, traits, Distance>& x,
    default_sentinel y);
template <class T, class charT, class traits, class Distance>
  bool operator!=(const istream_iterator<T, charT, traits, Distance>& x,
    const istream_iterator<T, charT, traits, Distance>& y);
template <class T, class charT, class traits, class Distance>
  bool operator!=(default_sentinel x,
    const istream_iterator<T, charT, traits, Distance>& y);
template <class T, class charT, class traits, class Distance>
  bool operator!=(const istream_iterator<T, charT, traits, Distance>& x,
    default_sentinel y);
 
template <class T, class charT = char, class traits = char_traits<charT>>
  class ostream_iterator;
 
template <class charT, class traits = char_traits<charT> >
  class istreambuf_iterator;
 
template <class charT, class traits>
  bool operator==(const istreambuf_iterator<charT, traits>& a,
    const istreambuf_iterator<charT, traits>& b);
template <class charT, class traits>
  bool operator==(default_sentinel a,
    const istreambuf_iterator<charT, traits>& b);
template <class charT, class traits>
  bool operator==(const istreambuf_iterator<charT, traits>& a,
    default_sentinel b);
template <class charT, class traits>
  bool operator!=(const istreambuf_iterator<charT, traits>& a,
    const istreambuf_iterator<charT, traits>& b);
template <class charT, class traits>
  bool operator!=(default_sentinel a,
    const istreambuf_iterator<charT, traits>& b);
template <class charT, class traits>
  bool operator!=(const istreambuf_iterator<charT, traits>& a,
    default_sentinel b);
 
template <class charT, class traits = char_traits<charT> >
  class ostreambuf_iterator;
 
}}}}
 
namespace std {
  template <experimental::ranges::Iterator Out>
    struct iterator_traits<Out>;
  template <experimental::ranges::InputIterator In>
    struct iterator_traits<In>;
  template <experimental::ranges::InputIterator In>
      requires experimental::ranges::Sentinel<In, In>
    struct iterator_traits;
}