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

   1 .. Copyright David Abrahams 2006. 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 Random Access Traversal Concept
   6 ...............................
   7
   8 A class or built-in type ``X`` models the *Random Access Traversal*
   9 concept if the following expressions are valid and respect the stated
  10 semantics.  In the table below, ``Distance`` is
  11 ``iterator_traits<X>::difference_type`` and ``n`` represents a
  12 constant object of type ``Distance``.
  13
  14 +------------------------------------------------------------------------------------------------------------------+
  15 |Random Access Traversal Iterator Requirements (in addition to Bidirectional Traversal)                            |
  16 +-------------------------------+---------------------------------+-------------------------+----------------------+
  17 |Expression                     |Return Type                      |Operational Semantics    |Assertion/            |
  18 |                               |                                 |                         |Precondition          |
  19 +===============================+=================================+=========================+======================+
  20 |``r += n``                     |``X&``                           |::                       |                      |
  21 |                               |                                 |                         |                      |
  22 |                               |                                 | {                       |                      |
  23 |                               |                                 |   Distance m = n;       |                      |
  24 |                               |                                 |   if (m >= 0)           |                      |
  25 |                               |                                 |     while (m--)         |                      |
  26 |                               |                                 |       ++r;              |                      |
  27 |                               |                                 |   else                  |                      |
  28 |                               |                                 |     while (m++)         |                      |
  29 |                               |                                 |       --r;              |                      |
  30 |                               |                                 |   return r;             |                      |
  31 |                               |                                 | }                       |                      |
  32 +-------------------------------+---------------------------------+-------------------------+----------------------+
  33 |``a + n``, ``n + a``           |``X``                            |``{ X tmp = a; return tmp|                      |
  34 |                               |                                 |+= n; }``                |                      |
  35 |                               |                                 |                         |                      |
  36 +-------------------------------+---------------------------------+-------------------------+----------------------+
  37 |``r -= n``                     |``X&``                           |``return r += -n``       |                      |
  38 +-------------------------------+---------------------------------+-------------------------+----------------------+
  39 |``a - n``                      |``X``                            |``{ X tmp = a; return tmp|                      |
  40 |                               |                                 |-= n; }``                |                      |
  41 |                               |                                 |                         |                      |
  42 +-------------------------------+---------------------------------+-------------------------+----------------------+
  43 |``b - a``                      |``Distance``                     |``a < b ?  distance(a,b) |pre: there exists a   |
  44 |                               |                                 |: -distance(b,a)``       |value ``n`` of        |
  45 |                               |                                 |                         |``Distance`` such that|
  46 |                               |                                 |                         |``a + n == b``.  ``b  |
  47 |                               |                                 |                         |== a + (b - a)``.     |
  48 +-------------------------------+---------------------------------+-------------------------+----------------------+
  49 |``a[n]``                       |convertible to T                 |``*(a + n)``             |pre: a is a *Readable |
  50 |                               |                                 |                         |Iterator*             |
  51 +-------------------------------+---------------------------------+-------------------------+----------------------+
  52 |``a[n] = v``                   |convertible to T                 |``*(a + n) = v``         |pre: a is a *Writable |
  53 |                               |                                 |                         |iterator*             |
  54 +-------------------------------+---------------------------------+-------------------------+----------------------+
  55 |``a < b``                      |convertible to ``bool``          |``b - a > 0``            |``<`` is a total      |
  56 |                               |                                 |                         |ordering relation     |
  57 +-------------------------------+---------------------------------+-------------------------+----------------------+
  58 |``a > b``                      |convertible to ``bool``          |``b < a``                |``>`` is a total      |
  59 |                               |                                 |                         |ordering relation     |
  60 +-------------------------------+---------------------------------+-------------------------+----------------------+
  61 |``a >= b``                     |convertible to ``bool``          |``!(a < b)``             |                      |
  62 +-------------------------------+---------------------------------+-------------------------+----------------------+
  63 |``a <= b``                     |convertible to ``bool``          |``!(a > b)``             |                      |
  64 +-------------------------------+---------------------------------+-------------------------+----------------------+
  65 |``iterator_traversal<X>::type``|Convertible to                   |                         |                      |
  66 |                               |``random_access_traversal_tag``  |                         |                      |
  67 +-------------------------------+---------------------------------+-------------------------+----------------------+