Bring branch up-to-date with trunk

[SVN r21992]
2004-01-27 04:50:52 +00:00
parent 189533437f
commit d15302e683
38 changed files with 8573 additions and 4216 deletions
@@ -7,200 +7,9 @@
 <title>Permutation Iterator</title>
 <meta name="author" content="Toon Knapen, David Abrahams, Roland Richter, Jeremy Siek" />
 <meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab" />
-<meta name="date" content="2003-09-14" />
+<meta name="date" content="2004-01-13" />
 <meta name="copyright" content="Copyright Toon Knapen, David Abrahams, Roland Richter, and Jeremy Siek 2003. All rights reserved" />
-<style type="text/css"><!--
-
-/*
-:Author: David Goodger
-:Contact: goodger@users.sourceforge.net
-:date: $Date$
-:version: $Revision$
-:copyright: This stylesheet has been placed in the public domain.
-
-Default cascading style sheet for the HTML output of Docutils.
-*/
-
-.first {
-  margin-top: 0 }
-
-.last {
-  margin-bottom: 0 }
-
-a.toc-backref {
-  text-decoration: none ;
-  color: black }
-
-dd {
-  margin-bottom: 0.5em }
-
-div.abstract {
-  margin: 2em 5em }
-
-div.abstract p.topic-title {
-  font-weight: bold ;
-  text-align: center }
-
-div.attention, div.caution, div.danger, div.error, div.hint,
-div.important, div.note, div.tip, div.warning {
-  margin: 2em ;
-  border: medium outset ;
-  padding: 1em }
-
-div.attention p.admonition-title, div.caution p.admonition-title,
-div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title {
-  color: red ;
-  font-weight: bold ;
-  font-family: sans-serif }
-
-div.hint p.admonition-title, div.important p.admonition-title,
-div.note p.admonition-title, div.tip p.admonition-title {
-  font-weight: bold ;
-  font-family: sans-serif }
-
-div.dedication {
-  margin: 2em 5em ;
-  text-align: center ;
-  font-style: italic }
-
-div.dedication p.topic-title {
-  font-weight: bold ;
-  font-style: normal }
-
-div.figure {
-  margin-left: 2em }
-
-div.footer, div.header {
-  font-size: smaller }
-
-div.system-messages {
-  margin: 5em }
-
-div.system-messages h1 {
-  color: red }
-
-div.system-message {
-  border: medium outset ;
-  padding: 1em }
-
-div.system-message p.system-message-title {
-  color: red ;
-  font-weight: bold }
-
-div.topic {
-  margin: 2em }
-
-h1.title {
-  text-align: center }
-
-h2.subtitle {
-  text-align: center }
-
-hr {
-  width: 75% }
-
-ol.simple, ul.simple {
-  margin-bottom: 1em }
-
-ol.arabic {
-  list-style: decimal }
-
-ol.loweralpha {
-  list-style: lower-alpha }
-
-ol.upperalpha {
-  list-style: upper-alpha }
-
-ol.lowerroman {
-  list-style: lower-roman }
-
-ol.upperroman {
-  list-style: upper-roman }
-
-p.caption {
-  font-style: italic }
-
-p.credits {
-  font-style: italic ;
-  font-size: smaller }
-
-p.label {
-  white-space: nowrap }
-
-p.topic-title {
-  font-weight: bold }
-
-pre.address {
-  margin-bottom: 0 ;
-  margin-top: 0 ;
-  font-family: serif ;
-  font-size: 100% }
-
-pre.line-block {
-  font-family: serif ;
-  font-size: 100% }
-
-pre.literal-block, pre.doctest-block {
-  margin-left: 2em ;
-  margin-right: 2em ;
-  background-color: #eeeeee }
-
-span.classifier {
-  font-family: sans-serif ;
-  font-style: oblique }
-
-span.classifier-delimiter {
-  font-family: sans-serif ;
-  font-weight: bold }
-
-span.interpreted {
-  font-family: sans-serif }
-
-span.option-argument {
-  font-style: italic }
-
-span.pre {
-  white-space: pre }
-
-span.problematic {
-  color: red }
-
-table {
-  margin-top: 0.5em ;
-  margin-bottom: 0.5em }
-
-table.citation {
-  border-left: solid thin gray ;
-  padding-left: 0.5ex }
-
-table.docinfo {
-  margin: 2em 4em }
-
-table.footnote {
-  border-left: solid thin black ;
-  padding-left: 0.5ex }
-
-td, th {
-  padding-left: 0.5em ;
-  padding-right: 0.5em ;
-  vertical-align: top }
-
-th.docinfo-name, th.field-name {
-  font-weight: bold ;
-  text-align: left ;
-  white-space: nowrap }
-
-h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
-  font-size: 100% }
-
-tt {
-  background-color: #eeeeee }
-
-ul.auto-toc {
-  list-style-type: none }
-
--></style>
+<link rel="stylesheet" href="default.css" type="text/css" />
 </head>
 <body>
 <div class="document" id="permutation-iterator">
@@ -217,7 +26,7 @@ ul.auto-toc {
 <td><a class="first reference" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="last reference" href="http://www.osl.iu.edu">Open Systems
 Lab</a></td></tr>
 <tr><th class="docinfo-name">Date:</th>
-<td>2003-09-14</td></tr>
+<td>2004-01-13</td></tr>
 <tr><th class="docinfo-name">Copyright:</th>
 <td>Copyright Toon Knapen, David Abrahams, Roland Richter, and Jeremy Siek 2003. All rights reserved</td></tr>
 </tbody>
@@ -226,26 +35,27 @@ Lab</a></td></tr>
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">abstract:</th><td class="field-body"></td>
+<tr class="field"><th class="field-name">abstract:</th><td class="field-body">The permutation iterator adaptor provides a permuted view of a given
+range. That is, the view includes every element of the given range but
+in a potentially different order.</td>
 </tr>
 </tbody>
 </table>
-<p>The permutation iterator adaptor provides a permuted view of a given
-range. That is, the view includes every element of the given range but
-in a potentially different order.</p>
 <div class="contents topic" id="table-of-contents">
 <p class="topic-title"><a name="table-of-contents">Table of Contents</a></p>
 <ul class="simple">
-<li><a class="reference" href="#introduction" id="id4" name="id4">Introduction</a></li>
-<li><a class="reference" href="#reference" id="id5" name="id5">Reference</a><ul>
-<li><a class="reference" href="#permutation-iterator-requirements" id="id6" name="id6"><tt class="literal"><span class="pre">permutation_iterator</span></tt> requirements</a></li>
-<li><a class="reference" href="#permutation-iterator-operations" id="id7" name="id7"><tt class="literal"><span class="pre">permutation_iterator</span></tt> operations</a></li>
+<li><a class="reference" href="#introduction" id="id2" name="id2">Introduction</a></li>
+<li><a class="reference" href="#reference" id="id3" name="id3">Reference</a><ul>
+<li><a class="reference" href="#permutation-iterator-requirements" id="id4" name="id4"><tt class="literal"><span class="pre">permutation_iterator</span></tt> requirements</a></li>
+<li><a class="reference" href="#permutation-iterator-models" id="id5" name="id5"><tt class="literal"><span class="pre">permutation_iterator</span></tt> models</a></li>
+<li><a class="reference" href="#permutation-iterator-operations" id="id6" name="id6"><tt class="literal"><span class="pre">permutation_iterator</span></tt> operations</a></li>
 </ul>
 </li>
+<li><a class="reference" href="#example" id="id7" name="id7">Example</a></li>
 </ul>
 </div>
 <div class="section" id="introduction">
-<h1><a class="toc-backref" href="#id4" name="introduction">Introduction</a></h1>
+<h1><a class="toc-backref" href="#id2" name="introduction">Introduction</a></h1>
 <p>The adaptor takes two arguments:</p>
 <blockquote>
 <ul class="simple">
@@ -265,20 +75,16 @@ end permutation iterator is completely defined by means of the
 past-the-end iterator to the indices.</p>
 </div>
 <div class="section" id="reference">
-<h1><a class="toc-backref" href="#id5" name="reference">Reference</a></h1>
+<h1><a class="toc-backref" href="#id3" name="reference">Reference</a></h1>
 <pre class="literal-block">
 template&lt; class ElementIterator
        , class IndexIterator
        , class ValueT        = use_default
-    , unsigned access     = use_default_access
-        , class Traversal     = use_default
+        , class CategoryT     = use_default
        , class ReferenceT    = use_default
        , class DifferenceT   = use_default &gt;
 class permutation_iterator
-  : public iterator_adaptor&lt;...&gt;
 {
-  typedef iterator_adaptor&lt;...&gt;
-  friend class iterator_core_access;
 public:
  permutation_iterator();
  explicit permutation_iterator(ElementIterator x, IndexIterator y);
@@ -289,31 +95,200 @@ public:
      , typename enable_if_convertible&lt;OEIter, ElementIterator&gt;::type* = 0
      , typename enable_if_convertible&lt;OIIter, IndexIterator&gt;::type* = 0
      );
+  reference operator*() const;
+  permutation_iterator&amp; operator++();
+  ElementIterator const&amp; base() const;
+private:
+  ElementIterator m_elt;      // exposition only
+  IndexIterator m_order;      // exposition only
 };
+
+template &lt;class ElementIterator, class IndexIterator&gt;
+permutation_iterator&lt;ElementIterator, IndexIterator&gt; 
+make_permutation_iterator( ElementIterator e, IndexIterator i);
 </pre>
 <div class="section" id="permutation-iterator-requirements">
-<h2><a class="toc-backref" href="#id6" name="permutation-iterator-requirements"><tt class="literal"><span class="pre">permutation_iterator</span></tt> requirements</a></h2>
-<p><tt class="literal"><span class="pre">ElementIterator</span></tt> must be a model of <a class="reference" href="http://www.sgi.com/tech/stl/RandomAccessIterator.html">RandomAccessIterator</a>.
-<tt class="literal"><span class="pre">IndexIterator</span></tt> must at least be a model <a class="reference" href="http://www.sgi.com/tech/stl/ForwardIterator.html">ForwardIterator</a>.  The
-value type of the <tt class="literal"><span class="pre">IndexIterator</span></tt> must be convertible to the
-difference type of <tt class="literal"><span class="pre">ElementIterator</span></tt>.</p>
+<h2><a class="toc-backref" href="#id4" name="permutation-iterator-requirements"><tt class="literal"><span class="pre">permutation_iterator</span></tt> requirements</a></h2>
+<p><tt class="literal"><span class="pre">ElementIterator</span></tt> shall model Random Access Traversal Iterator.
+<tt class="literal"><span class="pre">IndexIterator</span></tt> shall model Readable Iterator.  The value type of
+the <tt class="literal"><span class="pre">IndexIterator</span></tt> must be convertible to the difference type of
+<tt class="literal"><span class="pre">ElementIterator</span></tt>.</p>
+</div>
+<div class="section" id="permutation-iterator-models">
+<h2><a class="toc-backref" href="#id5" name="permutation-iterator-models"><tt class="literal"><span class="pre">permutation_iterator</span></tt> models</a></h2>
+<p><tt class="literal"><span class="pre">permutation_iterator</span></tt> models the same iterator traversal concepts
+as <tt class="literal"><span class="pre">IndexIterator</span></tt> and the same iterator access concepts as
+<tt class="literal"><span class="pre">ElementIterator</span></tt>.</p>
+<p>If <tt class="literal"><span class="pre">IndexIterator</span></tt> models Single Pass Iterator and 
+<tt class="literal"><span class="pre">ElementIterator</span></tt> models Readable Iterator then
+<tt class="literal"><span class="pre">permutation_iterator</span></tt> models Input Iterator.</p>
+<p>If <tt class="literal"><span class="pre">IndexIterator</span></tt> models Forward Traversal Iterator and 
+<tt class="literal"><span class="pre">ElementIterator</span></tt> models Readable Lvalue Iterator then
+<tt class="literal"><span class="pre">permutation_iterator</span></tt> models Forward Iterator.</p>
+<p>If <tt class="literal"><span class="pre">IndexIterator</span></tt> models Bidirectional Traversal Iterator and 
+<tt class="literal"><span class="pre">ElementIterator</span></tt> models Readable Lvalue Iterator then
+<tt class="literal"><span class="pre">permutation_iterator</span></tt> models Bidirectional Iterator.</p>
+<p>If <tt class="literal"><span class="pre">IndexIterator</span></tt> models Random Access Traversal Iterator and
+<tt class="literal"><span class="pre">ElementIterator</span></tt> models Readable Lvalue Iterator then
+<tt class="literal"><span class="pre">permutation_iterator</span></tt> models Random Access Iterator.</p>
+<p><tt class="literal"><span class="pre">permutation_iterator&lt;E1,</span> <span class="pre">X,</span> <span class="pre">V1,</span> <span class="pre">C2,</span> <span class="pre">R1,</span> <span class="pre">D1&gt;</span></tt> is interoperable
+with <tt class="literal"><span class="pre">permutation_iterator&lt;E2,</span> <span class="pre">Y,</span> <span class="pre">V2,</span> <span class="pre">C2,</span> <span class="pre">R2,</span> <span class="pre">D2&gt;</span></tt> if and only if
+<tt class="literal"><span class="pre">X</span></tt> is interoperable with <tt class="literal"><span class="pre">Y</span></tt> and <tt class="literal"><span class="pre">E1</span></tt> is convertible
+to <tt class="literal"><span class="pre">E2</span></tt>.</p>
 </div>
 <div class="section" id="permutation-iterator-operations">
-<h2><a class="toc-backref" href="#id7" name="permutation-iterator-operations"><tt class="literal"><span class="pre">permutation_iterator</span></tt> operations</a></h2>
-<p>The permutation iterator implements the member functions and operators
-required for the <a class="reference" href="http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random Access Iterator</a> concept. However, the
-permutation iterator can only meet the complexity guarantees of the
-same concept as the IndexIterator. Thus for instance, although the
-permutation iterator provides <tt class="literal"><span class="pre">operator+=(distance)</span></tt>, this operation
-will take linear time in case the IndexIterator is a model of
-ForwardIterator instead of amortized constant time.</p>
+<h2><a class="toc-backref" href="#id6" name="permutation-iterator-operations"><tt class="literal"><span class="pre">permutation_iterator</span></tt> operations</a></h2>
+<p>In addition to those operations required by the concepts that
+<tt class="literal"><span class="pre">permutation_iterator</span></tt> models, <tt class="literal"><span class="pre">permutation_iterator</span></tt> provides the
+following operations.</p>
+<p><tt class="literal"><span class="pre">permutation_iterator();</span></tt></p>
+<table class="field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Default constructs <tt class="literal"><span class="pre">m_elt</span></tt> and <tt class="literal"><span class="pre">m_order</span></tt>.</td>
+</tr>
+</tbody>
+</table>
+<p><tt class="literal"><span class="pre">explicit</span> <span class="pre">permutation_iterator(ElementIterator</span> <span class="pre">x,</span> <span class="pre">IndexIterator</span> <span class="pre">y);</span></tt></p>
+<table class="field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs <tt class="literal"><span class="pre">m_elt</span></tt> from <tt class="literal"><span class="pre">x</span></tt> and <tt class="literal"><span class="pre">m_order</span></tt> from <tt class="literal"><span class="pre">y</span></tt>.</td>
+</tr>
+</tbody>
+</table>
+<pre class="literal-block">
+template&lt; class OEIter, class OIIter, class V, class C, class R, class D &gt;
+permutation_iterator(
+    permutation_iterator&lt;OEIter, OIIter, V, C, R, D&gt; const&amp; r
+    , typename enable_if_convertible&lt;OEIter, ElementIterator&gt;::type* = 0
+    , typename enable_if_convertible&lt;OIIter, IndexIterator&gt;::type* = 0
+    );
+</pre>
+<table class="field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs <tt class="literal"><span class="pre">m_elt</span></tt> from <tt class="literal"><span class="pre">r.m_elt</span></tt> and
+<tt class="literal"><span class="pre">m_order</span></tt> from <tt class="literal"><span class="pre">y.m_order</span></tt>.</td>
+</tr>
+</tbody>
+</table>
+<p><tt class="literal"><span class="pre">reference</span> <span class="pre">operator*()</span> <span class="pre">const;</span></tt></p>
+<table class="field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">*(m_elt</span> <span class="pre">+</span> <span class="pre">*m_order)</span></tt></td>
+</tr>
+</tbody>
+</table>
+<p><tt class="literal"><span class="pre">permutation_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
+<table class="field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="literal"><span class="pre">++m_order</span></tt></td>
+</tr>
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">*this</span></tt></td>
+</tr>
+</tbody>
+</table>
+<p><tt class="literal"><span class="pre">ElementIterator</span> <span class="pre">const&amp;</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
+<table class="field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">m_order</span></tt></td>
+</tr>
+</tbody>
+</table>
+<pre class="literal-block">
+template &lt;class ElementIterator, class IndexIterator&gt;
+permutation_iterator&lt;ElementIterator, IndexIterator&gt; 
+make_permutation_iterator(ElementIterator e, IndexIterator i);
+</pre>
+<table class="field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">permutation_iterator&lt;ElementIterator,</span> <span class="pre">IndexIterator&gt;(e,</span> <span class="pre">i)</span></tt></td>
+</tr>
+</tbody>
+</table>
 </div>
 </div>
+<div class="section" id="example">
+<h1><a class="toc-backref" href="#id7" name="example">Example</a></h1>
+<pre class="literal-block">
+using namespace boost;
+int i = 0;
+
+typedef std::vector&lt; int &gt; element_range_type;
+typedef std::list&lt; int &gt; index_type;
+
+static const int element_range_size = 10;
+static const int index_size = 4;
+
+element_range_type elements( element_range_size );
+for(element_range_type::iterator el_it = elements.begin() ; el_it != elements.end() ; ++el_it)
+  *el_it = std::distance(elements.begin(), el_it);
+
+index_type indices( index_size );
+for(index_type::iterator i_it = indices.begin() ; i_it != indices.end() ; ++i_it ) 
+  *i_it = element_range_size - index_size + std::distance(indices.begin(), i_it);
+std::reverse( indices.begin(), indices.end() );
+
+typedef permutation_iterator&lt; element_range_type::iterator, index_type::iterator &gt; permutation_type;
+permutation_type begin = make_permutation_iterator( elements.begin(), indices.begin() );
+permutation_type it = begin;
+permutation_type end = make_permutation_iterator( elements.begin(), indices.end() );
+
+std::cout &lt;&lt; &quot;The original range is : &quot;;
+std::copy( elements.begin(), elements.end(), std::ostream_iterator&lt; int &gt;( std::cout, &quot; &quot; ) );
+std::cout &lt;&lt; &quot;\n&quot;;
+
+std::cout &lt;&lt; &quot;The reindexing scheme is : &quot;;
+std::copy( indices.begin(), indices.end(), std::ostream_iterator&lt; int &gt;( std::cout, &quot; &quot; ) );
+std::cout &lt;&lt; &quot;\n&quot;;
+
+std::cout &lt;&lt; &quot;The permutated range is : &quot;;
+std::copy( begin, end, std::ostream_iterator&lt; int &gt;( std::cout, &quot; &quot; ) );
+std::cout &lt;&lt; &quot;\n&quot;;
+
+std::cout &lt;&lt; &quot;Elements at even indices in the permutation : &quot;;
+it = begin;
+for(i = 0; i &lt; index_size / 2 ; ++i, it+=2 ) std::cout &lt;&lt; *it &lt;&lt; &quot; &quot;;
+std::cout &lt;&lt; &quot;\n&quot;;
+
+std::cout &lt;&lt; &quot;Permutation backwards : &quot;;
+it = begin + (index_size);
+assert( it != begin );
+for( ; it-- != begin ; ) std::cout &lt;&lt; *it &lt;&lt; &quot; &quot;;
+std::cout &lt;&lt; &quot;\n&quot;;
+
+std::cout &lt;&lt; &quot;Iterate backward with stride 2 : &quot;;
+it = begin + (index_size - 1);
+for(i = 0 ; i &lt; index_size / 2 ; ++i, it-=2 ) std::cout &lt;&lt; *it &lt;&lt; &quot; &quot;;
+std::cout &lt;&lt; &quot;\n&quot;;
+</pre>
+<p>The output is:</p>
+<pre class="literal-block">
+The original range is : 0 1 2 3 4 5 6 7 8 9 
+The reindexing scheme is : 9 8 7 6 
+The permutated range is : 9 8 7 6 
+Elements at even indices in the permutation : 9 7 
+Permutation backwards : 6 7 8 9 
+Iterate backward with stride 2 : 6 8 
+</pre>
+<p>The source code for this example can be found <a class="reference" href="../example/permutation_iterator_example.cpp">here</a>.</p>
+</div>
 </div>
 <hr class="footer" />
 <div class="footer">
 <a class="reference" href="permutation_iterator.rst">View document source</a>.
-Generated on: 2003-11-24 05:00 UTC.
 Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
 </div>
 </body>