stl_iterator.h

Introduction

This is an internal header file, included by other library headers. You should not attempt to use it directly.

This file implements reverse_iterator, back_insert_iterator, front_insert_iterator, insert_iterator, __normal_iterator, and their supporting functions and overloaded operators.

Classes

back_insert_iterator

front_insert_iterator

insert_iterator

Functions

back_inserter

front_inserter

inserter

operator ==

operator reverse_iterator

template<typename _Container> inline back_insert_iterator<_Container> back_inserter(
    _Container& __x) 

Parameters

x

A container of arbitrary type.

Return Value

An instance of back_insert_iterator working on @p x.

This wrapper function helps in creating back_insert_iterator instances. Typing the name of the %iterator requires knowing the precise full type of the container, which can be tedious and impedes generic programming. Using this function lets you take advantage of automatic template parameter deduction, making the compiler match the correct types for you.

template<typename _Container> inline front_insert_iterator<_Container> front_inserter(
    _Container& __x) 

Parameters

x

A container of arbitrary type.

Return Value

An instance of front_insert_iterator working on @p x.

This wrapper function helps in creating front_insert_iterator instances. Typing the name of the %iterator requires knowing the precise full type of the container, which can be tedious and impedes generic programming. Using this function lets you take advantage of automatic template parameter deduction, making the compiler match the correct types for you.

template<typename _Container, typename _Iterator> inline insert_iterator<_Container> inserter(
    _Container& __x,
    _Iterator __i) 

Parameters

x

A container of arbitrary type.

Return Value

An instance of insert_iterator working on @p x.

This wrapper function helps in creating insert_iterator instances. Typing the name of the %iterator requires knowing the precise full type of the container, which can be tedious and impedes generic programming. Using this function lets you take advantage of automatic template parameter deduction, making the compiler match the correct types for you.

template<typename _Iterator> inline bool operator==(
    const reverse_iterator<_Iterator>& __x, 
    const reverse_iterator<_Iterator>& __y) 

Parameters

x

A %reverse_iterator.

y

A %reverse_iterator.

Return Value

A simple bool.

Reverse iterators forward many operations to their underlying base() iterators. Others are implemented in terms of one another.

template<typename _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> { 
        protected: _Iterator current;  
    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;   
public: /**
The default constructor default-initializes member @p current.
If it is a pointer, that means it is zero-initialized.
    */
// _GLIBCXX_RESOLVE_LIB_DEFECTS 
// 235 No specification of default ctor for reverse_iterator 
reverse_iterator() : current() ;  /**
This %iterator will move in the opposite direction that @p x does.
    */
explicit reverse_iterator(
    iterator_type __x) : current(
    __x) ;  /**
The copy constructor is normal.
    */
reverse_iterator(
    const reverse_iterator& __x) : current(
    __x.current) ;  /**
A reverse_iterator across other types can be copied in the normal
fashion.
    */
template<typename _Iter> reverse_iterator(
    const reverse_iterator<_Iter>& __x) : current(
    __x.base()) ;  /**
@return @c current, the %iterator used for underlying work.
    */
iterator_type base() const   /**
@return TODO

@doctodo
    */
reference operator*() const   /**
@return TODO

@doctodo
    */
pointer operator->() const return &(
    operator*());  
}  /**
@return TODO

@doctodo
    */
reverse_iterator& operator++() ;

Discussion

"Bidirectional and random access iterators have corresponding reverse %iterator adaptors that iterate through the data structure in the opposite direction. They have the same signatures as the corresponding iterators. The fundamental relation between a reverse %iterator and its corresponding %iterator @c i is established by the identity: @code &*(reverse_iterator(i)) == &*(i - 1) @endcode

This mapping is dictated by the fact that while there is always a pointer past the end of an array, there might not be a valid pointer before the beginning of an array." [24.4.1]/1,2

Reverse iterators can be tricky and surprising at first. Their semantics make sense, however, and the trickiness is a side effect of the requirement that the iterators must be safe.