Fixed base() to always return const&. Cleaned up iterator_adaptor

specification of inheritance and base class parameters.


[SVN r21821]

doc/counting_iterator.html

@@ -81,7 +81,7 @@ class counting_iterator
     counting_iterator();
     counting_iterator(counting_iterator const& rhs);
     explicit counting_iterator(Incrementable x);
-    Incrementable base() const;
+    Incrementable const& base() const;
     reference operator*() const;
     counting_iterator& operator++();
     counting_iterator& operator--();
@@ -105,9 +105,12 @@ else
          iterator_traversal<Incrementable>::type, 
          Incrementable, const Incrementable&)
 </pre>
-<p>[<em>Note:</em> implementers are encouraged to provide an implementation
+<dl>
-of <tt class="literal"><span class="pre">operator-</span></tt> and a default <tt class="literal"><span class="pre">difference_type</span></tt> that avoid
+<dt>[<em>Note:</em> implementers are encouraged to provide an implementation of</dt>
-overflows when <tt class="literal"><span class="pre">Incrementable</span></tt> is a numeric type.]</p>
+<dd><tt class="literal"><span class="pre">operator-</span></tt> and a <tt class="literal"><span class="pre">difference_type</span></tt> that avoids overflows in
+the cases where <tt class="literal"><span class="pre">std::numeric_limits&lt;Incrementable&gt;::is_specialized</span></tt>
+is true.]</dd>
+</dl>
 </div>
 <div class="section" id="counting-iterator-requirements">
 <h1><a class="toc-backref" href="#id3" name="counting-iterator-requirements"><tt class="literal"><span class="pre">counting_iterator</span></tt> requirements</a></h1>
@@ -216,7 +219,7 @@ operations.</p>
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">Incrementable</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
+<p><tt class="literal"><span class="pre">Incrementable</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" />

doc/counting_iterator_ref.rst

@@ -17,7 +17,7 @@
       counting_iterator();
       counting_iterator(counting_iterator const& rhs);
       explicit counting_iterator(Incrementable x);
-      Incrementable base() const;
+      Incrementable const& base() const;
       reference operator*() const;
       counting_iterator& operator++();
       counting_iterator& operator--();
@@ -140,6 +140,6 @@ operations.
 :Returns: ``*this``  
 
 
-``Incrementable base() const;``
+``Incrementable const& base() const;``
 
 :Returns: ``m_inc``

doc/facade-and-adaptor.html

@@ -1158,13 +1158,13 @@ template <
   , class Difference = use_default
 >
 class iterator_adaptor 
