25 Iterators library [iterators]

25.2 Header <iterator> synopsis [iterator.synopsis]

#include <compare> // see [compare.syn] #include <concepts> // see [concepts.syn] namespace std { template<class T> using with-reference = T&; // exposition only template<class T> concept can-reference // exposition only = requires { typename with-reference<T>; }; template<class T> concept dereferenceable // exposition only = requires(T& t) { { *t } -> can-reference; // not required to be equality-preserving }; // [iterator.assoc.types], associated types // [incrementable.traits], incrementable traits template<class> struct incrementable_traits; // freestanding template<class T> using iter_difference_t = see below; // freestanding // [readable.traits], indirectly readable traits template<class> struct indirectly_readable_traits; // freestanding template<class T> using iter_value_t = see below; // freestanding // [iterator.traits], iterator traits template<class I> struct iterator_traits; // freestanding template<class T> requires is_object_v<T> struct iterator_traits<T*>; // freestanding template<dereferenceable T> using iter_reference_t = decltype(*declval<T&>()); // freestanding namespace ranges { // [iterator.cust], customization point objects inline namespace unspecified { // [iterator.cust.move], ranges​::​iter_move inline constexpr unspecified iter_move = unspecified; // freestanding // [iterator.cust.swap], ranges​::​iter_swap inline constexpr unspecified iter_swap = unspecified; // freestanding } } template<dereferenceable T> requires requires(T& t) { { ranges::iter_move(t) } -> can-reference; } using iter_rvalue_reference_t // freestanding = decltype(ranges::iter_move(declval<T&>())); // [iterator.concepts], iterator concepts // [iterator.concept.readable], concept indirectly_readable template<class In> concept indirectly_readable = see below; // freestanding template<indirectly_readable T> using indirect-value-t = see below; // exposition only template<indirectly_readable T> using iter_common_reference_t = // freestanding common_reference_t<iter_reference_t<T>, indirect-value-t<T>>; // [iterator.concept.writable], concept indirectly_writable template<class Out, class T> concept indirectly_writable = see below; // freestanding // [iterator.concept.winc], concept weakly_incrementable template<class I> concept weakly_incrementable = see below; // freestanding // [iterator.concept.inc], concept incrementable template<class I> concept incrementable = see below; // freestanding // [iterator.concept.iterator], concept input_or_output_iterator template<class I> concept input_or_output_iterator = see below; // freestanding // [iterator.concept.sentinel], concept sentinel_for template<class S, class I> concept sentinel_for = see below; // freestanding // [iterator.concept.sizedsentinel], concept sized_sentinel_for template<class S, class I> constexpr bool disable_sized_sentinel_for = false; // freestanding template<class S, class I> concept sized_sentinel_for = see below; // freestanding // [iterator.concept.input], concept input_iterator template<class I> concept input_iterator = see below; // freestanding // [iterator.concept.output], concept output_iterator template<class I, class T> concept output_iterator = see below; // freestanding // [iterator.concept.forward], concept forward_iterator template<class I> concept forward_iterator = see below; // freestanding // [iterator.concept.bidir], concept bidirectional_iterator template<class I> concept bidirectional_iterator = see below; // freestanding // [iterator.concept.random.access], concept random_access_iterator template<class I> concept random_access_iterator = see below; // freestanding // [iterator.concept.contiguous], concept contiguous_iterator template<class I> concept contiguous_iterator = see below; // freestanding // [indirectcallable], indirect callable requirements // [indirectcallable.indirectinvocable], indirect callables template<class F, class I> concept indirectly_unary_invocable = see below; // freestanding template<class F, class I> concept indirectly_regular_unary_invocable = see below; // freestanding template<class F, class I> concept indirect_unary_predicate = see below; // freestanding template<class F, class I1, class I2> concept indirect_binary_predicate = see below; // freestanding template<class F, class I1, class I2 = I1> concept indirect_equivalence_relation = see below; // freestanding template<class F, class I1, class I2 = I1> concept indirect_strict_weak_order = see below; // freestanding template<class F, class... Is> requires (indirectly_readable<Is> && ...) && invocable<F, iter_reference_t<Is>...> using indirect_result_t = invoke_result_t<F, iter_reference_t<Is>...>; // freestanding // [projected], projected template<indirectly_readable I, indirectly_regular_unary_invocable<I> Proj> struct projected; // freestanding template<weakly_incrementable I, class Proj> struct incrementable_traits<projected<I, Proj>>; // freestanding // [alg.req], common algorithm requirements // [alg.req.ind.move], concept indirectly_movable template<class In, class Out> concept indirectly_movable = see below; // freestanding template<class In, class Out> concept indirectly_movable_storable = see below; // freestanding // [alg.req.ind.copy], concept indirectly_copyable template<class In, class Out> concept indirectly_copyable = see below; // freestanding template<class In, class Out> concept indirectly_copyable_storable = see below; // freestanding // [alg.req.ind.swap], concept indirectly_swappable template<class I1, class I2 = I1> concept indirectly_swappable = see below; // freestanding // [alg.req.ind.cmp], concept indirectly_comparable template<class I1, class I2, class R, class P1 = identity, class P2 = identity> concept indirectly_comparable = see below; // freestanding // [alg.req.permutable], concept permutable template<class I> concept permutable = see below; // freestanding // [alg.req.mergeable], concept mergeable template<class I1, class I2, class Out, class R = ranges::less, class P1 = identity, class P2 = identity> concept mergeable = see below; // freestanding // [alg.req.sortable], concept sortable template<class I, class R = ranges::less, class P = identity> concept sortable = see below; // freestanding // [iterator.primitives], primitives // [std.iterator.tags], iterator tags struct input_iterator_tag { }; // freestanding struct output_iterator_tag { }; // freestanding struct forward_iterator_tag: public input_iterator_tag { }; // freestanding struct bidirectional_iterator_tag: public forward_iterator_tag { }; // freestanding struct random_access_iterator_tag: public bidirectional_iterator_tag { }; // freestanding struct contiguous_iterator_tag: public random_access_iterator_tag { }; // freestanding // [iterator.operations], iterator operations template<class InputIterator, class Distance> constexpr void advance(InputIterator& i, Distance n); // freestanding template<class InputIterator> constexpr typename iterator_traits<InputIterator>::difference_type distance(InputIterator first, InputIterator last); // freestanding template<class InputIterator> constexpr InputIterator next(InputIterator x, // freestanding typename iterator_traits<InputIterator>::difference_type n = 1); template<class BidirectionalIterator> constexpr BidirectionalIterator prev(BidirectionalIterator x, // freestanding typename iterator_traits<BidirectionalIterator>::difference_type n = 1); // [range.iter.ops], range iterator operations namespace ranges { // [range.iter.op.advance], ranges​::​advance template<input_or_output_iterator I> constexpr void advance(I& i, iter_difference_t<I> n); // freestanding template<input_or_output_iterator I, sentinel_for<I> S> constexpr void advance(I& i, S bound); // freestanding template<input_or_output_iterator I, sentinel_for<I> S> constexpr iter_difference_t<I> advance(I& i, iter_difference_t<I> n, // freestanding S bound); // [range.iter.op.distance], ranges​::​distance template<class I, sentinel_for<I> S> requires (!sized_sentinel_for<S, I>) constexpr iter_difference_t<I> distance(I first, S last); // freestanding template<class I, sized_sentinel_for<decay_t<I>> S> constexpr iter_difference_t<decay_t<I>> distance(I&& first, S last); // freestanding template<range R> constexpr range_difference_t<R> distance(R&& r); // freestanding // [range.iter.op.next], ranges​::​next template<input_or_output_iterator I> constexpr I next(I x); // freestanding template<input_or_output_iterator I> constexpr I next(I x, iter_difference_t<I> n); // freestanding template<input_or_output_iterator I, sentinel_for<I> S> constexpr I next(I x, S bound); // freestanding template<input_or_output_iterator I, sentinel_for<I> S> constexpr I next(I x, iter_difference_t<I> n, S bound); // freestanding // [range.iter.op.prev], ranges​::​prev template<bidirectional_iterator I> constexpr I prev(I x); // freestanding template<bidirectional_iterator I> constexpr I prev(I x, iter_difference_t<I> n); // freestanding template<bidirectional_iterator I> constexpr I prev(I x, iter_difference_t<I> n, I bound); // freestanding } // [predef.iterators], predefined iterators and sentinels // [reverse.iterators], reverse iterators template<class Iterator> class reverse_iterator; // freestanding template<class Iterator1, class Iterator2> constexpr bool operator==( // freestanding const reverse_iterator<Iterator1>& x, const reverse_iterator<Iterator2>& y); template<class Iterator1, class Iterator2> constexpr bool operator!=( // freestanding const reverse_iterator<Iterator1>& x, const reverse_iterator<Iterator2>& y); template<class Iterator1, class Iterator2> constexpr bool operator<( // freestanding const reverse_iterator<Iterator1>& x, const reverse_iterator<Iterator2>& y); template<class Iterator1, class Iterator2> constexpr bool operator>( // freestanding const reverse_iterator<Iterator1>& x, const reverse_iterator<Iterator2>& y); template<class Iterator1, class Iterator2> constexpr bool operator<=( // freestanding const reverse_iterator<Iterator1>& x, const reverse_iterator<Iterator2>& y); template<class Iterator1, class Iterator2> constexpr bool operator>=( // freestanding const reverse_iterator<Iterator1>& x, const reverse_iterator<Iterator2>& y); template<class Iterator1, three_way_comparable_with<Iterator1> Iterator2> constexpr compare_three_way_result_t<Iterator1, Iterator2> operator<=>(const reverse_iterator<Iterator1>& x, // freestanding const reverse_iterator<Iterator2>& y); template<class Iterator1, class Iterator2> constexpr auto operator-( // freestanding const reverse_iterator<Iterator1>& x, const reverse_iterator<Iterator2>& y) -> decltype(y.base() - x.base()); template<class Iterator> constexpr reverse_iterator<Iterator> operator+( // freestanding iter_difference_t<Iterator> n, const reverse_iterator<Iterator>& x); template<class Iterator> constexpr reverse_iterator<Iterator> make_reverse_iterator(Iterator i); // freestanding template<class Iterator1, class Iterator2> requires (!sized_sentinel_for<Iterator1, Iterator2>) constexpr bool disable_sized_sentinel_for<reverse_iterator<Iterator1>, // freestanding reverse_iterator<Iterator2>> = true; // [insert.iterators], insert iterators template<class Container> class back_insert_iterator; // freestanding template<class Container> constexpr back_insert_iterator<Container> back_inserter(Container& x); // freestanding template<class Container> class front_insert_iterator; // freestanding template<class Container> constexpr front_insert_iterator<Container> front_inserter(Container& x); // freestanding template<class Container> class insert_iterator; // freestanding template<class Container> constexpr insert_iterator<Container> inserter(Container& x, ranges::iterator_t<Container> i); // freestanding // [const.iterators], constant iterators and sentinels // [const.iterators.alias], alias templates template<indirectly_readable I> using iter_const_reference_t = see below; // freestanding template<class Iterator> concept constant-iterator = see below; // exposition only template<input_iterator I> using const_iterator = see below; // freestanding template<semiregular S> using const_sentinel = see below; // freestanding // [const.iterators.iterator], class template basic_const_iterator template<input_iterator Iterator> class basic_const_iterator; // freestanding template<class T, common_with<T> U> requires input_iterator<common_type_t<T, U>> struct common_type<basic_const_iterator<T>, U> { // freestanding using type = basic_const_iterator<common_type_t<T, U>>; }; template<class T, common_with<T> U> requires input_iterator<common_type_t<T, U>> struct common_type<U, basic_const_iterator<T>> { // freestanding using type = basic_const_iterator<common_type_t<T, U>>; }; template<class T, common_with<T> U> requires input_iterator<common_type_t<T, U>> struct common_type<basic_const_iterator<T>, basic_const_iterator<U>> { // freestanding using type = basic_const_iterator<common_type_t<T, U>>; }; template<input_iterator I> constexpr const_iterator<I> make_const_iterator(I it) { return it; } // freestanding template<semiregular S> constexpr const_sentinel<S> make_const_sentinel(S s) { return s; } // freestanding // [move.iterators], move iterators and sentinels template<class Iterator> class move_iterator; // freestanding template<class Iterator1, class Iterator2> constexpr bool operator==( // freestanding const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y); template<class Iterator1, class Iterator2> constexpr bool operator<( // freestanding const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y); template<class Iterator1, class Iterator2> constexpr bool operator>( // freestanding const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y); template<class Iterator1, class Iterator2> constexpr bool operator<=( // freestanding const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y); template<class Iterator1, class Iterator2> constexpr bool operator>=( // freestanding const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y); template<class Iterator1, three_way_comparable_with<Iterator1> Iterator2> constexpr compare_three_way_result_t<Iterator1, Iterator2> operator<=>(const move_iterator<Iterator1>& x, // freestanding const move_iterator<Iterator2>& y); template<class Iterator1, class Iterator2> constexpr auto operator-( // freestanding const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y) -> decltype(x.base() - y.base()); template<class Iterator> constexpr move_iterator<Iterator> operator+(iter_difference_t<Iterator> n, const move_iterator<Iterator>& x); // freestanding template<class Iterator> constexpr move_iterator<Iterator> make_move_iterator(Iterator i); // freestanding template<class Iterator1, class Iterator2> requires (!sized_sentinel_for<Iterator1, Iterator2>) constexpr bool disable_sized_sentinel_for<move_iterator<Iterator1>, // freestanding move_iterator<Iterator2>> = true; template<semiregular S> class move_sentinel; // freestanding // [iterators.common], common iterators template<input_or_output_iterator I, sentinel_for<I> S> requires (!same_as<I, S> && copyable<I>) class common_iterator; // freestanding template<class I, class S> struct incrementable_traits<common_iterator<I, S>>; // freestanding template<input_iterator I, class S> struct iterator_traits<common_iterator<I, S>>; // freestanding // [default.sentinel], default sentinel struct default_sentinel_t; // freestanding inline constexpr default_sentinel_t default_sentinel{}; // freestanding // [iterators.counted], counted iterators template<input_or_output_iterator I> class counted_iterator; // freestanding template<input_iterator I> requires see below struct iterator_traits<counted_iterator<I>>; // freestanding // [unreachable.sentinel], unreachable sentinel struct unreachable_sentinel_t; // freestanding inline constexpr unreachable_sentinel_t unreachable_sentinel{}; // freestanding // [stream.iterators], stream iterators 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 = 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 = char_traits<charT>> class ostreambuf_iterator; // [iterator.range], range access template<class C> constexpr auto begin(C& c) -> decltype(c.begin()); // freestanding template<class C> constexpr auto begin(const C& c) -> decltype(c.begin()); // freestanding template<class C> constexpr auto end(C& c) -> decltype(c.end()); // freestanding template<class C> constexpr auto end(const C& c) -> decltype(c.end()); // freestanding template<class T, size_t N> constexpr T* begin(T (&array)[N]) noexcept; // freestanding template<class T, size_t N> constexpr T* end(T (&array)[N]) noexcept; // freestanding template<class C> constexpr auto cbegin(const C& c) // freestanding noexcept(noexcept(std::begin(c))) -> decltype(std::begin(c)); template<class C> constexpr auto cend(const C& c) // freestanding noexcept(noexcept(std::end(c))) -> decltype(std::end(c)); template<class C> constexpr auto rbegin(C& c) -> decltype(c.rbegin()); // freestanding template<class C> constexpr auto rbegin(const C& c) -> decltype(c.rbegin()); // freestanding template<class C> constexpr auto rend(C& c) -> decltype(c.rend()); // freestanding template<class C> constexpr auto rend(const C& c) -> decltype(c.rend()); // freestanding template<class T, size_t N> constexpr reverse_iterator<T*> rbegin(T (&array)[N]) // freestanding template<class T, size_t N> constexpr reverse_iterator<T*> rend(T (&array)[N]); // freestanding template<class E> constexpr reverse_iterator<const E*> rbegin(initializer_list<E> il); // freestanding template<class E> constexpr reverse_iterator<const E*> rend(initializer_list<E> il); // freestanding template<class C> constexpr auto crbegin(const C& c) -> decltype(std::rbegin(c)); // freestanding template<class C> constexpr auto crend(const C& c) -> decltype(std::rend(c)); // freestanding template<class C> constexpr auto size(const C& c) -> decltype(c.size()); // freestanding template<class T, size_t N> constexpr size_t size(const T (&array)[N]) noexcept; // freestanding template<class C> constexpr auto ssize(const C& c) -> common_type_t<ptrdiff_t, make_signed_t<decltype(c.size())>>; // freestanding template<class T, ptrdiff_t N> constexpr ptrdiff_t ssize(const T (&array)[N]) noexcept; // freestanding template<class C> [[nodiscard]] constexpr auto empty(const C& c) -> decltype(c.empty()); // freestanding template<class T, size_t N> [[nodiscard]] constexpr bool empty(const T (&array)[N]) noexcept; // freestanding template<class E> [[nodiscard]] constexpr bool empty(initializer_list<E> il) noexcept; // freestanding template<class C> constexpr auto data(C& c) -> decltype(c.data()); // freestanding template<class C> constexpr auto data(const C& c) -> decltype(c.data()); // freestanding template<class T, size_t N> constexpr T* data(T (&array)[N]) noexcept; // freestanding template<class E> constexpr const E* data(initializer_list<E> il) noexcept; // freestanding }