factored iterator facade stuff into several files

[SVN r19464]

doc/iterator_facade_ref.rst

@@ -0,0 +1,284 @@
+.. parsed-literal::
+
+  template <
+      class Derived
+    , class Value
+    , class AccessCategory
+    , class TraversalCategory
+    , class Reference  = /* see below__ \*/
+    , class Difference = ptrdiff_t
+  >
+  class iterator_facade {
+  public:
+      typedef remove_cv<Value>::type value_type;
+      typedef Reference reference;
+      typedef /* see `description of operator->`__ \*/ pointer;
+      typedef Difference difference_type;
+      typedef iterator_tag<AccessCategory, TraversalCategory> iterator_category;
+
+      reference operator\*() const;
+      /* see below__ \*/ operator->() const;
+      /* see below__ \*/ operator[](difference_type n) const;
+      Derived& operator++();
+      Derived operator++(int);
+      Derived& operator--();
+      Derived operator--(int);
+      Derived& operator+=(difference_type n);
+      Derived& operator-=(difference_type n);
+      Derived operator-(difference_type n) const;
+  };
+
+  // Comparison operators
+  template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
+            class Dr2, class V2, class AC2, class TC2, class R2, class D2>
+  typename enable_if_interoperable<Dr1, Dr2, bool>::type // exposition
+  operator ==(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
+              iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
+
+  template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
+            class Dr2, class V2, class AC2, class TC2, class R2, class D2>
+  typename enable_if_interoperable<Dr1, Dr2, bool>::type
+  operator !=(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
+              iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
+
+  template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
+            class Dr2, class V2, class AC2, class TC2, class R2, class D2>
+  typename enable_if_interoperable<Dr1, Dr2, bool>::type
+  operator <(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
+             iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
+
+  template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
+            class Dr2, class V2, class AC2, class TC2, class R2, class D2>
+  typename enable_if_interoperable<Dr1, Dr2, bool>::type
+  operator <=(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
+              iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
+
+  template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
+            class Dr2, class V2, class AC2, class TC2, class R2, class D2>
+  typename enable_if_interoperable<Dr1, Dr2, bool>::type
+  operator >(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
+             iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
+
+  template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
+            class Dr2, class V2, class AC2, class TC2, class R2, class D2>
+  typename enable_if_interoperable<Dr1, Dr2, bool>::type
+  operator >=(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
+              iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
+
+  template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
+            class Dr2, class V2, class AC2, class TC2, class R2, class D2>
+  typename enable_if_interoperable<Dr1, Dr2, bool>::type
+  operator >=(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
+              iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
+
+  // Iterator difference
+  template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
+            class Dr2, class V2, class AC2, class TC2, class R2, class D2>
+  typename enable_if_interoperable<Dr1, Dr2, bool>::type
+  operator -(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
+             iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
+
+  // Iterator addition
+  template <class Derived, class V, class AC, class TC, class R, class D>
+  Derived operator+ (iterator_facade<Derived, V, AC, TC, R, D> const&,
+                     typename Derived::difference_type n)
+
+
+__ `iterator facade requirements`_
+
+__ `operator arrow`_
+
+__ `operator arrow`_
+
+__ brackets_
+
+[*Note:* The ``enable_if_interoperable`` template used above is for exposition
+purposes. The member operators should be only be in an overload set
+provided the derived types ``Dr1`` and ``Dr2`` are interoperable, by
+which we mean they are convertible to each other.  The
+``enable_if_interoperable`` approach uses SFINAE to take the operators
+out of the overload set when the types are not interoperable.]
+
+
+.. we need a new label here because the presence of markup in the
+   title prevents an automatic link from being generated
+
+.. _iterator facade requirements:
+
+``iterator_facade`` requirements
+================================
+
+The ``Derived`` template parameter must be a class derived from
+``iterator_facade``.
+
+The default for the ``Reference`` parameter is ``Value&`` if the
+access category for ``iterator_facade`` is implicitly convertible to
+``writable_iterator_tag``, and ``const Value&`` otherwise.
+
+The following table describes the other requirements on the
+``Derived`` parameter.  Depending on the resulting iterator's
+``iterator_category``, a subset of the expressions listed in the table
+are required to be valid.  The operations in the first column must be
+accessible to member functions of class ``iterator_core_access``.
+
+In the table below, ``X`` is the derived iterator type, ``a`` is an
+object of type ``X``, ``b`` and ``c`` are objects of type ``const X``,
+``n`` is an object of ``X::difference_type``, ``y`` is a constant
+object of a single pass iterator type interoperable with X, and ``z``
+is a constant object of a random access traversal iterator type
+interoperable with ``X``.
+
++--------------------+-------------------+-------------------------------------+---------------------------+
+|Expression          |Return Type        |Assertion/Note                       |Required to implement      |
+|                    |                   |                                     |Iterator Concept(s)        |
++====================+===================+=====================================+===========================+
+|``c.dereference()`` |``X::reference``   |                                     |Readable Iterator, Writable|
+|                    |                   |                                     |Iterator                   |
++--------------------+-------------------+-------------------------------------+---------------------------+
+|``c.equal(b)``      |convertible to bool|true iff ``b`` and ``c`` are         |Single Pass Iterator       |
+|                    |                   |equivalent.                          |                           |
++--------------------+-------------------+-------------------------------------+---------------------------+
+|``c.equal(y)``      |convertible to bool|true iff ``c`` and ``y`` refer to the|Single Pass Iterator       |
+|                    |                   |same position.  Implements ``c == y``|                           |
+|                    |                   |and ``c != y``.                      |                           |
++--------------------+-------------------+-------------------------------------+---------------------------+
+|``a.advance(n)``    |unused             |                                     |Random Access Traversal    |
+|                    |                   |                                     |Iterator                   |
++--------------------+-------------------+-------------------------------------+---------------------------+
+|``a.increment()``   |unused             |                                     |Incrementable Iterator     |
++--------------------+-------------------+-------------------------------------+---------------------------+
+|``a.decrement()``   |unused             |                                     |Bidirectional Traversal    |
+|                    |                   |                                     |Iterator                   |
++--------------------+-------------------+-------------------------------------+---------------------------+
+|``c.distance_to(b)``|convertible to     |equivalent to ``distance(c, b)``     |Random Access Traversal    |
+|                    |X::difference_type |                                     |Iterator                   |
++--------------------+-------------------+-------------------------------------+---------------------------+
+|``c.distance_to(z)``|convertible to     |equivalent to ``distance(c, z)``.    |Random Access Traversal    |
+|                    |X::difference_type |Implements ``c - z``, ``c < z``, ``c |Iterator                   |
+|                    |                   |<= z``, ``c > z``, and ``c >= c``.   |                           |
++--------------------+-------------------+-------------------------------------+---------------------------+
+
+.. We should explain more about how the
+   functions in the interface of iterator_facade
+   are there conditionally. -JGS
+
+
+``iterator_facade`` operations
+==============================
+
+The operations in this section are described in terms of operations on
+the core interface of ``Derived`` which may be inaccessible
+(i.e. private).  The implementation should access these operations
+through member functions of class ``iterator_core_access``.
+
+``reference operator*() const;``
+
+:Returns: ``static_cast<Derived const*>(this)->dereference()``
+
+``operator->() const;`` (see below__)
+
+__ `operator arrow`_
+
+:Returns: If ``X::reference`` is a reference type, returns an object
+  of type ``X::pointer`` equal to::
+
+    &static_cast<Derived const*>(this)->dereference()
+
+  Otherwise returns an object of unspecified type such that, given an
+  object ``a`` of type ``X``, ``a->m`` is equivalent to ``(w = *a,
+  w.m)`` for some temporary object ``w`` of type ``X::value_type``.
+
+  The type ``X::pointer`` is ``Value*`` if the access category for
+  ``X`` is implicitly convertible to ``writable_iterator_tag``, and
+  ``Value const*`` otherwise.
+
+
+.. _brackets:
+
+*unspecified* ``operator[](difference_type n) const;``
+
+:Returns: an object convertible to ``X::reference`` and holding a copy
+     *p* of ``a+n`` such that, for a constant object ``v`` of type
+     ``X::value_type``, ``X::reference(a[n] = v)`` is equivalent
+     to ``p = v``.
+
+
+
+``Derived& operator++();``
+
+:Effects: 
+
+  ::
+
+    static_cast<Derived*>(this)->increment();
+    return *this;
+
+.. I realize that the committee is moving away from specifying things
+   like this in terms of code, but I worried about the imprecision of
+   saying that a core interface function is invoked without describing
+   the downcast.  An alternative to what I did would be to mention it
+   above where we talk about accessibility.
+
+
+``Derived operator++(int);``
+
+:Effects:
+
+  ::
+
+    Derived tmp(static_cast<Derived const*>(this));
+    ++*this;
+    return tmp;
+
+
+``Derived& operator--();``
+
+:Effects:
+
+   ::
+
+      static_cast<Derived*>(this)->decrement();
+      return *this;
+
+
+``Derived operator--(int);``
+
+:Effects:
+
+  ::
+
+    Derived tmp(static_cast<Derived const*>(this));
+    --*this;
+    return tmp;
+
+
+``Derived& operator+=(difference_type n);``
+
+:Effects:
+
+  ::
+
+      static_cast<Derived*>(this)->advance(n);
+      return *this;
+
+
+``Derived& operator-=(difference_type n);``
+
+:Effects:
+
+   ::
+
+      static_cast<Derived*>(this)->advance(-n);
+      return *this;
+
+
+``Derived operator-(difference_type n) const;``
+
+:Effects: 
+
+   Derived tmp(static_cast<Derived const*>(this));
+   return tmp -= n;
+
+:Returns: ``static_cast<Derived const*>(this)->advance(-n);``
+
+