Added Caramel/BoostBook concept documentation (finally)

[SVN r21176]

doc/reference/BidirectionalIterator.xml

@@ -0,0 +1,136 @@
+<?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>&amp;i = &amp;(--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>