Return base by const&

[SVN r21775]

doc/facade-and-adaptor.html

@@ -742,14 +742,6 @@ traversal tags would add no information]</p>
 <!-- Copyright David Abrahams 2004. Use, modification and distribution is -->
 <!-- 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>If <tt class="literal"><span class="pre">CategoryOrTraversal</span></tt> is <tt class="literal"><span class="pre">use_default</span></tt> then
-<tt class="literal"><span class="pre">iterator_traversal&lt;Derived&gt;::type</span></tt> is convertible to the most
-derived standard traversal tag type to which
-<tt class="literal"><span class="pre">iterator_traversal&lt;Iterator&gt;::type</span></tt> is also convertible, and not to
-any more-derived traversal tag type.  Otherwise
-<tt class="literal"><span class="pre">iterator_traversal&lt;Derived&gt;::type</span></tt> is convertible to the most
-derived standard traversal tag type to which <tt class="literal"><span class="pre">CategoryOrTraversal</span></tt>
-is also convertible, and not to any more-derived traversal tag type.</p>
 <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
 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, 
@@ -1173,7 +1165,7 @@ class iterator_adaptor
  public:
     iterator_adaptor();
     explicit iterator_adaptor(Base iter);
-    Base base() const;
+    Base const base() const;
  protected:
     Base const&amp; base_reference() const;
     Base&amp; base_reference();
@@ -1270,7 +1262,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">base()</span> <span class="pre">const;</span></tt></p>
+<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>
 <table class="field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
@@ -1279,6 +1271,10 @@ 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>

doc/iterator_adaptor.html

@@ -133,7 +133,7 @@ class iterator_adaptor
  public:
     iterator_adaptor();
     explicit iterator_adaptor(Base iter);
-    Base base() const;
+    Base const base() const;
  protected:
     Base const& base_reference() const;
     Base& base_reference();
@@ -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">base()</span> <span class="pre">const;</span></tt></p>
+<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>
 <table class="field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
@@ -238,6 +238,10 @@ 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>
@@ -440,7 +444,6 @@ adaptor, and also <a class="reference" href="counting_iterator.html"><tt class="
 <hr class="footer" />
 <div class="footer">
 <a class="reference" href="iterator_adaptor.rst">View document source</a>.
-Generated on: 2004-01-13 19:35 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>

doc/iterator_adaptor_ref.rst

@@ -21,7 +21,7 @@
    public:
       iterator_adaptor();
       explicit iterator_adaptor(Base iter);
-      Base base() const;
+      Base const base() const;
    protected:
       Base const& base_reference() const;
       Base& base_reference();
@@ -122,10 +122,14 @@ expression involving ``Derived`` in those concepts' requirements.
 :Returns: An instance of ``iterator_adaptor`` with
     ``m_iterator`` copy constructed from ``iter``.
 
-``Base 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

@@ -407,14 +407,6 @@ traversal tags would add no information]</p>
 <!-- Copyright David Abrahams 2004. Use, modification and distribution is -->
 <!-- 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>If <tt class="literal"><span class="pre">CategoryOrTraversal</span></tt> is <tt class="literal"><span class="pre">use_default</span></tt> then
-<tt class="literal"><span class="pre">iterator_traversal&lt;Derived&gt;::type</span></tt> is convertible to the most
-derived standard traversal tag type to which
-<tt class="literal"><span class="pre">iterator_traversal&lt;Iterator&gt;::type</span></tt> is also convertible, and not to
-any more-derived traversal tag type.  Otherwise
-<tt class="literal"><span class="pre">iterator_traversal&lt;Derived&gt;::type</span></tt> is convertible to the most
-derived standard traversal tag type to which <tt class="literal"><span class="pre">CategoryOrTraversal</span></tt>
-is also convertible, and not to any more-derived traversal tag type.</p>
 <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
 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,