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

   1 .. 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 .. Version 1.2 of this ReStructuredText document corresponds to
   6    n1530_, the paper accepted by the LWG for TR1.
   7
   8 .. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.
   9
  10 The ``iterator_adaptor`` class template adapts some ``Base`` [#base]_
  11 type to create a new iterator.  Instantiations of ``iterator_adaptor``
  12 are derived from a corresponding instantiation of ``iterator_facade``
  13 and implement the core behaviors in terms of the ``Base`` type. In
  14 essence, ``iterator_adaptor`` merely forwards all operations to an
  15 instance of the ``Base`` type, which it stores as a member.
  16
  17 .. [#base] The term "Base" here does not refer to a base class and is
  18    not meant to imply the use of derivation. We have followed the lead
  19    of the standard library, which provides a base() function to access
  20    the underlying iterator object of a ``reverse_iterator`` adaptor.
  21
  22 The user of ``iterator_adaptor`` creates a class derived from an
  23 instantiation of ``iterator_adaptor`` and then selectively
  24 redefines some of the core member functions described in the
  25 ``iterator_facade`` core requirements table. The ``Base`` type need
  26 not meet the full requirements for an iterator; it need only
  27 support the operations used by the core interface functions of
  28 ``iterator_adaptor`` that have not been redefined in the user's
  29 derived class.
  30
  31 Several of the template parameters of ``iterator_adaptor`` default
  32 to ``use_default``. This allows the
  33 user to make use of a default parameter even when she wants to
  34 specify a parameter later in the parameter list.  Also, the
  35 defaults for the corresponding associated types are somewhat
  36 complicated, so metaprogramming is required to compute them, and
  37 ``use_default`` can help to simplify the implementation.  Finally,
  38 the identity of the ``use_default`` type is not left unspecified
  39 because specification helps to highlight that the ``Reference``
  40 template parameter may not always be identical to the iterator's
  41 ``reference`` type, and will keep users from making mistakes based on
  42 that assumption.
  43