[ceph.git] / ceph / src / boost / libs / iterator / doc / InteroperableIterator.rst

.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

Interoperable Iterator Concept
..............................

A class or built-in type ``X`` that models Single Pass Iterator is
*interoperable with* a class or built-in type ``Y`` that also models
Single Pass Iterator if the following expressions are valid and
respect the stated semantics. In the tables below, ``x`` is an object
of type ``X``, ``y`` is an object of type ``Y``, ``Distance`` is
``iterator_traits<Y>::difference_type``, and ``n`` represents a
constant object of type ``Distance``.

+-----------+-----------------------+---------------------------------------------------+
|Expression |Return Type            |Assertion/Precondition/Postcondition               |
+===========+=======================+===================================================+
|``y = x``  |``Y``                  |post: ``y == x``                                   |
+-----------+-----------------------+---------------------------------------------------+
|``Y(x)``   |``Y``                  |post: ``Y(x) == x``                                |
+-----------+-----------------------+---------------------------------------------------+
|``x == y`` |convertible to ``bool``|``==`` is an equivalence relation over its domain. |
+-----------+-----------------------+---------------------------------------------------+
|``y == x`` |convertible to ``bool``|``==`` is an equivalence relation over its domain. |
+-----------+-----------------------+---------------------------------------------------+
|``x != y`` |convertible to ``bool``|``bool(a==b) != bool(a!=b)`` over its domain.      |
+-----------+-----------------------+---------------------------------------------------+
|``y != x`` |convertible to ``bool``|``bool(a==b) != bool(a!=b)`` over its domain.      |
+-----------+-----------------------+---------------------------------------------------+

If ``X`` and ``Y`` both model Random Access Traversal Iterator then
the following additional requirements must be met.

