137 lines
4.2 KiB
XML
137 lines
4.2 KiB
XML
<?xml version="1.0"?>
|
|
<concept name="BidirectionalIterator" category="Iterator"><!--
|
|
Based on concepts from the SGI Standard Template Library documentation:
|
|
Copyright (c) 1996-1999
|
|
Silicon Graphics Computer Systems, Inc.
|
|
|
|
Copyright (c) 1994
|
|
Hewlett-Packard Company
|
|
--><!--
|
|
Copyright 2000-2001 University of Notre Dame du Lac.
|
|
Copyright 2001-2002 Indiana University.
|
|
Some concepts based on versions from the MTL draft manual and Boost Graph
|
|
and Property Map documentation:
|
|
Copyright (c) Jeremy Siek, Lie-Quan Lee, and Andrew Lumsdaine 2000
|
|
-->
|
|
<param name="Iter" role="iterator-type"/>
|
|
|
|
<use-header name="iterator"/>
|
|
|
|
<models-sentence>The iterator type <arg num="1"/> must be a model of <self/>.</models-sentence>
|
|
|
|
<description>
|
|
<para>A bidirectional iterator is an iterator that can read through a sequence
|
|
of values. It can move in either direction through the sequence, and can
|
|
be either mutable (data pointed to by it can be changed) or not mutable.</para>
|
|
|
|
<para>An iterator represents a position in a sequence. Therefore, the
|
|
iterator can point into the sequence (returning a value when dereferenced
|
|
and being incrementable), or be off-the-end (and not dereferenceable or
|
|
incrementable).</para>
|
|
</description>
|
|
|
|
<associated-type name="value_type">
|
|
<get-member-type name="value_type">
|
|
<apply-template name="std::iterator_traits">
|
|
<type name="Iter"/>
|
|
</apply-template>
|
|
</get-member-type>
|
|
<description><simpara>The value type of the iterator</simpara></description>
|
|
</associated-type>
|
|
|
|
<refines const="no" concept="ForwardIterator"/>
|
|
|
|
<notation variables="i j">
|
|
<sample-value>
|
|
<type name="Iter"/>
|
|
</sample-value>
|
|
</notation>
|
|
|
|
<associated-type name="category">
|
|
<get-member-type name="iterator_category">
|
|
<apply-template name="std::iterator_traits">
|
|
<type name="Iter"/>
|
|
</apply-template>
|
|
</get-member-type>
|
|
<description><simpara>The category of the iterator</simpara></description>
|
|
</associated-type>
|
|
|
|
<notation variables="x">
|
|
<sample-value>
|
|
<type name="value_type"/>
|
|
</sample-value>
|
|
</notation>
|
|
|
|
<valid-type-expression name="Category tag">
|
|
<description/>
|
|
<type name="category"/>
|
|
<return-type>
|
|
<derived-from testable="yes">
|
|
<type name="std::bidirectional_iterator_tag"/>
|
|
</derived-from>
|
|
</return-type>
|
|
</valid-type-expression>
|
|
|
|
<valid-expression name="Predecrement">
|
|
<predecrement>
|
|
<sample-value><reference-to><type name="Iter"/></reference-to></sample-value>
|
|
</predecrement>
|
|
<return-type>
|
|
<require-same-type testable="yes">
|
|
<reference-to><type name="Iter"/></reference-to>
|
|
</require-same-type>
|
|
</return-type>
|
|
<precondition><code>i</code> is incrementable (not
|
|
off-the-end) and some dereferenceable iterator <code>j</code> exists
|
|
such that <code>i == ++j</code></precondition>
|
|
</valid-expression>
|
|
|
|
<valid-expression name="Postdecrement">
|
|
<postdecrement>
|
|
<sample-value><reference-to><type name="Iter"/></reference-to></sample-value>
|
|
</postdecrement>
|
|
<return-type>
|
|
<require-same-type testable="yes"><type name="Iter"/></require-same-type>
|
|
</return-type>
|
|
<precondition>Same as for predecrement</precondition>
|
|
<semantics>Equivalent to <code>{Iter j = i; --i; return j;}</code></semantics>
|
|
<postcondition><code>i</code> is dereferenceable or
|
|
off-the-end</postcondition>
|
|
</valid-expression>
|
|
|
|
<complexity>
|
|
All iterator operations must take amortized constant time.
|
|
</complexity>
|
|
|
|
<invariant name="Predecrement must return object">
|
|
<code>&i = &(--i)</code>
|
|
</invariant>
|
|
|
|
<invariant name="Unique path through sequence">
|
|
<code>i == j</code> implies <code>--i == --j</code>
|
|
</invariant>
|
|
|
|
<invariant name="Increment and decrement are inverses">
|
|
<code>++i; --i;</code> and <code>--i; ++i;</code> must end up with the
|
|
value of <code>i</code> unmodified, if <code>i</code> both of the
|
|
operations in the pair are valid.
|
|
</invariant>
|
|
|
|
<example-model>
|
|
<pointer-to>
|
|
<type name="T"/>
|
|
</pointer-to>
|
|
</example-model>
|
|
|
|
<example-model>
|
|
<get-member-type name="iterator">
|
|
<apply-template name="std::list">
|
|
<type name="T"/>
|
|
</apply-template>
|
|
</get-member-type>
|
|
</example-model>
|
|
|
|
<see-also concept="RandomAccessIterator"/>
|
|
|
|
</concept>
|