iterator/doc/quickbook/utilities.qbk

[section:utilities Iterator Utilities]

[section:utilities_traits Traits]

[h2 Overview]

Have you ever wanted to write a generic function that can operate
on any kind of dereferenceable object?  If you have, you've
probably run into the problem of how to determine the type that the
object "points at":

   template <class Dereferenceable>
   void f(Dereferenceable p)
   {
       *what-goes-here?* value = \*p;
       ...
   }


[h2 `pointee`]

It turns out to be impossible to come up with a fully-general
algorithm to do determine *what-goes-here* directly, but it is
possible to require that `pointee<Dereferenceable>::type` is
correct. Naturally, `pointee` has the same difficulty: it can't
determine the appropriate `::type` reliably for all
`Dereferenceable`\ s, but it makes very good guesses (it works
for all pointers, standard and boost smart pointers, and
iterators), and when it guesses wrongly, it can be specialized as
necessary:

  namespace boost
  {
    template <class T>
    struct pointee<third_party_lib::smart_pointer<T> >
    {
        typedef T type;
    };
  }

[h2 `indirect_reference`]

`indirect_reference<T>::type` is rather more specialized than
`pointee`, and is meant to be used to forward the result of
dereferencing an object of its argument type.  Most dereferenceable
types just return a reference to their pointee, but some return
proxy references or return the pointee by value.  When that
information is needed, call on `indirect_reference`.

Both of these templates are essential to the correct functioning of
[link indirecct `indirect_iterator`].

[h2 Reference]

[h3 `pointeee`]

  template <class Dereferenceable>
  struct pointee
  {
      typedef /* see below */ type;
  };

[*Requires:] For an object `x` of type `Dereferenceable`, `*x`
  is well-formed.  If `++x` is ill-formed it shall neither be
  ambiguous nor shall it violate access control, and
  `Dereferenceable::element_type` shall be an accessible type.
  Otherwise `iterator_traits<Dereferenceable>::value_type` shall
  be well formed. \[Note: These requirements need not apply to
  explicit or partial specializations of `pointee`\]

`type` is determined according to the following algorithm, where
`x` is an object of type `Dereferenceable`:

  if ( ++x is ill-formed )
  {
      return `Dereferenceable::element_type`
  }
  else if (`*x` is a mutable reference to
           std::iterator_traits<Dereferenceable>::value_type)
  {
      return iterator_traits<Dereferenceable>::value_type
  }
  else
  {
      return iterator_traits<Dereferenceable>::value_type const
  }

[h3 `indirect_reference`]

  template <class Dereferenceable>
  struct indirect_reference
  {
      typedef /* see below */ type;
  };

[*Requires:] For an object `x` of type `Dereferenceable`, `*x`
  is well-formed.  If `++x` is ill-formed it shall neither be
  ambiguous nor shall it violate access control, and
  `pointee<Dereferenceable>::type&` shall be well-formed.
  Otherwise `iterator_traits<Dereferenceable>::reference` shall
  be well formed.  \[Note: These requirements need not apply to
  explicit or partial specializations of `indirect_reference`\]

`type` is determined according to the following algorithm, where
`x` is an object of type `Dereferenceable`:

  if ( ++x is ill-formed )
      return `pointee<Dereferenceable>::type&`
  else
      std::iterator_traits<Dereferenceable>::reference


[endsect]

[section:utilities_testing Testing and Concept Checking]

The iterator concept checking classes provide a mechanism for a
template to report better error messages when a user instantiates
the template with a type that does not meet the requirements of the
template.

For an introduction to using concept checking classes, see
the documentation for the 
[@../../concept_check/index.html `boost::concept_check`] library.


[h2 Reference]

[h3 Iterator Access Concepts]

* |Readable|_ 
* |Writable|_ 
* |Swappable|_ 
* |Lvalue|_ 

[/ .. |Readable| replace:: *Readable Iterator* ]
[/ .. _Readable: ReadableIterator.html            ]
[/                                                ]
[/ .. |Writable| replace:: *Writable Iterator*    ]
[/ .. _Writable: WritableIterator.html            ]
[/                                                ]
[/ .. |Swappable| replace:: *Swappable Iterator*  ]
[/ .. _Swappable: SwappableIterator.html          ]
[/                                                ]
[/ .. |Lvalue| replace:: *Lvalue Iterator*        ]
[/ .. _Lvalue: LvalueIterator.html                ]


Iterator Traversal Concepts
...........................

* |Incrementable|_
* |SinglePass|_
* |Forward|_
* |Bidir|_
* |Random|_


[/ .. |Incrementable| replace:: *Incrementable Iterator* ]
[/ .. _Incrementable: IncrementableIterator.html         ]
[/                                                       ]
[/ .. |SinglePass| replace:: *Single Pass Iterator*      ]
[/ .. _SinglePass: SinglePassIterator.html               ]
[/                                                       ]
[/ .. |Forward| replace:: *Forward Traversal*            ]
[/ .. _Forward: ForwardTraversal.html                    ]
[/                                                       ]
[/ .. |Bidir| replace:: *Bidirectional Traversal*        ]
[/ .. _Bidir: BidirectionalTraversal.html                ]
[/                                                       ]
[/ .. |Random| replace:: *Random Access Traversal*       ]
[/ .. _Random: RandomAccessTraversal.html                ]



[h3 `iterator_concepts.hpp` Synopsis]

    namespace boost_concepts {

        // Iterator Access Concepts

        template <typename Iterator>
        class ReadableIteratorConcept;

        template <
            typename Iterator
          , typename ValueType = std::iterator_traits<Iterator>::value_type
        >
        class WritableIteratorConcept;

        template <typename Iterator>
        class SwappableIteratorConcept;

        template <typename Iterator>
        class LvalueIteratorConcept;

        // Iterator Traversal Concepts

        template <typename Iterator>
        class IncrementableIteratorConcept;

        template <typename Iterator>
        class SinglePassIteratorConcept;

        template <typename Iterator>
        class ForwardTraversalConcept;

        template <typename Iterator>
        class BidirectionalTraversalConcept;

        template <typename Iterator>
        class RandomAccessTraversalConcept;

        // Interoperability

        template <typename Iterator, typename ConstIterator>
        class InteroperableIteratorConcept;

    }

[endsect]

[endsect]