[ceph.git] / ceph / src / boost / libs / iterator / doc / permutation_iterator_ref.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)

.. parsed-literal::

  template< class ElementIterator
	  , class IndexIterator
	  , class ValueT        = use_default
	  , class CategoryT     = use_default
	  , class ReferenceT    = use_default
	  , class DifferenceT   = use_default >
  class permutation_iterator
  {
  public:
    permutation_iterator();
    explicit permutation_iterator(ElementIterator x, IndexIterator y);

    template< class OEIter, class OIIter, class V, class C, class R, class D >
    permutation_iterator(
	permutation_iterator<OEIter, OIIter, V, C, R, D> const& r
	, typename enable_if_convertible<OEIter, ElementIterator>::type* = 0
	, typename enable_if_convertible<OIIter, IndexIterator>::type* = 0
	);
    reference operator*() const;
    permutation_iterator& operator++();
    ElementIterator const& base() const;
  private:
    ElementIterator m_elt;      // exposition only
    IndexIterator m_order;      // exposition only
  };

  template <class ElementIterator, class IndexIterator>
  permutation_iterator<ElementIterator, IndexIterator> 
  make_permutation_iterator( ElementIterator e, IndexIterator i);


``permutation_iterator`` requirements
-------------------------------------

``ElementIterator`` shall model Random Access Traversal Iterator.
``IndexIterator`` shall model Readable Iterator.  The value type of
the ``IndexIterator`` must be convertible to the difference type of
``ElementIterator``.


``permutation_iterator`` models
-------------------------------

``permutation_iterator`` models the same iterator traversal concepts
as ``IndexIterator`` and the same iterator access concepts as
``ElementIterator``.

If ``IndexIterator`` models Single Pass Iterator and 
``ElementIterator`` models Readable Iterator then
``permutation_iterator`` models Input Iterator.

If ``IndexIterator`` models Forward Traversal Iterator and 
``ElementIterator`` models Readable Lvalue Iterator then
``permutation_iterator`` models Forward Iterator.

If ``IndexIterator`` models Bidirectional Traversal Iterator and 
``ElementIterator`` models Readable Lvalue Iterator then
``permutation_iterator`` models Bidirectional Iterator.

If ``IndexIterator`` models Random Access Traversal Iterator and
``ElementIterator`` models Readable Lvalue Iterator then
``permutation_iterator`` models Random Access Iterator.

``permutation_iterator<E1, X, V1, C2, R1, D1>`` is interoperable
with ``permutation_iterator<E2, Y, V2, C2, R2, D2>`` if and only if
``X`` is interoperable with ``Y`` and ``E1`` is convertible
to ``E2``.


``permutation_iterator`` operations
-----------------------------------

In addition to those operations required by the concepts that
``permutation_iterator`` models, ``permutation_iterator`` provides the
following operations.

``permutation_iterator();``

:Effects: Default constructs ``m_elt`` and ``m_order``.


``explicit permutation_iterator(ElementIterator x, IndexIterator y);``

:Effects: Constructs ``m_elt`` from ``x`` and ``m_order`` from ``y``.


::

    template< class OEIter, class OIIter, class V, class C, class R, class D >
    permutation_iterator(
	permutation_iterator<OEIter, OIIter, V, C, R, D> const& r
	, typename enable_if_convertible<OEIter, ElementIterator>::type* = 0
	, typename enable_if_convertible<OIIter, IndexIterator>::type* = 0
	);

:Effects: Constructs ``m_elt`` from ``r.m_elt`` and
  ``m_order`` from ``y.m_order``.


``reference operator*() const;``

:Returns: ``*(m_elt + *m_order)``


``permutation_iterator& operator++();``

:Effects: ``++m_order``
:Returns: ``*this``


``ElementIterator const& base() const;``

:Returns: ``m_order``


::

  template <class ElementIterator, class IndexIterator>
  permutation_iterator<ElementIterator, IndexIterator> 
  make_permutation_iterator(ElementIterator e, IndexIterator i);

