Standard library header <iterator>

 

C++

Language

Standard library headers

Concepts

Utilities library

Strings library

Containers library

Algorithms library

Iterators 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 header files

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

 

This header is part of the iterator library.

Classes

Primitives
iterator_traits	provides uniform interface to the properties of an iterator (class template)
input_iterator_tagoutput_iterator_tagforward_iterator_tagbidirectional_iterator_tagrandom_access_iterator_tag	empty class types used to indicate iterator categories (class)
iterator (deprecated in C++17)	base class to ease the definition of required types for simple iterators (class template)
Adaptors
reverse_iterator	iterator adaptor for reverse-order traversal (class template)
move_iterator (C++11)	iterator adaptor which dereferences to an rvalue reference (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)
Stream Iterators
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)

Functions

Adaptors
make_reverse_iterator (C++14)	creates a std::reverse_iterator of type inferred from the argument (function template)
make_move_iterator (C++11)	creates a std::move_iterator of type inferred from the argument (function template)
front_inserter	creates a std::front_insert_iterator of type inferred from the argument (function template)
back_inserter	creates a std::back_insert_iterator of type inferred from the argument (function template)
inserter	creates a std::insert_iterator of type inferred from the argument (function template)
Operations
advance	advances an iterator by given distance (function)
distance	returns the distance between two iterators (function)
next (C++11)	increment an iterator (function)
prev (C++11)	decrement an iterator (function)
Range
begincbegin (C++11)(C++14)	returns an iterator to the beginning of a container or array (function)
endcend (C++11)(C++14)	returns an iterator to the end of a container or array (function)
rbegincrbegin (C++14)	returns a reverse iterator to a container or array (function)
rendcrend (C++14)	returns a reverse end iterator for a container or array (function)
Non-member operators
operator==operator!=operator<operator<=operator>operator>=	compares the underlying iterators (function template)
operator+	advances the iterator (function template)
operator-	computes the distance between two iterator adaptors (function template)
operator==operator!=operator<operator<=operator>operator>=	compares the underlying iterators (function template)
operator+	advances the iterator (function template)
operator-	computes the distance between two iterator adaptors (function template)
operator==operator!=	compares two istream_iterators (function template)
operator==operator!=	compares two istreambuf_iterators (function template)

Synopsis

namespace std {
    // primitives:
    template<class Iterator> struct iterator_traits;
    template<class T> struct iterator_traits<T*>;
    template<class Category, class T, class Distance = ptrdiff_t,
    class Pointer = T*, class Reference = T&> struct iterator;
 
    struct input_iterator_tag { };
    struct output_iterator_tag { };
    struct forward_iterator_tag: public input_iterator_tag { };
    struct bidirectional_iterator_tag: public forward_iterator_tag { };
    struct random_access_iterator_tag: public bidirectional_iterator_tag { };
 
    // iterator operations:
    template <class InputIterator, class Distance>
        void advance(InputIterator& i, Distance n);
    template <class InputIterator>
        typename iterator_traits<InputIterator>::difference_type
        distance(InputIterator first, InputIterator last);
    template <class ForwardIterator>
        ForwardIterator next(ForwardIterator x,
            typename std::iterator_traits<ForwardIterator>::difference_type n = 1);
    template <class BidirectionalIterator>
        BidirectionalIterator prev(BidirectionalIterator x,
            typename std::iterator_traits<BidirectionalIterator>::difference_type n = 1);
 
    // predefined iterators:
    template <class Iterator> class reverse_iterator;
    template <class Iterator1, class Iterator2>
        bool operator==(
            const reverse_iterator<Iterator1>& x,
            const reverse_iterator<Iterator2>& y);
    template <class Iterator1, class Iterator2>
        bool operator<(
            const reverse_iterator<Iterator1>& x,
            const reverse_iterator<Iterator2>& y);
    template <class Iterator1, class Iterator2>
        bool operator!=(
            const reverse_iterator<Iterator1>& x,
            const reverse_iterator<Iterator2>& y);
    template <class Iterator1, class Iterator2>
        bool operator>(
            const reverse_iterator<Iterator1>& x,
            const reverse_iterator<Iterator2>& y);
    template <class Iterator1, class Iterator2>
        bool operator>=(
            const reverse_iterator<Iterator1>& x,
            const reverse_iterator<Iterator2>& y);
    template <class Iterator1, class Iterator2>
        bool operator<=(
            const reverse_iterator<Iterator1>& x,
            const reverse_iterator<Iterator2>& y);
 
