1.. Copyright David Abrahams 2006. Distributed under the Boost
2.. Software License, Version 1.0. (See accompanying
3.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
4
5::
6
7  template <class Iterator>
8  class reverse_iterator
9  {
10  public:
11    typedef iterator_traits<Iterator>::value_type value_type;
12    typedef iterator_traits<Iterator>::reference reference;
13    typedef iterator_traits<Iterator>::pointer pointer;
14    typedef iterator_traits<Iterator>::difference_type difference_type;
15    typedef /* see below */ iterator_category;
16
17    reverse_iterator() {}
18    explicit reverse_iterator(Iterator x) ;
19
20    template<class OtherIterator>
21    reverse_iterator(
22        reverse_iterator<OtherIterator> const& r
23      , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
24    );
25    Iterator const& base() const;
26    reference operator*() const;
27    reverse_iterator& operator++();
28    reverse_iterator& operator--();
29  private:
30    Iterator m_iterator; // exposition
31  };
32
33
34If ``Iterator`` models Random Access Traversal Iterator and Readable
35Lvalue Iterator, then ``iterator_category`` is convertible to
36``random_access_iterator_tag``. Otherwise, if
37``Iterator`` models Bidirectional Traversal Iterator and Readable
38Lvalue Iterator, then ``iterator_category`` is convertible to
39``bidirectional_iterator_tag``. Otherwise, ``iterator_category`` is
40convertible to ``input_iterator_tag``.
41
42
43
44``reverse_iterator`` requirements
45.................................
46
47``Iterator`` must be a model of Bidirectional Traversal Iterator.  The
48type ``iterator_traits<Iterator>::reference`` must be the type of
49``*i``, where ``i`` is an object of type ``Iterator``.
50
51
52
53``reverse_iterator`` models
54...........................
55
56A specialization of ``reverse_iterator`` models the same iterator
57traversal and iterator access concepts modeled by its ``Iterator``
58argument.  In addition, it may model old iterator concepts
59specified in the following table:
60
61+---------------------------------------+-----------------------------------+
62| If ``I`` models                       |then ``reverse_iterator<I>`` models|
63+=======================================+===================================+
64| Readable Lvalue Iterator,             | Bidirectional Iterator            |
65| Bidirectional Traversal Iterator      |                                   |
66+---------------------------------------+-----------------------------------+
67| Writable Lvalue Iterator,             | Mutable Bidirectional Iterator    |
68| Bidirectional Traversal Iterator      |                                   |
69+---------------------------------------+-----------------------------------+
70| Readable Lvalue Iterator,             | Random Access Iterator            |
71| Random Access Traversal Iterator      |                                   |
72+---------------------------------------+-----------------------------------+
73| Writable Lvalue Iterator,             | Mutable Random Access Iterator    |
74| Random Access Traversal Iterator      |                                   |
75+---------------------------------------+-----------------------------------+
76
77
78``reverse_iterator<X>`` is interoperable with
79``reverse_iterator<Y>`` if and only if ``X`` is interoperable with
80``Y``.
81
82``reverse_iterator`` operations
83...............................
84
85In addition to the operations required by the concepts modeled by
86``reverse_iterator``, ``reverse_iterator`` provides the following
87operations.
88
89
90
91``reverse_iterator();``
92
93:Requires: ``Iterator`` must be Default Constructible.
94:Effects: Constructs an instance of ``reverse_iterator`` with ``m_iterator``
95  default constructed.
96
97``explicit reverse_iterator(Iterator x);``
98
99:Effects: Constructs an instance of ``reverse_iterator`` with
100    ``m_iterator`` copy constructed from ``x``.
101
102
103::
104
105    template<class OtherIterator>
106    reverse_iterator(
107        reverse_iterator<OtherIterator> const& r
108      , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
109    );
110
111:Requires: ``OtherIterator`` is implicitly convertible to ``Iterator``.
112:Effects: Constructs instance of ``reverse_iterator`` whose
113    ``m_iterator`` subobject is constructed from ``y.base()``.
114
115
116
117``Iterator const& base() const;``
118
119:Returns: ``m_iterator``
120
121
122``reference operator*() const;``
123
124:Effects:
125
126::
127
128    Iterator tmp = m_iterator;
129    return *--tmp;
130
131
132``reverse_iterator& operator++();``
133
134:Effects: ``--m_iterator``
135:Returns: ``*this``
136
137
138``reverse_iterator& operator--();``
139
140:Effects: ``++m_iterator``
141:Returns: ``*this``
142