ceph/src/boost/libs/iterator/doc/reverse_iterator_ref.rst

   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
  34 If ``Iterator`` models Random Access Traversal Iterator and Readable
  35 Lvalue Iterator, then ``iterator_category`` is convertible to
  36 ``random_access_iterator_tag``. Otherwise, if
  37 ``Iterator`` models Bidirectional Traversal Iterator and Readable
  38 Lvalue Iterator, then ``iterator_category`` is convertible to
  39 ``bidirectional_iterator_tag``. Otherwise, ``iterator_category`` is
  40 convertible to ``input_iterator_tag``.
  41
  42
  43
  44 ``reverse_iterator`` requirements
  45 .................................
  46
  47 ``Iterator`` must be a model of Bidirectional Traversal Iterator.  The
  48 type ``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
  56 A specialization of ``reverse_iterator`` models the same iterator
  57 traversal and iterator access concepts modeled by its ``Iterator``
  58 argument.  In addition, it may model old iterator concepts
  59 specified 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
  85 In addition to the operations required by the concepts modeled by
  86 ``reverse_iterator``, ``reverse_iterator`` provides the following
  87 operations.
  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``