    template <class Iterator1, class Iterator2>
        auto operator-(
            const reverse_iterator<Iterator1>& x,
            const reverse_iterator<Iterator2>& y) ->decltype(y.base() - x.base());
    template <class Iterator>
        reverse_iterator<Iterator>
        operator+(
            typename reverse_iterator<Iterator>::difference_type n,
            const reverse_iterator<Iterator>& x);
    template <class Iterator>
        reverse_iterator<Iterator> make_reverse_iterator(Iterator 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, typename Container::iterator i);
 
    template <class Iterator> class move_iterator;
    template <class Iterator1, class Iterator2>
        bool operator==(
            const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
    template <class Iterator1, class Iterator2>
        bool operator!=(
            const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
    template <class Iterator1, class Iterator2>
        bool operator<(
            const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
    template <class Iterator1, class Iterator2>
        bool operator<=(
            const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
    template <class Iterator1, class Iterator2>
        bool operator>(
            const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
    template <class Iterator1, class Iterator2>
        bool operator>=(
            const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
 
    template <class Iterator1, class Iterator2>
        auto operator-(
            const move_iterator<Iterator1>& x,
            const move_iterator<Iterator2>& y) -> decltype(x.base() - y.base());
    template <class Iterator>
        move_iterator<Iterator> operator+(
            typename move_iterator<Iterator>::difference_type n, 
            const move_iterator<Iterator>& x);
    template <class Iterator>
        move_iterator<Iterator> make_move_iterator(Iterator i);
 
    // 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, 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>
        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;
 
    // range access:
    template <class C> auto begin(C& c) -> decltype(c.begin());
    template <class C> auto begin(const C& c) -> decltype(c.begin());
    template <class C> auto end(C& c) -> decltype(c.end());
    template <class C> auto end(const C& c) -> decltype(c.end());
    template <class T, size_t N> T* begin(T (&array)[N]);
    template <class T, size_t N> T* end(T (&array)[N]);
}

Class std::iterator_traits

template<class Iterator> struct iterator_traits {
    typedef typename Iterator::difference_type      difference_type;
    typedef typename Iterator::value_type           value_type;
    typedef typename Iterator::pointer              pointer;
    typedef typename Iterator::reference            reference;
    typedef typename Iterator::iterator_category    iterator_category;
};
 
template<class T> struct iterator_traits<T*> {
    typedef ptrdiff_t                   difference_type;
    typedef T                           value_type;
    typedef T*                          pointer;
    typedef T&                          reference;
    typedef random_access_iterator_tag  iterator_category;
};
 
template<class T> struct iterator_traits<const T*> {
    typedef ptrdiff_t                   difference_type;
    typedef T                           value_type;
    typedef const T*                    pointer;
    typedef const T&                    reference;
    typedef random_access_iterator_tag  iterator_category;
};

Class std::iterator

template<class Category, class T, class Distance = ptrdiff_t,
         class Pointer = T*, class Reference = T&>
struct iterator {
    typedef T           value_type;
    typedef Distance    difference_type;
    typedef Pointer     pointer;
    typedef Reference   reference;
    typedef Category    iterator_category;
};

Iterator tags

struct input_iterator_tag { };
struct output_iterator_tag { };
struct forward_iterator_tag: public input_iterator_tag { };
struct bidirectional_iterator_tag: public forward_iterator_tag { };
struct random_access_iterator_tag: public bidirectional_iterator_tag { };

Class std::reverse_iterator

template <class Iterator>
class reverse_iterator : public
    iterator<typename iterator_traits<Iterator>::iterator_category,
    typename iterator_traits<Iterator>::value_type,
    typename iterator_traits<Iterator>::difference_type,
    typename iterator_traits<Iterator>::pointer,
    typename iterator_traits<Iterator>::reference> {
public:
    typedef Iterator                                            iterator_type;
    typedef typename iterator_traits<Iterator>::difference_type difference_type;
    typedef typename iterator_traits<Iterator>::reference       reference;
    typedef typename iterator_traits<Iterator>::pointer         pointer;
 
    reverse_iterator();
    explicit reverse_iterator(Iterator x);
    template <class U> reverse_iterator(const reverse_iterator<U>& u);
    template <class U> reverse_iterator& operator=(const reverse_iterator<U>& u);
 
    Iterator base() const; // explicit
    reference operator*() const;
    pointer operator->() const;
 
    reverse_iterator& operator++();
    reverse_iterator  operator++(int);
    reverse_iterator& operator--();
    reverse_iterator  operator--(int);
 
    reverse_iterator  operator+ (difference_type n) const;
    reverse_iterator& operator+=(difference_type n);
    reverse_iterator  operator- (difference_type n) const;
    reverse_iterator& operator-=(difference_type n);
 
    /*unspecified*/ operator[](difference_type n) const;
protected:
    Iterator current;
private:
    Iterator deref_tmp; // exposition only
};

Class std::back_insert_iterator

template <class Container>
class back_insert_iterator :
    public iterator<output_iterator_tag,void,void,void,void> {
protected:
    Container* container;
public:
    typedef Container container_type;
 
    explicit back_insert_iterator(Container& x);
    back_insert_iterator<Container>&
        operator=(const typename Container::value_type& value);
    back_insert_iterator<Container>&
        operator=(typename Container::value_type&& value);
 
    back_insert_iterator<Container>& operator*();
    back_insert_iterator<Container>& operator++();
    back_insert_iterator<Container>  operator++(int);
};

Class std::front_insert_iterator

template <class Container>
class front_insert_iterator :
    public iterator<output_iterator_tag,void,void,void,void> {
protected:
    Container* container;
public:
    typedef Container container_type;
 
    explicit front_insert_iterator(Container& x);
    front_insert_iterator<Container>&
    operator=(const typename Container::value_type& value);
    front_insert_iterator<Container>&
    operator=(typename Container::value_type&& value);
 
    front_insert_iterator<Container>& operator*();
    front_insert_iterator<Container>& operator++();
    front_insert_iterator<Container>  operator++(int);
};

Class std::insert_iterator

template <class Container>
class insert_iterator :
    public iterator<output_iterator_tag,void,void,void,void> {
protected:
    Container*                   container;
    typename Container::iterator iter;
public:
    typedef Container container_type;
 
    insert_iterator(Container& x, typename Container::iterator i);
    insert_iterator<Container>&
    operator=(const typename Container::value_type& value);
    insert_iterator<Container>&
    operator=(typename Container::value_type&& value);
 
    insert_iterator<Container>& operator*();
    insert_iterator<Container>& operator++();
    insert_iterator<Container>& operator++(int);
};

Class std::move_iterator

template <class Iterator>
class move_iterator {
public:
    typedef Iterator                                            iterator_type;
    typedef typename iterator_traits<Iterator>::difference_type difference_type;
    typedef Iterator                                            pointer;
    typedef typename iterator_traits<Iterator>::value_type      value_type;
    typedef typename iterator_traits<Iterator>::iterator_category
                                                                iterator_category;
    typedef value_type&&                                        reference;
 
    move_iterator();
    explicit move_iterator(Iterator i);
    template <class U> move_iterator(const move_iterator<U>& u);
    template <class U> move_iterator& operator=(const move_iterator<U>& u);
 
    iterator_type base() const;
    reference operator*() const;
    pointer operator->() const;
 
    move_iterator& operator++();
    move_iterator  operator++(int);
    move_iterator& operator--();
    move_iterator  operator--(int);
 
    move_iterator   operator+(difference_type n) const;
    move_iterator&  operator+=(difference_type n);
    move_iterator   operator-(difference_type n) const;
    move_iterator&  operator-=(difference_type n);
    /*unspecified*/ operator[](difference_type n) const;
 
private:
    Iterator current; // exposition only
};