libs/iterator/doc/quickbook/utilities.qbk

   1
   2 [section:utilities Iterator Utilities]
   3
   4 [section:utilities_traits Traits]
   5
   6 [h2 Overview]
   7
   8 Have you ever wanted to write a generic function that can operate
   9 on any kind of dereferenceable object?  If you have, you've
  10 probably run into the problem of how to determine the type that the
  11 object "points at":
  12
  13    template <class Dereferenceable>
  14    void f(Dereferenceable p)
  15    {
  16        *what-goes-here?* value = \*p;
  17        ...
  18    }
  19
  20
  21 [h2 `pointee`]
  22
  23 It turns out to be impossible to come up with a fully-general
  24 algorithm to do determine *what-goes-here* directly, but it is
  25 possible to require that `pointee<Dereferenceable>::type` is
  26 correct. Naturally, `pointee` has the same difficulty: it can't
  27 determine the appropriate `::type` reliably for all
  28 `Dereferenceable`\ s, but it makes very good guesses (it works
  29 for all pointers, standard and boost smart pointers, and
  30 iterators), and when it guesses wrongly, it can be specialized as
  31 necessary:
  32
  33   namespace boost
  34   {
  35     template <class T>
  36     struct pointee<third_party_lib::smart_pointer<T> >
  37     {
  38         typedef T type;
  39     };
  40   }
  41
  42 [h2 `indirect_reference`]
  43
  44 `indirect_reference<T>::type` is rather more specialized than
  45 `pointee`, and is meant to be used to forward the result of
  46 dereferencing an object of its argument type.  Most dereferenceable
  47 types just return a reference to their pointee, but some return
  48 proxy references or return the pointee by value.  When that
  49 information is needed, call on `indirect_reference`.
  50
  51 Both of these templates are essential to the correct functioning of
  52 [link boost_iterator.indirect `indirect_iterator`].
  53
  54 [h2 `minimum_category`]
  55
  56 `minimum_category` takes two iterator categories or two iterator traversal tags
  57 and returns the one that is the weakest (i.e. least advanced). For example:
  58
  59   static_assert(
  60       is_same<
  61           minimum_category<
  62               std::forward_iterator_tag,
  63               std::random_access_iterator_tag
  64           >::type,
  65           std::forward_iterator_tag
  66       >::value,
  67       "Unexpected minimum_category result"
  68   );
  69
  70 [h2 Iterator category and traversal tags manipulation]
  71
  72 The library provides several utilities to simplify conversions between iterator categories
  73 and traversal tags:
  74
  75 * `iterator_category_to_traversal<C>::type` - the metafunction takes an iterator category `C` and returns
  76 the corresponding traversal tag.
  77 * `iterator_traversal<T>::type` - a shorthand for `iterator_category_to_traversal<iterator_category<T>::type>::type`.
  78 * `pure_traversal_tag<T>::type` - the metafunction takes a tag `T` which derives from one of the iterator traversal tags
  79 and returns that traversal tag. `T` may also derive from other tags describing the iterator (e.g. whether this is a `const`-iterator
  80 or not), these additional tags are not considered.
  81 * `pure_iterator_traversal<T>::type` - a shorthand for `pure_traversal_tag<iterator_traversal<T>::type>::type`.
  82
  83 [h2 Reference]
  84
  85 [h3 `pointee`]
  86
  87   template <class Dereferenceable>
  88   struct pointee
  89   {
  90       typedef /* see below */ type;
  91   };
  92
  93 [*Requires:] For an object `x` of type `Dereferenceable`, `*x`
  94   is well-formed.  If `++x` is ill-formed it shall neither be
  95   ambiguous nor shall it violate access control, and
  96   `Dereferenceable::element_type` shall be an accessible type.
  97   Otherwise `iterator_traits<Dereferenceable>::value_type` shall
  98   be well formed. \[Note: These requirements need not apply to
  99   explicit or partial specializations of `pointee`\]
 100
 101 `type` is determined according to the following algorithm, where
 102 `x` is an object of type `Dereferenceable`:
 103
 104   if ( ++x is ill-formed )
 105   {
 106       return `Dereferenceable::element_type`
 107   }
 108   else if (`*x` is a mutable reference to
 109            std::iterator_traits<Dereferenceable>::value_type)
 110   {
 111       return iterator_traits<Dereferenceable>::value_type
 112   }
 113   else
 114   {
 115       return iterator_traits<Dereferenceable>::value_type const
 116   }
 117
 118 [h3 `indirect_reference`]
 119
 120   template <class Dereferenceable>
 121   struct indirect_reference
 122   {
 123       typedef /* see below */ type;
 124   };
 125
 126 [*Requires:] For an object `x` of type `Dereferenceable`, `*x`
 127   is well-formed.  If `++x` is ill-formed it shall neither be
 128   ambiguous nor shall it violate access control, and
 129   `pointee<Dereferenceable>::type&` shall be well-formed.
 130   Otherwise `iterator_traits<Dereferenceable>::reference` shall
 131   be well formed.  \[Note: These requirements need not apply to
 132   explicit or partial specializations of `indirect_reference`\]
 133
 134 `type` is determined according to the following algorithm, where
 135 `x` is an object of type `Dereferenceable`:
 136
 137   if ( ++x is ill-formed )
 138       return `pointee<Dereferenceable>::type&`
 139   else
 140       std::iterator_traits<Dereferenceable>::reference
 141
 142 [h3 `minimum_category`]
 143
 144   template <typename C1, typename C2>
 145   struct minimum_category
 146   {
 147       typedef /* see below */ type;
 148   };
 149
 150 [*Requires:] Both `C1` and `C2` shall be standard iterator categories or
 151   iterator traversal tags.
 152
 153 `type` is determined according to the following algorithm, where `c1` is an
 154 object of type `C1` and `c2` is an object of type `C2`:
 155
 156   if (c1 is convertible to c2)
 157       return C2;
 158   else
 159       return C1;
 160
 161 [note The above definition relies on the fact that the more restricting categories
 162 and traversal tags are convertible to the less restricting ones.]
 163
 164 [h3 `iterator_category_to_traversal`]
 165
 166   template <typename C>
 167   struct iterator_category_to_traversal
 168   {
 169       typedef /* see below */ type;
 170   };
 171
 172 [*Requires:] `C` shall be a standard iterator category or an
 173   iterator traversal tag.
 174
 175 If `C` is an iterator traversal tag or convertible to one, `type` equivalent to `C`.
 176 Otherwise, `type` is defined to the closest iterator traversal tag matching `C`.
 177
 178 [h3 `iterator_traversal`]
 179
 180   template <typename Iterator>
 181   struct iterator_traversal
 182   {
 183       typedef typename iterator_category_to_traversal<
 184           typename iterator_category<Iterator>::type
 185       >::type type;
 186   };
 187
 188 [*Requires:] `Iterator` shall be an iterator.
 189
 190 [h3 `pure_traversal_tag`]
 191
 192   template <typename T>
 193   struct pure_traversal_tag
 194   {
 195       typedef /* see below */ type;
 196   };
 197
 198 [*Requires:] `T` shall be convertible to an iterator traversal tag.
 199
 200 `type` is defined to be the most advanced traversal tag `Tag` so that `T` is convertible to `Tag`.
 201
 202 [h3 `pure_iterator_traversal`]
 203
 204   template <typename Iterator>
 205   struct pure_iterator_traversal
 206   {
 207       typedef typename pure_traversal_tag<
 208           typename iterator_traversal<Iterator>::type
 209       >::type type;
 210   };
 211
 212 [*Requires:] `Iterator` shall be an iterator.
 213
 214 [endsect]
 215
 216 [section:utilities_testing Testing and Concept Checking]
 217
 218 The iterator concept checking classes provide a mechanism for a
 219 template to report better error messages when a user instantiates
 220 the template with a type that does not meet the requirements of the
 221 template.
 222
 223 For an introduction to using concept checking classes, see
 224 the documentation for the
 225 [@../../concept_check/index.html `boost::concept_check`] library.
 226
 227
 228 [h2 Reference]
 229
 230 [h3 Iterator Access Concepts]
 231
 232 * |Readable|_
 233 * |Writable|_
 234 * |Swappable|_
 235 * |Lvalue|_
 236
 237 [/ .. |Readable| replace:: *Readable Iterator* ]
 238 [/ .. _Readable: ReadableIterator.html            ]
 239 [/                                                ]
 240 [/ .. |Writable| replace:: *Writable Iterator*    ]
 241 [/ .. _Writable: WritableIterator.html            ]
 242 [/                                                ]
 243 [/ .. |Swappable| replace:: *Swappable Iterator*  ]
 244 [/ .. _Swappable: SwappableIterator.html          ]
 245 [/                                                ]
 246 [/ .. |Lvalue| replace:: *Lvalue Iterator*        ]
 247 [/ .. _Lvalue: LvalueIterator.html                ]
 248
 249
 250 Iterator Traversal Concepts
 251 ...........................
 252
 253 * |Incrementable|_
 254 * |SinglePass|_
 255 * |Forward|_
 256 * |Bidir|_
 257 * |Random|_
 258
 259
 260 [/ .. |Incrementable| replace:: *Incrementable Iterator* ]
 261 [/ .. _Incrementable: IncrementableIterator.html         ]
 262 [/                                                       ]
 263 [/ .. |SinglePass| replace:: *Single Pass Iterator*      ]
 264 [/ .. _SinglePass: SinglePassIterator.html               ]
 265 [/                                                       ]
 266 [/ .. |Forward| replace:: *Forward Traversal*            ]
 267 [/ .. _Forward: ForwardTraversal.html                    ]
 268 [/                                                       ]
 269 [/ .. |Bidir| replace:: *Bidirectional Traversal*        ]
 270 [/ .. _Bidir: BidirectionalTraversal.html                ]
 271 [/                                                       ]
 272 [/ .. |Random| replace:: *Random Access Traversal*       ]
 273 [/ .. _Random: RandomAccessTraversal.html                ]
 274
 275
 276
 277 [h3 `iterator_concepts.hpp` Synopsis]
 278
 279     namespace boost_concepts {
 280
 281         // Iterator Access Concepts
 282
 283         template <typename Iterator>
 284         class ReadableIteratorConcept;
 285
 286         template <
 287             typename Iterator
 288           , typename ValueType = std::iterator_traits<Iterator>::value_type
 289         >
 290         class WritableIteratorConcept;
 291
 292         template <typename Iterator>
 293         class SwappableIteratorConcept;
 294
 295         template <typename Iterator>
 296         class LvalueIteratorConcept;
 297
 298         // Iterator Traversal Concepts
 299
 300         template <typename Iterator>
 301         class IncrementableIteratorConcept;
 302
 303         template <typename Iterator>
 304         class SinglePassIteratorConcept;
 305
 306         template <typename Iterator>
 307         class ForwardTraversalConcept;
 308
 309         template <typename Iterator>
 310         class BidirectionalTraversalConcept;
 311
 312         template <typename Iterator>
 313         class RandomAccessTraversalConcept;
 314
 315         // Interoperability
 316
 317         template <typename Iterator, typename ConstIterator>
 318         class InteroperableIteratorConcept;
 319
 320     }
 321
 322 [endsect]
 323
 324 [endsect]