W3cubDocs

/C++

Standard library header <iterator>

This header is part of the iterator library.

Classes

Primitives
provides uniform interface to the properties of an iterator
(class template)
empty class types used to indicate iterator categories
(class)
(deprecated in C++17)
 base class to ease the definition of required types for simple iterators
(class template)
Adaptors
iterator adaptor for reverse-order traversal
(class template)
(C++11)
 iterator adaptor which dereferences to an rvalue reference
(class template)
iterator adaptor for insertion at the end of a container
(class template)
iterator adaptor for insertion at the front of a container
(class template)
iterator adaptor for insertion into a container
(class template)
Stream Iterators
input iterator that reads from std::basic_istream
(class template)
output iterator that writes to std::basic_ostream
(class template)
input iterator that reads from std::basic_streambuf
(class template)
output iterator that writes to std::basic_streambuf
(class template)

Functions

Adaptors
(C++14)
 creates a std::reverse_iterator of type inferred from the argument
(function template)
(C++11)
 creates a std::move_iterator of type inferred from the argument
(function template)
creates a std::front_insert_iterator of type inferred from the argument
(function template)
creates a std::back_insert_iterator of type inferred from the argument
(function template)
creates a std::insert_iterator of type inferred from the argument
(function template)
Operations
advances an iterator by given distance
(function)
returns the distance between two iterators
(function)
(C++11)
 increment an iterator
(function)
(C++11)
 decrement an iterator
(function)
Range
(C++11)(C++14)
 returns an iterator to the beginning of a container or array
(function)
(C++11)(C++14)
 returns an iterator to the end of a container or array
(function)
(C++14)
 returns a reverse iterator to a container or array
(function)
(C++14)
 returns a reverse end iterator for a container or array
(function)
Non-member operators
compares the underlying iterators
(function template)
advances the iterator
(function template)
computes the distance between two iterator adaptors
(function template)
compares the underlying iterators
(function template)
advances the iterator
(function template)
computes the distance between two iterator adaptors
(function template)
compares two istream_iterators
(function template)
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
};

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
http://en.cppreference.com/w/cpp/header/iterator