-  : public iterator_facade&lt;Derived, <em>V</em>, <em>C</em>, <em>R</em>, <em>D</em>&gt; // see <a class="reference" href="#requirements">details</a>
+  : public iterator_facade&lt;Derived, <em>V'</em>, <em>C'</em>, <em>R'</em>, <em>D'</em>&gt; // see <a class="reference" href="#base-parameters">details</a>
 {
     friend class iterator_core_access;
  public:
     iterator_adaptor();
     explicit iterator_adaptor(Base iter);
-    Base const base() const;
+    Base const const&amp; base() const;
  protected:
     Base const&amp; base_reference() const;
     Base&amp; base_reference();
@@ -1193,27 +1193,27 @@ class iterator_adaptor
 <a class="target" id="requirements" name="requirements"></a></div>
 <div class="section" id="iterator-adaptor-requirements">
 <h3><a class="toc-backref" href="#id36" name="iterator-adaptor-requirements"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> requirements</a></h3>
-<p>The <tt class="literal"><span class="pre">Derived</span></tt> template argument must be a publicly derived from
+<p>The <tt class="literal"><span class="pre">Base</span></tt> argument shall be Assignable and Copy
-<tt class="literal"><span class="pre">iterator_adaptor</span></tt>.</p>
+Constructible. In addition,
-<p>The <tt class="literal"><span class="pre">Base</span></tt> argument shall be Assignable and Copy Constructible.</p>
+<tt class="literal"><span class="pre">static_cast&lt;Derived*&gt;(iterator_adaptor*)</span></tt> shall be well-formed.</p>
 <a class="target" id="base-parameters" name="base-parameters"></a></div>
 <div class="section" id="iterator-adaptor-base-class-parameters">
 <h3><a class="toc-backref" href="#id37" name="iterator-adaptor-base-class-parameters"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> base class parameters</a></h3>
-<p>The <em>V</em>, <em>C</em>, <em>R</em>, and <em>D</em> parameters of the <tt class="literal"><span class="pre">iterator_facade</span></tt>
+<p>The <em>V'</em>, <em>C'</em>, <em>R'</em>, and <em>D'</em> parameters of the <tt class="literal"><span class="pre">iterator_facade</span></tt>
 used as a base class in the summary of <tt class="literal"><span class="pre">iterator_adaptor</span></tt>
 above are defined as follows:</p>
 <pre class="literal-block">
-<em>V</em> = if (Value is use_default)
+<em>V'</em> = if (Value is use_default)
           return iterator_traits&lt;Base&gt;::value_type
       else
           return Value
 
-<em>C</em> = if (CategoryOrTraversal is use_default)
+<em>C'</em> = if (CategoryOrTraversal is use_default)
           return iterator_traversal&lt;Base&gt;::type
       else
           return CategoryOrTraversal
 
-<em>R</em> = if (Reference is use_default)
+<em>R'</em> = if (Reference is use_default)
           if (Value is use_default)
               return iterator_traits&lt;Base&gt;::reference
           else
@@ -1221,7 +1221,7 @@ above are defined as follows:</p>
       else
           return Reference
 
-<em>D</em> = if (Difference is use_default)
+<em>D'</em> = if (Difference is use_default)
           return iterator_traits&lt;Base&gt;::difference_type
       else
           return Difference
@@ -1261,7 +1261,7 @@ expression involving <tt class="literal"><span class="pre">Derived</span></tt> i
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">Base</span> <span class="pre">const</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
+<p><tt class="literal"><span class="pre">Base</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" />
@@ -1270,10 +1270,6 @@ expression involving <tt class="literal"><span class="pre">Derived</span></tt> i
 </tr>
 </tbody>
 </table>
-<p>[Note: specifying <tt class="literal"><span class="pre">Base</span> <span class="pre">const</span></tt> gives implementations license to
-return <tt class="literal"><span class="pre">Base</span> <span class="pre">const&amp;</span></tt> for efficiency's sake.  If <tt class="literal"><span class="pre">base()</span></tt>
-returned just <tt class="literal"><span class="pre">Base</span></tt>, it would be possible to call non-<tt class="literal"><span class="pre">const</span></tt>
-member functions on the result object directly]</p>
 </div>
 <div class="section" id="iterator-adaptor-protected-member-functions">
 <h3><a class="toc-backref" href="#id40" name="iterator-adaptor-protected-member-functions"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> protected member functions</a></h3>
@@ -1516,7 +1512,7 @@ class indirect_iterator
       , typename enable_if_convertible&lt;Iterator2, Iterator&gt;::type* = 0 // exposition
     );
 
-    Iterator base() const;
+    Iterator const&amp; base() const;
     reference operator*() const;
     indirect_iterator&amp; operator++();
     indirect_iterator&amp; operator--();
@@ -1552,11 +1548,11 @@ else
     typedef Difference difference_type;
 
 if (CategoryOrTraversal is use_default)