+-----------+-----------------------+---------------------+--------------------------------------+
|Expression |Return Type            |Operational Semantics|Assertion/ Precondition               |
+===========+=======================+=====================+======================================+
|``x < y``  |convertible to ``bool``|``y - x > 0``        |``<`` is a total ordering relation    |
+-----------+-----------------------+---------------------+--------------------------------------+
|``y < x``  |convertible to ``bool``|``x - y > 0``        |``<`` is a total ordering relation    |
+-----------+-----------------------+---------------------+--------------------------------------+
|``x > y``  |convertible to ``bool``|``y < x``            |``>`` is a total ordering relation    |
+-----------+-----------------------+---------------------+--------------------------------------+
|``y > x``  |convertible to ``bool``|``x < y``            |``>`` is a total ordering relation    |
+-----------+-----------------------+---------------------+--------------------------------------+
|``x >= y`` |convertible to ``bool``|``!(x < y)``         |                                      |
+-----------+-----------------------+---------------------+--------------------------------------+
|``y >= x`` |convertible to ``bool``|``!(y < x)``         |                                      |
+-----------+-----------------------+---------------------+--------------------------------------+
|``x <= y`` |convertible to ``bool``|``!(x > y)``         |                                      |
+-----------+-----------------------+---------------------+--------------------------------------+
|``y <= x`` |convertible to ``bool``|``!(y > x)``         |                                      |
+-----------+-----------------------+---------------------+--------------------------------------+
|``y - x``  |``Distance``           |``distance(Y(x),y)`` |pre: there exists a value ``n`` of    |
|           |                       |                     |``Distance`` such that ``x + n == y``.|
|           |                       |                     |``y == x + (y - x)``.                 |
+-----------+-----------------------+---------------------+--------------------------------------+ 
|``x - y``  |``Distance``           |``distance(y,Y(x))`` |pre: there exists a value ``n`` of    |
|           |                       |                     |``Distance`` such that ``y + n == x``.|
|           |                       |                     |``x == y + (x - y)``.                 |
+-----------+-----------------------+---------------------+--------------------------------------+
Commit	Line	Data
7c673cae FG	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	Interoperable Iterator Concept
	6	..............................
	7
	8	A class or built-in type ``X`` that models Single Pass Iterator is
	9	interoperable with a class or built-in type ``Y`` that also models
	10	Single Pass Iterator if the following expressions are valid and
	11	respect the stated semantics. In the tables below, ``x`` is an object
	12	of type ``X``, ``y`` is an object of type ``Y``, ``Distance`` is
	13	``iterator_traits<Y>::difference_type``, and ``n`` represents a
	14	constant object of type ``Distance``.
	15
	16	+-----------+-----------------------+---------------------------------------------------+
	17	\|Expression \|Return Type \|Assertion/Precondition/Postcondition \|
	18	+===========+=======================+===================================================+
	19	\|``y = x`` \|``Y`` \|post: ``y == x`` \|
	20	+-----------+-----------------------+---------------------------------------------------+
	21	\|``Y(x)`` \|``Y`` \|post: ``Y(x) == x`` \|
	22	+-----------+-----------------------+---------------------------------------------------+
	23	\|``x == y`` \|convertible to ``bool``\|``==`` is an equivalence relation over its domain. \|
	24	+-----------+-----------------------+---------------------------------------------------+
	25	\|``y == x`` \|convertible to ``bool``\|``==`` is an equivalence relation over its domain. \|
	26	+-----------+-----------------------+---------------------------------------------------+
	27	\|``x != y`` \|convertible to ``bool``\|``bool(a==b) != bool(a!=b)`` over its domain. \|
	28	+-----------+-----------------------+---------------------------------------------------+
	29	\|``y != x`` \|convertible to ``bool``\|``bool(a==b) != bool(a!=b)`` over its domain. \|
	30	+-----------+-----------------------+---------------------------------------------------+
	31
	32	If ``X`` and ``Y`` both model Random Access Traversal Iterator then
	33	the following additional requirements must be met.
	34
	35	+-----------+-----------------------+---------------------+--------------------------------------+
	36	\|Expression \|Return Type \|Operational Semantics\|Assertion/ Precondition \|
	37	+===========+=======================+=====================+======================================+
	38	\|``x < y`` \|convertible to ``bool``\|``y - x > 0`` \|``<`` is a total ordering relation \|
	39	+-----------+-----------------------+---------------------+--------------------------------------+
	40	\|``y < x`` \|convertible to ``bool``\|``x - y > 0`` \|``<`` is a total ordering relation \|
	41	+-----------+-----------------------+---------------------+--------------------------------------+
	42	\|``x > y`` \|convertible to ``bool``\|``y < x`` \|``>`` is a total ordering relation \|
	43	+-----------+-----------------------+---------------------+--------------------------------------+
	44	\|``y > x`` \|convertible to ``bool``\|``x < y`` \|``>`` is a total ordering relation \|
	45	+-----------+-----------------------+---------------------+--------------------------------------+
	46	\|``x >= y`` \|convertible to ``bool``\|``!(x < y)`` \| \|
	47	+-----------+-----------------------+---------------------+--------------------------------------+
	48	\|``y >= x`` \|convertible to ``bool``\|``!(y < x)`` \| \|
	49	+-----------+-----------------------+---------------------+--------------------------------------+
	50	\|``x <= y`` \|convertible to ``bool``\|``!(x > y)`` \| \|
	51	+-----------+-----------------------+---------------------+--------------------------------------+
	52	\|``y <= x`` \|convertible to ``bool``\|``!(y > x)`` \| \|
	53	+-----------+-----------------------+---------------------+--------------------------------------+
	54	\|``y - x`` \|``Distance`` \|``distance(Y(x),y)`` \|pre: there exists a value ``n`` of \|
	55	\| \| \| \|``Distance`` such that ``x + n == y``.\|
	56	\| \| \| \|``y == x + (y - x)``. \|
	57	+-----------+-----------------------+---------------------+--------------------------------------+
	58	\|``x - y`` \|``Distance`` \|``distance(y,Y(x))`` \|pre: there exists a value ``n`` of \|
	59	\| \| \| \|``Distance`` such that ``y + n == x``.\|
	60	\| \| \| \|``x == y + (x - y)``. \|
	61	+-----------+-----------------------+---------------------+--------------------------------------+