-
-
..include:: iterator_facade_ref.rst
+
+
+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)
+
+
[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.]
+
+
+
+
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
+equivalent. |
+Single Pass Iterator |
+
+| c.equal(y) |
+convertible to bool |
+true iff c and y refer to the
+same position. Implements c == y
+and c != y. |
+Single Pass Iterator |
+
+| 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
+X::difference_type |
+equivalent to distance(c, b) |
+Random Access Traversal
+Iterator |
+
+| c.distance_to(z) |
+convertible to
+X::difference_type |
+equivalent to distance(c, z).
+Implements c - z, c < z, c
+<= z, c > z, and c >= c. |
+Random Access Traversal
+Iterator |
+
+
+
+
+
+
+
+
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)
+
+
+
+
+| 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.
+ |
+
|---|
+
+
+
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;
+
+ |
+
|---|
+
+
+
+
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); |
+
|---|
+
+
+