:Returns: ``permutation_iterator<ElementIterator, IndexIterator>(e, i)``
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	.. parsed-literal::
	6
	7	template< class ElementIterator
	8	, class IndexIterator
	9	, class ValueT = use_default
	10	, class CategoryT = use_default
	11	, class ReferenceT = use_default
	12	, class DifferenceT = use_default >
	13	class permutation_iterator
	14	{
	15	public:
	16	permutation_iterator();
	17	explicit permutation_iterator(ElementIterator x, IndexIterator y);
	18
	19	template< class OEIter, class OIIter, class V, class C, class R, class D >
	20	permutation_iterator(
	21	permutation_iterator<OEIter, OIIter, V, C, R, D> const& r
	22	, typename enable_if_convertible<OEIter, ElementIterator>::type* = 0
	23	, typename enable_if_convertible<OIIter, IndexIterator>::type* = 0
	24	);
	25	reference operator*() const;
	26	permutation_iterator& operator++();
	27	ElementIterator const& base() const;
	28	private:
	29	ElementIterator m_elt; // exposition only
	30	IndexIterator m_order; // exposition only
	31	};
	32
	33	template <class ElementIterator, class IndexIterator>
	34	permutation_iterator<ElementIterator, IndexIterator>
	35	make_permutation_iterator( ElementIterator e, IndexIterator i);
	36
	37
	38
	39	``permutation_iterator`` requirements
	40	-------------------------------------
	41
	42	``ElementIterator`` shall model Random Access Traversal Iterator.
	43	``IndexIterator`` shall model Readable Iterator. The value type of
	44	the ``IndexIterator`` must be convertible to the difference type of
	45	``ElementIterator``.
	46
	47
	48	``permutation_iterator`` models
	49	-------------------------------
	50
	51	``permutation_iterator`` models the same iterator traversal concepts
	52	as ``IndexIterator`` and the same iterator access concepts as
	53	``ElementIterator``.
	54
	55	If ``IndexIterator`` models Single Pass Iterator and
	56	``ElementIterator`` models Readable Iterator then
	57	``permutation_iterator`` models Input Iterator.
	58
	59	If ``IndexIterator`` models Forward Traversal Iterator and
	60	``ElementIterator`` models Readable Lvalue Iterator then
	61	``permutation_iterator`` models Forward Iterator.
	62
	63	If ``IndexIterator`` models Bidirectional Traversal Iterator and
	64	``ElementIterator`` models Readable Lvalue Iterator then
65	``permutation_iterator`` models Bidirectional Iterator.
66
67	If ``IndexIterator`` models Random Access Traversal Iterator and
68	``ElementIterator`` models Readable Lvalue Iterator then
69	``permutation_iterator`` models Random Access Iterator.
70
71	``permutation_iterator<E1, X, V1, C2, R1, D1>`` is interoperable
72	with ``permutation_iterator<E2, Y, V2, C2, R2, D2>`` if and only if
73	``X`` is interoperable with ``Y`` and ``E1`` is convertible
74	to ``E2``.
75
76
77	``permutation_iterator`` operations
78	-----------------------------------
79
80	In addition to those operations required by the concepts that
81	``permutation_iterator`` models, ``permutation_iterator`` provides the
82	following operations.
83
84	``permutation_iterator();``
85
86	:Effects: Default constructs ``m_elt`` and ``m_order``.
87
88
89	``explicit permutation_iterator(ElementIterator x, IndexIterator y);``
90
91	:Effects: Constructs ``m_elt`` from ``x`` and ``m_order`` from ``y``.
92
93
94	::
95
96	template< class OEIter, class OIIter, class V, class C, class R, class D >
97	permutation_iterator(
98	permutation_iterator<OEIter, OIIter, V, C, R, D> const& r
99	, typename enable_if_convertible<OEIter, ElementIterator>::type* = 0
100	, typename enable_if_convertible<OIIter, IndexIterator>::type* = 0
101	);
102
103	:Effects: Constructs ``m_elt`` from ``r.m_elt`` and
104	``m_order`` from ``y.m_order``.
105
106
107	``reference operator*() const;``
108
109	:Returns: ``(m_elt + m_order)``
110
111
112	``permutation_iterator& operator++();``
113
114	:Effects: ``++m_order``
115	:Returns: ``*this``
116
117
118	``ElementIterator const& base() const;``
119
120	:Returns: ``m_order``
121
122
123	::
124
125	template <class ElementIterator, class IndexIterator>
126	permutation_iterator<ElementIterator, IndexIterator>
127	make_permutation_iterator(ElementIterator e, IndexIterator i);
128
129	:Returns: ``permutation_iterator<ElementIterator, IndexIterator>(e, i)``
130