-    typedef <a class="reference" href="#id12"><em>iterator-category</em></a>(
+    typedef <em>iterator-category</em> (
         iterator_traversal&lt;Iterator&gt;::type,``reference``,``value_type``
     ) iterator_category;
 else
-    typedef <a class="reference" href="#id12"><em>iterator-category</em></a>(
+    typedef <em>iterator-category</em> (
         CategoryOrTraversal,``reference``,``value_type``
     ) iterator_category;
 </pre>
@@ -1646,7 +1642,7 @@ indirect_iterator(
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">Iterator</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
+<p><tt class="literal"><span class="pre">Iterator</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" />
@@ -1713,7 +1709,7 @@ public:
       reverse_iterator&lt;OtherIterator&gt; const&amp; r
     , typename enable_if_convertible&lt;OtherIterator, Iterator&gt;::type* = 0 // exposition
   );
-  Iterator base() const;
+  Iterator const&amp; base() const;
   reference operator*() const;
   reverse_iterator&amp; operator++();
   reverse_iterator&amp; operator--();
@@ -1816,7 +1812,7 @@ reverse_iterator(
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">Iterator</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
+<p><tt class="literal"><span class="pre">Iterator</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" />
@@ -1893,8 +1889,8 @@ public:
       , typename enable_if_convertible&lt;I2, Iterator&gt;::type* = 0      // exposition only
       , typename enable_if_convertible&lt;F2, UnaryFunction&gt;::type* = 0 // exposition only
   );
-  Iterator base() const;
   UnaryFunction functor() const;
+  Iterator const&amp; base() const;
   reference operator*() const;
   transform_iterator&amp; operator++();
   transform_iterator&amp; operator--();
@@ -1932,7 +1928,7 @@ where the type of <tt class="literal"><span class="pre">f(*i)</span></tt> must b
 <div class="section" id="transform-iterator-models">
 <h4><a class="toc-backref" href="#id58" name="transform-iterator-models"><tt class="literal"><span class="pre">transform_iterator</span></tt> models</a></h4>
 <p>The resulting <tt class="literal"><span class="pre">transform_iterator</span></tt> models the most refined of the
-following options that is also modeled by <tt class="literal"><span class="pre">Iterator</span></tt>.</p>
+following that is also modeled by <tt class="literal"><span class="pre">Iterator</span></tt>.</p>
 <blockquote>
 <ul class="simple">
 <li>Writable Lvalue Iterator if <tt class="literal"><span class="pre">transform_iterator::reference</span></tt> is a non-const reference.</li>
@@ -2018,15 +2014,6 @@ transform_iterator(
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">Iterator</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_iterator</span></tt></td>
-</tr>
-</tbody>
-</table>
 <p><tt class="literal"><span class="pre">UnaryFunction</span> <span class="pre">functor()</span> <span class="pre">const;</span></tt></p>
 <table class="field-list" frame="void" rules="none">
 <col class="field-name" />
@@ -2036,6 +2023,15 @@ transform_iterator(
 </tr>
 </tbody>
 </table>
+<p><tt class="literal"><span class="pre">Iterator</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_iterator</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" />
@@ -2108,7 +2104,7 @@ class filter_iterator
         );
     Predicate predicate() const;
     Iterator end() const;
-    Iterator base() const;
+    Iterator const&amp; base() const;
     reference operator*() const;
     filter_iterator&amp; operator++();
 private:
@@ -2282,7 +2278,7 @@ filter_iterator(
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">Iterator</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
+<p><tt class="literal"><span class="pre">Iterator</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" />
@@ -2340,7 +2336,7 @@ class counting_iterator
     counting_iterator();
     counting_iterator(counting_iterator const&amp; rhs);
     explicit counting_iterator(Incrementable x);
-    Incrementable base() const;
+    Incrementable const&amp; base() const;
     reference operator*() const;
     counting_iterator&amp; operator++();
     counting_iterator&amp; operator--();
@@ -2364,9 +2360,12 @@ else
          iterator_traversal&lt;Incrementable&gt;::type, 
          Incrementable, const Incrementable&amp;)
 </pre>
-<p>[<em>Note:</em> implementers are encouraged to provide an implementation
+<dl>
-of <tt class="literal"><span class="pre">operator-</span></tt> and a default <tt class="literal"><span class="pre">difference_type</span></tt> that avoid
+<dt>[<em>Note:</em> implementers are encouraged to provide an implementation of</dt>
-overflows when <tt class="literal"><span class="pre">Incrementable</span></tt> is a numeric type.]</p>
+<dd><tt class="literal"><span class="pre">operator-</span></tt> and a <tt class="literal"><span class="pre">difference_type</span></tt> that avoids overflows in
+the cases where <tt class="literal"><span class="pre">std::numeric_limits&lt;Incrementable&gt;::is_specialized</span></tt>
+is true.]</dd>
+</dl>
 </div>
 <div class="section" id="counting-iterator-requirements">
 <h4><a class="toc-backref" href="#id67" name="counting-iterator-requirements"><tt class="literal"><span class="pre">counting_iterator</span></tt> requirements</a></h4>
@@ -2475,7 +2474,7 @@ operations.</p>
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">Incrementable</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
+<p><tt class="literal"><span class="pre">Incrementable</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" />

doc/filter_iterator.html

@@ -86,7 +86,7 @@ class filter_iterator
         );
     Predicate predicate() const;
     Iterator end() const;
-    Iterator base() const;
+    Iterator const& base() const;
     reference operator*() const;
     filter_iterator& operator++();
 private:
@@ -260,7 +260,7 @@ filter_iterator(
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">Iterator</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
+<p><tt class="literal"><span class="pre">Iterator</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" />

doc/filter_iterator_ref.rst

@@ -25,7 +25,7 @@
           );
       Predicate predicate() const;
       Iterator end() const;
-      Iterator base() const;
+      Iterator const& base() const;
       reference operator*() const;
       filter_iterator& operator++();
   private:
@@ -151,7 +151,7 @@ operations.
 :Returns: ``m_end``
 
 
-``Iterator base() const;``
+``Iterator const& base() const;``
 
 :Returns: ``m_iterator``
 

doc/index.html

@@ -17,11 +17,10 @@
 <tbody valign="top">
 <tr class="field"><th class="field-name">Authors:</th><td class="field-body">David Abrahams, Jeremy Siek, Thomas Witt</td>
 </tr>
-<tr class="field"><th class="field-name">Contact:</th><td class="field-body"><a class="reference" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="reference" href="mailto:witt&#64;ive.uni-hannover.de">witt&#64;ive.uni-hannover.de</a></td>
+<tr class="field"><th class="field-name">Contact:</th><td class="field-body"><a class="reference" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="reference" href="mailto:witt&#64;styleadvisor.com">witt&#64;styleadvisor.com</a></td>
 </tr>
 <tr class="field"><th class="field-name">organizations:</th><td class="field-body"><a class="reference" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference" href="http://www.osl.iu.edu">Open Systems
-Lab</a>, University of Hanover <a class="reference" href="http://www.ive.uni-hannover.de">Institute for Transport
+Lab</a>, <a class="reference" href="http://www.styleadvisor.com">Zephyr Associates, Inc.</a></td>
-Railway Operation and Construction</a></td>
 </tr>
 <tr class="field"><th class="field-name">date:</th><td class="field-body">$Date$</td>
 </tr>
@@ -92,7 +91,7 @@ concepts, see our</p>
 up often.  In order to ease the implementation of new iterators,
 the Boost.Iterator library provides the <tt class="literal"><span class="pre">iterator_facade</span></tt> class template,
 which implements many useful defaults and compile-time checks
-designed to help the author iterator ensure that his iterator is
+designed to help the iterator author ensure that his iterator is
 correct.</p>
 <p>It is also common to define a new iterator that is similar to some
 underlying iterator or iterator-like type, but that modifies some

doc/indirect_iterator.html

@@ -90,7 +90,7 @@ class indirect_iterator
       , typename enable_if_convertible<Iterator2, Iterator>::type* = 0 // exposition
     );
 
-    Iterator base() const;
+    Iterator const& base() const;
     reference operator*() const;
     indirect_iterator& operator++();
     indirect_iterator& operator--();
@@ -126,11 +126,11 @@ else
     typedef Difference difference_type;
 
 if (CategoryOrTraversal is use_default)
-    typedef <a class="reference" href="iterator_facade.html#iterator-category"><em>iterator-category</em></a>(
+    typedef <em>iterator-category</em> (
         iterator_traversal&lt;Iterator&gt;::type,``reference``,``value_type``
     ) iterator_category;
 else
-    typedef <a class="reference" href="iterator_facade.html#iterator-category"><em>iterator-category</em></a>(
+    typedef <em>iterator-category</em> (
         CategoryOrTraversal,``reference``,``value_type``
     ) iterator_category;
 </pre>
@@ -220,7 +220,7 @@ indirect_iterator(
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">Iterator</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
+<p><tt class="literal"><span class="pre">Iterator</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" />

doc/indirect_iterator_ref.diff

@@ -63,7 +63,7 @@ Issue 9.37x
 -          return **this->base();
 -      }
 +
-+      Iterator base() const;
++      Iterator const& base() const;
 +      reference operator*() const;
 +      indirect_iterator& operator++();
 +      indirect_iterator& operator--();
@@ -223,7 +223,7 @@ Issue 9.29
 
 Issue 9.37x
 
-+``Iterator base() const;``
++``Iterator const& base() const;``
  
 +:Returns: ``m_iterator``
 +

doc/indirect_iterator_ref.rst

@@ -30,7 +30,7 @@
         , typename enable_if_convertible<Iterator2, Iterator>::type* = 0 // exposition
       );
 
-      Iterator base() const;
+      Iterator const& base() const;
       reference operator*() const;
       indirect_iterator& operator++();
       indirect_iterator& operator--();
@@ -155,7 +155,7 @@ following operations.
     ``m_iterator`` subobject is constructed from ``y.base()``.
 
 
-``Iterator base() const;``
+``Iterator const& base() const;``
 
 :Returns: ``m_iterator``
 

doc/iter-issue-list.rst

@@ -996,7 +996,7 @@ provide rather than how they're implemented.
 
   to::
 
-        Iterator base() const;
+        Iterator const& base() const;
         reference operator*() const;
         indirect_iterator& operator++();
         indirect_iterator& operator--();
@@ -1068,7 +1068,7 @@ provide rather than how they're implemented.
 
   After ``UnaryFunction functor() const;`` add::
 
-     Iterator base() const;
+     Iterator const& base() const;
      reference operator*() const;
      transform_iterator& operator++();
      transform_iterator& operator--();
@@ -1173,7 +1173,7 @@ provide rather than how they're implemented.
 
   After the entry for ``functor()``, add::
 
-    ``Iterator base() const;``
+    ``Iterator const& base() const;``
     
     :Returns: ``m_iterator``
     
@@ -1447,4 +1447,6 @@ specification
 
    :Proposed resolution: add "from" before "making"
 
+9.46y N1530: ``base()``
+=====================================================
 

doc/iterator_adaptor.html

@@ -127,13 +127,13 @@ template <
   , class Difference = use_default
 >
 class iterator_adaptor 
-  : public iterator_facade&lt;Derived, <em>V</em>, <em>C</em>, <em>R</em>, <em>D</em>&gt; // see <a class="reference" href="#requirements">details</a>
+  : public iterator_facade&lt;Derived, <em>V'</em>, <em>C'</em>, <em>R'</em>, <em>D'</em>&gt; // see <a class="reference" href="#base-parameters">details</a>
 {
     friend class iterator_core_access;
  public:
     iterator_adaptor();
     explicit iterator_adaptor(Base iter);
-    Base const base() const;
+    Base const const&amp; base() const;
  protected:
     Base const&amp; base_reference() const;
     Base&amp; base_reference();
@@ -161,27 +161,27 @@ class iterator_adaptor
 </pre>
 <a class="target" id="requirements" name="requirements"></a><div class="section" id="iterator-adaptor-requirements">
 <h2><a class="toc-backref" href="#id8" name="iterator-adaptor-requirements"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> requirements</a></h2>
-<p>The <tt class="literal"><span class="pre">Derived</span></tt> template argument must be a publicly derived from
+<p>The <tt class="literal"><span class="pre">Base</span></tt> argument shall be Assignable and Copy
-<tt class="literal"><span class="pre">iterator_adaptor</span></tt>.</p>
+Constructible. In addition,
-<p>The <tt class="literal"><span class="pre">Base</span></tt> argument shall be Assignable and Copy Constructible.</p>
+<tt class="literal"><span class="pre">static_cast&lt;Derived*&gt;(iterator_adaptor*)</span></tt> shall be well-formed.</p>
 <a class="target" id="base-parameters" name="base-parameters"></a></div>
 <div class="section" id="iterator-adaptor-base-class-parameters">
 <h2><a class="toc-backref" href="#id9" name="iterator-adaptor-base-class-parameters"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> base class parameters</a></h2>
-<p>The <em>V</em>, <em>C</em>, <em>R</em>, and <em>D</em> parameters of the <tt class="literal"><span class="pre">iterator_facade</span></tt>
+<p>The <em>V'</em>, <em>C'</em>, <em>R'</em>, and <em>D'</em> parameters of the <tt class="literal"><span class="pre">iterator_facade</span></tt>
 used as a base class in the summary of <tt class="literal"><span class="pre">iterator_adaptor</span></tt>
 above are defined as follows:</p>
 <pre class="literal-block">
-<em>V</em> = if (Value is use_default)
+<em>V'</em> = if (Value is use_default)
           return iterator_traits&lt;Base&gt;::value_type
       else
           return Value
 
-<em>C</em> = if (CategoryOrTraversal is use_default)
+<em>C'</em> = if (CategoryOrTraversal is use_default)
           return iterator_traversal&lt;Base&gt;::type
       else
           return CategoryOrTraversal
 
-<em>R</em> = if (Reference is use_default)
+<em>R'</em> = if (Reference is use_default)
           if (Value is use_default)
               return iterator_traits&lt;Base&gt;::reference
           else
@@ -189,7 +189,7 @@ above are defined as follows:</p>
       else
           return Reference
 
-<em>D</em> = if (Difference is use_default)
+<em>D'</em> = if (Difference is use_default)
           return iterator_traits&lt;Base&gt;::difference_type
       else
           return Difference
@@ -229,7 +229,7 @@ expression involving <tt class="literal"><span class="pre">Derived</span></tt> i
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">Base</span> <span class="pre">const</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
+<p><tt class="literal"><span class="pre">Base</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" />
@@ -238,10 +238,6 @@ expression involving <tt class="literal"><span class="pre">Derived</span></tt> i
 </tr>
 </tbody>
 </table>
-<p>[Note: specifying <tt class="literal"><span class="pre">Base</span> <span class="pre">const</span></tt> gives implementations license to
-return <tt class="literal"><span class="pre">Base</span> <span class="pre">const&amp;</span></tt> for efficiency's sake.  If <tt class="literal"><span class="pre">base()</span></tt>
-returned just <tt class="literal"><span class="pre">Base</span></tt>, it would be possible to call non-<tt class="literal"><span class="pre">const</span></tt>
-member functions on the result object directly]</p>
 </div>
 <div class="section" id="iterator-adaptor-protected-member-functions">
 <h2><a class="toc-backref" href="#id12" name="iterator-adaptor-protected-member-functions"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> protected member functions</a></h2>

doc/iterator_adaptor_ref.rst

@@ -15,13 +15,13 @@
     , class Difference = use_default
   >
   class iterator_adaptor 
-    : public iterator_facade<Derived, *V*, *C*, *R*, *D*> // see details__
+    : public iterator_facade<Derived, *V'*, *C'*, *R'*, *D'*> // see details__
   {
       friend class iterator_core_access;
    public:
       iterator_adaptor();
       explicit iterator_adaptor(Base iter);
-      Base const base() const;
+      Base const const& base() const;
    protected:
       Base const& base_reference() const;
       Base& base_reference();
@@ -47,18 +47,16 @@
       Base m_iterator; // exposition only
   };
 
-
+__ base_parameters_
-__ requirements_
 
 .. _requirements:
 
 ``iterator_adaptor`` requirements
 ---------------------------------
 
-The ``Derived`` template argument must be a publicly derived from
+The ``Base`` argument shall be Assignable and Copy
-``iterator_adaptor``.
+Constructible. In addition,
-
+``static_cast<Derived*>(iterator_adaptor*)`` shall be well-formed.
-The ``Base`` argument shall be Assignable and Copy Constructible.
 
 
 .. _base_parameters:
@@ -66,23 +64,23 @@ The ``Base`` argument shall be Assignable and Copy Constructible.
 ``iterator_adaptor`` base class parameters
 ------------------------------------------
 
-The *V*, *C*, *R*, and *D* parameters of the ``iterator_facade``
+The *V'*, *C'*, *R'*, and *D'* parameters of the ``iterator_facade``
 used as a base class in the summary of ``iterator_adaptor``
 above are defined as follows:
 
 .. parsed-literal::
 
-   *V* = if (Value is use_default)
+   *V'* = if (Value is use_default)
              return iterator_traits<Base>::value_type
          else
              return Value
 
-   *C* = if (CategoryOrTraversal is use_default)
+   *C'* = if (CategoryOrTraversal is use_default)
              return iterator_traversal<Base>::type
          else
              return CategoryOrTraversal
 
-   *R* = if (Reference is use_default)
+   *R'* = if (Reference is use_default)
              if (Value is use_default)
                  return iterator_traits<Base>::reference
              else
@@ -90,7 +88,7 @@ above are defined as follows:
          else
              return Reference
 
-   *D* = if (Difference is use_default)
+   *D'* = if (Difference is use_default)
              return iterator_traits<Base>::difference_type
          else
              return Difference
@@ -122,15 +120,10 @@ expression involving ``Derived`` in those concepts' requirements.
 :Returns: An instance of ``iterator_adaptor`` with
     ``m_iterator`` copy constructed from ``iter``.
 
-``Base const base() const;``
+``Base const& base() const;``
 
 :Returns: ``m_iterator``
 
-[Note: specifying ``Base const`` gives implementations license to
-return ``Base const&`` for efficiency's sake.  If ``base()``
-returned just ``Base``, it would be possible to call non-``const``
-member functions on the result object directly]
-
 ``iterator_adaptor`` protected member functions
 -----------------------------------------------
 

doc/iterator_facade.html

@@ -408,7 +408,7 @@ traversal tags would add no information]</p>
 <!-- subject to the Boost Software License, Version 1.0. (See accompanying -->
 <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
 <p>The <tt class="literal"><span class="pre">enable_if_interoperable</span></tt> template used above is for exposition
-purposes.  The member operators should be only be in an overload set
+purposes.  The member operators should only be in an overload set
 provided the derived types <tt class="literal"><span class="pre">Dr1</span></tt> and <tt class="literal"><span class="pre">Dr2</span></tt> are interoperable, 
 meaning that at least one of the types is convertible to the other.  The
 <tt class="literal"><span class="pre">enable_if_interoperable</span></tt> approach uses SFINAE to take the operators
@@ -785,7 +785,7 @@ operator -(iterator_facade&lt;Dr1,V1,TC1,R1,D1&gt; const&amp; lhs,
 </tr>
 <tr class="field"><th class="field-name">Returns:</th><td class="field-body">if <tt class="literal"><span class="pre">is_convertible&lt;Dr2,Dr1&gt;::value</span></tt>, then
 <tt class="literal"><span class="pre">-lhs.distance_to(rhs)</span></tt>. Otherwise,
-<tt class="literal"><span class="pre">-rhs.distance_to(lhs)</span></tt>.</td>
+<tt class="literal"><span class="pre">rhs.distance_to(lhs)</span></tt>.</td>
 </tr>
 </tbody>
 </table>

doc/new-iter-concepts.html

@@ -6,8 +6,8 @@
 <meta name="generator" content="Docutils 0.3.1: http://docutils.sourceforge.net/" />
 <title>New Iterator Concepts</title>
 <meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />
-<meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction" />
+<meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, Zephyr Associates, Inc." />
-<meta name="date" content="2004-01-15" />
+<meta name="date" content="2004-01-18" />
 <meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved" />
 <link rel="stylesheet" href="default.css" type="text/css" />
 </head>
@@ -21,13 +21,12 @@
 <tr><th class="docinfo-name">Author:</th>
 <td>David Abrahams, Jeremy Siek, Thomas Witt</td></tr>
 <tr><th class="docinfo-name">Contact:</th>
-<td><a class="first reference" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference" href="mailto:witt&#64;acm.org">witt&#64;acm.org</a></td></tr>
+<td><a class="first reference" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference" href="mailto:witt&#64;styleadvisor.com">witt&#64;styleadvisor.com</a></td></tr>
 <tr><th class="docinfo-name">Organization:</th>
-<td><a class="first reference" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference" href="http://www.osl.iu.edu">Open
+<td><a class="first reference" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference" href="http://www.osl.iu.edu">Open Systems
-Systems Lab</a>, University of Hanover <a class="last reference" href="http://www.ive.uni-hannover.de">Institute for
+Lab</a>, <a class="last reference" href="http://www.styleadvisor.com">Zephyr Associates, Inc.</a></td></tr>
-Transport Railway Operation and Construction</a></td></tr>
 <tr><th class="docinfo-name">Date:</th>
-<td>2004-01-15</td></tr>
+<td>2004-01-18</td></tr>
 <tr class="field"><th class="docinfo-name">Number:</th><td class="field-body">This is a revised version of <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1550.html">n1550</a>=03-0133, which was
 accepted for Technical Report 1 by the C++ standard
 committee's library working group. This proposal is a
@@ -190,11 +189,6 @@ made it). -DWA -->
 standards conforming input iterator is allowed to have
 a tag that is not input_iterator_tag but that
 is convertible to input_iterator_tag? -JGS -->
-<p>Note that as currently specified, <tt class="literal"><span class="pre">istreambuf_iterator</span></tt> doesn't
-meet the Readable Iterator requirements because its <tt class="literal"><span class="pre">value_type</span></tt>
-is not convertible to its <tt class="literal"><span class="pre">reference</span></tt> type.  We believe this to
-be a defect in the standard; it should be fixed by changing its
-<tt class="literal"><span class="pre">reference</span></tt> type from <tt class="literal"><span class="pre">value_type&amp;</span></tt> to <tt class="literal"><span class="pre">value_type</span> <span class="pre">const&amp;</span></tt>.</p>
 <div class="section" id="possible-but-not-proposed-changes-to-the-working-paper">
 <h2><a class="toc-backref" href="#id3" name="possible-but-not-proposed-changes-to-the-working-paper">Possible (but not proposed) Changes to the Working Paper</a></h2>
 <p>The extensions in this paper suggest several changes we might make

doc/permutation_iterator.html

@@ -97,9 +97,9 @@ public:
       );
   reference operator*() const;
   permutation_iterator& operator++();
-  ElementIterator base() const;
+  ElementIterator const& base() const;
 private:
-  ElementIterator m_iterator; // exposition only
+  ElementIterator m_elt;      // exposition only
   IndexIterator m_order;      // exposition only
 };
 
@@ -131,9 +131,10 @@ as <tt class="literal"><span class="pre">IndexIterator</span></tt> and the same
 <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;X,</span> <span class="pre">I1,</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
+<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;Y,</span> <span class="pre">I2,</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
+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>.</p>
+<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="#id6" name="permutation-iterator-operations"><tt class="literal"><span class="pre">permutation_iterator</span></tt> operations</a></h2>
@@ -145,7 +146,7 @@ following operations.</p>
 <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_iterator</span></tt> and <tt class="literal"><span class="pre">m_order</span></tt>.</td>
+<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>
@@ -154,7 +155,7 @@ following operations.</p>
 <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_iterator</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 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>
@@ -170,7 +171,7 @@ permutation_iterator(
 <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_iterator</span></tt> from <tt class="literal"><span class="pre">r.m_iterator</span></tt> and
+<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>
@@ -180,7 +181,7 @@ permutation_iterator(
 <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_iterator</span> <span class="pre">+</span> <span class="pre">*m_order)</span></tt></td>
+<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>
@@ -195,12 +196,12 @@ permutation_iterator(
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">ElementIterator</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
+<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_iterator</span></tt></td>
+<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>

doc/permutation_iterator_ref.rst

@@ -20,7 +20,7 @@
 	);
     reference operator*() const;
     permutation_iterator& operator++();
-    ElementIterator base() const;
+    ElementIterator const& base() const;
   private:
     ElementIterator m_elt;      // exposition only
     IndexIterator m_order;      // exposition only
@@ -111,7 +111,7 @@ following operations.
 :Returns: ``*this``
 
 
-``ElementIterator base() const;``
+``ElementIterator const& base() const;``
 
 :Returns: ``m_order``
 

doc/reverse_iterator.html

@@ -72,7 +72,7 @@ public:
       reverse_iterator<OtherIterator> const& r
     , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
   );
-  Iterator base() const;
+  Iterator const& base() const;
   reference operator*() const;
   reverse_iterator& operator++();
   reverse_iterator& operator--();
@@ -175,7 +175,7 @@ reverse_iterator(
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">Iterator</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
+<p><tt class="literal"><span class="pre">Iterator</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" />

doc/reverse_iterator_ref.rst

@@ -18,7 +18,7 @@
         reverse_iterator<OtherIterator> const& r
       , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
     );
-    Iterator base() const;
+    Iterator const& base() const;
     reference operator*() const;
     reverse_iterator& operator++();
     reverse_iterator& operator--();
@@ -108,7 +108,7 @@ operations.
 
 
 
-``Iterator base() const;``
+``Iterator const& base() const;``
 
 :Returns: ``m_iterator``
 

doc/transform_iterator_ref.diff

@@ -48,7 +48,7 @@ Issue 9.43x
 
 Issues 9.37x and 9.12
 
-+    Iterator base() const;
++    Iterator const& base() const;
 +    reference operator*() const;
 +    transform_iterator& operator++();
 +    transform_iterator& operator--();
@@ -170,7 +170,7 @@ Issue 9.37x.
  :Requires: ``OtherIterator`` is implicitly convertible to ``Iterator``.
  
 +
-+``Iterator base() const;``
++``Iterator const& base() const;``
 +
 +:Returns: ``m_iterator``
 +

doc/transform_iterator_ref.rst

@@ -25,7 +25,7 @@
         , typename enable_if_convertible<F2, UnaryFunction>::type* = 0 // exposition only
     );
     UnaryFunction functor() const;
-    Iterator base() const;
+    Iterator const& base() const;
     reference operator*() const;
     transform_iterator& operator++();
     transform_iterator& operator--();
@@ -145,7 +145,7 @@ operations.
 :Returns: ``m_f``
 
 
-``Iterator base() const;``
+``Iterator const& base() const;``
 
 :Returns: ``m_iterator``