123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313 |
- <?xml version="1.0"?>
- <concept name="RandomAccessIterator" 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 random access iterator is an iterator that can read through
- a sequence of values. It can move in either direction through the
- sequence (by any amount in constant time), 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="BidirectionalIterator"/>
- <refines const="no" concept="LessThanComparable"/>
- <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>
- <associated-type name="difference_type">
- <get-member-type name="difference_type">
- <apply-template name="std::iterator_traits">
- <type name="Iter"/>
- </apply-template>
- </get-member-type>
- <description><simpara>The difference type of the iterator (measure of the number
- of steps between two iterators)</simpara></description>
- </associated-type>
- <notation variables="x">
- <sample-value>
- <type name="value_type"/>
- </sample-value>
- </notation>
- <notation variables="n">
- <sample-value>
- <type name="difference_type"/>
- </sample-value>
- </notation>
- <notation variables="int_off">
- <sample-value>
- <type name="int"/>
- </sample-value>
- </notation>
- <valid-type-expression name="Category tag">
- <description/>
- <type name="category"/>
- <return-type>
- <derived-from testable="yes">
- <type name="std::random_access_iterator_tag"/>
- </derived-from>
- </return-type>
- </valid-type-expression>
- <valid-expression name="Motion">
- <add-assign>
- <sample-value><reference-to><type name="Iter"/></reference-to></sample-value>
- <sample-value><type name="difference_type"/></sample-value>
- </add-assign>
- <return-type>
- <require-same-type testable="yes">
- <reference-to><type name="Iter"/></reference-to>
- </require-same-type>
- </return-type>
- <semantics>Equivalent to applying <code>i++</code> <code>n</code> times
- if <code>n</code> is positive, applying <code>i--</code>
- <code>-n</code> times if <code>n</code> is negative, and to a null
- operation if <code>n</code> is zero.</semantics>
- </valid-expression>
- <valid-expression name="Motion (with integer offset)">
- <add-assign>
- <sample-value><reference-to><type name="Iter"/></reference-to></sample-value>
- <sample-value><type name="int"/></sample-value>
- </add-assign>
- <return-type>
- <require-same-type testable="yes">
- <reference-to><type name="Iter"/></reference-to>
- </require-same-type>
- </return-type>
- <semantics>Equivalent to applying <code>i++</code> <code>n</code> times
- if <code>n</code> is positive, applying <code>i--</code>
- <code>-n</code> times if <code>n</code> is negative, and to a null
- operation if <code>n</code> is zero.</semantics>
- </valid-expression>
- <valid-expression name="Subtractive motion">
- <subtract-assign>
- <sample-value><reference-to><type name="Iter"/></reference-to></sample-value>
- <sample-value><type name="difference_type"/></sample-value>
- </subtract-assign>
- <return-type>
- <require-same-type testable="yes">
- <reference-to><type name="Iter"/></reference-to>
- </require-same-type>
- </return-type>
- <semantics>Equivalent to <code>i+=(-n)</code></semantics>
- </valid-expression>
- <valid-expression name="Subtractive motion (with integer offset)">
- <subtract-assign>
- <sample-value><reference-to><type name="Iter"/></reference-to></sample-value>
- <sample-value><type name="int"/></sample-value>
- </subtract-assign>
- <return-type>
- <require-same-type testable="yes">
- <reference-to><type name="Iter"/></reference-to>
- </require-same-type>
- </return-type>
- <semantics>Equivalent to <code>i+=(-n)</code></semantics>
- </valid-expression>
- <valid-expression name="Addition">
- <add>
- <sample-value><type name="Iter"/></sample-value>
- <sample-value><type name="difference_type"/></sample-value>
- </add>
- <return-type>
- <require-same-type testable="yes"><type name="Iter"/></require-same-type>
- </return-type>
- <semantics>Equivalent to <code>{Iter j = i; j += n; return j;}</code></semantics>
- </valid-expression>
- <valid-expression name="Addition with integer">
- <add>
- <sample-value><type name="Iter"/></sample-value>
- <sample-value><type name="int"/></sample-value>
- </add>
- <return-type>
- <require-same-type testable="yes"><type name="Iter"/></require-same-type>
- </return-type>
- <semantics>Equivalent to <code>{Iter j = i; j += n; return j;}</code></semantics>
- </valid-expression>
- <valid-expression name="Addition (count first)">
- <add>
- <sample-value><type name="difference_type"/></sample-value>
- <sample-value><type name="Iter"/></sample-value>
- </add>
- <return-type>
- <require-same-type testable="yes"><type name="Iter"/></require-same-type>
- </return-type>
- <semantics>Equivalent to <code>i + n</code></semantics>
- </valid-expression>
- <valid-expression name="Addition with integer (count first)">
- <add>
- <sample-value><type name="int"/></sample-value>
- <sample-value><type name="Iter"/></sample-value>
- </add>
- <return-type>
- <require-same-type testable="yes"><type name="Iter"/></require-same-type>
- </return-type>
- <semantics>Equivalent to <code>i + n</code></semantics>
- </valid-expression>
- <valid-expression name="Subtraction">
- <subtract>
- <sample-value><type name="Iter"/></sample-value>
- <sample-value><type name="difference_type"/></sample-value>
- </subtract>
- <return-type>
- <require-same-type testable="yes"><type name="Iter"/></require-same-type>
- </return-type>
- <semantics>Equivalent to <code>i + (-n)</code></semantics>
- </valid-expression>
- <valid-expression name="Subtraction with integer">
- <subtract>
- <sample-value><type name="Iter"/></sample-value>
- <sample-value><type name="int"/></sample-value>
- </subtract>
- <return-type>
- <require-same-type testable="yes"><type name="Iter"/></require-same-type>
- </return-type>
- <semantics>Equivalent to <code>i + (-n)</code></semantics>
- </valid-expression>
- <valid-expression name="Distance">
- <subtract>
- <sample-value><type name="Iter"/></sample-value>
- <sample-value><type name="Iter"/></sample-value>
- </subtract>
- <return-type>
- <require-same-type testable="yes"><type name="difference_type"/></require-same-type>
- </return-type>
- <semantics>The number of times <code>i</code> must be incremented (or
- decremented if the result is negative) to reach <code>j</code>. Not
- defined if <code>j</code> is not reachable from
- <code>i</code>.</semantics>
- </valid-expression>
- <valid-expression name="Element access">
- <subscript>
- <sample-value><type name="Iter"/></sample-value>
- <sample-value><type name="difference_type"/></sample-value>
- </subscript>
- <return-type>
- <require-same-type testable="yes">
- <const-if-not-mutable>
- <reference-to>
- <type name="value_type"/>
- </reference-to>
- </const-if-not-mutable>
- </require-same-type>
- </return-type>
- <semantics>Equivalent to <code>*(i + n)</code></semantics>
- </valid-expression>
- <valid-expression name="Element access with integer index">
- <subscript>
- <sample-value><type name="Iter"/></sample-value>
- <sample-value><type name="int"/></sample-value>
- </subscript>
- <return-type>
- <require-same-type testable="yes">
- <const-if-not-mutable>
- <reference-to>
- <type name="value_type"/>
- </reference-to>
- </const-if-not-mutable>
- </require-same-type>
- </return-type>
- <semantics>Equivalent to <code>*(i + n)</code></semantics>
- </valid-expression>
- <complexity>
- All iterator operations must take amortized constant time.
- </complexity>
- <example-model>
- <pointer-to>
- <type name="T"/>
- </pointer-to>
- </example-model>
- <example-model>
- <get-member-type name="iterator">
- <apply-template name="std::vector">
- <type name="T"/>
- </apply-template>
- </get-member-type>
- </example-model>
- <example-model>
- <get-member-type name="const_iterator">
- <apply-template name="std::vector">
- <type name="T"/>
- </apply-template>
- </get-member-type>
- </example-model>
- <example-model>
- <get-member-type name="iterator">
- <apply-template name="std::deque">
- <type name="T"/>
- </apply-template>
- </get-member-type>
- </example-model>
- <example-model>
- <get-member-type name="const_iterator">
- <apply-template name="std::deque">
- <type name="T"/>
- </apply-template>
- </get-member-type>
- </example-model>
- </concept>
|