ceph/src/boost/libs/iterator/doc/iterator_archetypes.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 ++++++++++++++++++++
   6  Iterator Archetype
   7 ++++++++++++++++++++
   8
   9 :Author: David Abrahams, Jeremy Siek, Thomas Witt
  10 :Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@styleadvisor.com
  11 :organization: `Boost Consulting`_, Indiana University `Open Systems
  12                Lab`_, `Zephyr Associates, Inc.`_
  13 :date: $Date$
  14 :copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2004.
  15
  16 .. _`Boost Consulting`: http://www.boost-consulting.com
  17 .. _`Open Systems Lab`: http://www.osl.iu.edu
  18 .. _`Zephyr Associates, Inc.`: http://www.styleadvisor.com
  19
  20 :abstract: The ``iterator_archetype`` class constructs a minimal implementation of
  21   one of the iterator access concepts and one of the iterator traversal concepts.
  22   This is used for doing a compile-time check to see if a the type requirements
  23   of a template are really enough to cover the implementation of the template.
  24   For further information see the documentation for the |concepts|_ library.
  25
  26 .. |concepts| replace:: ``boost::concept_check``
  27 .. _concepts: ../../concept_check/index.html
  28
  29
  30 .. contents:: Table of Contents
  31
  32 Reference
  33 =========
  34
  35 ``iterator_archetype`` Synopsis
  36 ...............................
  37
  38 ::
  39
  40     namespace iterator_archetypes
  41     {
  42         // Access categories
  43
  44         typedef /*implementation  defined*/ readable_iterator_t;
  45         typedef /*implementation  defined*/ writable_iterator_t;
  46         typedef /*implementation  defined*/ readable_writable_iterator_t;
  47         typedef /*implementation  defined*/ readable_lvalue_iterator_t;
  48         typedef /*implementation  defined*/ writable_lvalue_iterator_t;
  49
  50     }
  51
  52     template <
  53         class Value
  54       , class AccessCategory
  55       , class TraversalCategory
  56     >
  57     class iterator_archetype
  58     {
  59         typedef /* see below */ value_type;
  60         typedef /* see below */ reference;
  61         typedef /* see below */ pointer;
  62         typedef /* see below */ difference_type;
  63         typedef /* see below */ iterator_category;
  64     };
  65
  66 ``Access Category Tags``
  67 ........................
  68
  69 The access category types provided correspond to the following
  70 standard iterator access concept combinations:
  71
  72 ::
  73
  74     readable_iterator_t :=
  75
  76       Readable Iterator
  77
  78     writable_iterator_t :=
  79
  80       Writeable Iterator
  81
  82     readable_writable_iterator_t :=
  83
  84       Readable Iterator & Writeable Iterator & Swappable Iterator
  85
  86     readable_lvalue_iterator_t :=
  87
  88       Readable Iterator & Lvalue Iterator
  89
  90     writeable_lvalue_iterator_t :=
  91
  92       Readable Iterator & Writeable Iterator & Swappable Iterator & Lvalue Iterator
  93
  94 ``iterator_archetype`` Requirements
  95 ...................................
  96
  97 The ``AccessCategory`` argument must be one of the predefined access
  98 category tags. The ``TraversalCategory`` must be one of the standard
  99 traversal tags. The ``Value`` type must satisfy the requirements of
 100 the iterator concept specified by ``AccessCategory`` and
 101 ``TraversalCategory`` as implied by the nested traits types.
 102
 103 ``iterator_archetype`` Models
 104 .............................
 105
 106 ``iterator_archetype`` models the iterator concepts specified by the
 107 ``AccessCategory`` and ``TraversalCategory``
 108 arguments. ``iterator_archetype`` does not model any other access
 109 concepts or any more derived traversal concepts.
 110
 111 ``Traits``
 112 ..........
 113
 114 The nested trait types are defined as follows:
 115
 116 ::
 117
 118    if (AccessCategory == readable_iterator_t)
 119
 120      value_type = Value
 121      reference  = Value
 122      pointer    = Value*
 123
 124    else if (AccessCategory == writable_iterator_t)
 125
 126      value_type = void
 127      reference  = void
 128      pointer    = void
 129
 130    else if (AccessCategory == readable_writable_iterator_t)
 131
 132      value_type = Value
 133
 134      reference :=
 135
 136        A type X that is convertible to Value for which the following
 137        expression is valid. Given an object x of type X and v of type
 138        Value.
 139
 140        x = v
 141
 142      pointer    = Value*
 143
 144    else if (AccessCategory == readable_lvalue_iterator_t)
 145
 146      value_type = Value
 147      reference  = Value const&
 148      pointer    = Value const*
 149
 150    else if (AccessCategory == writable_lvalue_iterator_t)
 151
 152      value_type = Value
 153      reference  = Value&
 154      pointer    = Value*
 155
 156    if ( TraversalCategory is convertible to forward_traversal_tag )
 157
 158      difference_type := ptrdiff_t
 159
 160    else
 161
 162      difference_type := unspecified type
 163
 164
 165    iterator_category :=
 166
 167      A type X satisfying the following two constraints:
 168
 169         1. X is convertible to X1, and not to any more-derived
 170            type, where X1 is defined by:
 171
 172              if (reference is a reference type
 173                  && TraversalCategory is convertible to forward_traversal_tag)
 174              {
 175                  if (TraversalCategory is convertible to random_access_traversal_tag)
 176                      X1 = random_access_iterator_tag
 177                  else if (TraversalCategory is convertible to bidirectional_traversal_tag)
 178                      X1 = bidirectional_iterator_tag
 179                  else
 180                      X1 = forward_iterator_tag
 181              }
 182              else
 183              {
 184                  if (TraversalCategory is convertible to single_pass_traversal_tag
 185                      && reference != void)
 186                      X1 = input_iterator_tag
 187                  else
 188                      X1 = output_iterator_tag
 189              }
 190
 191         2. X is convertible to TraversalCategory
 192
 193