doc/reference/RandomAccessIterator.xml

<?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>