From 1e3da4b77f527437b018262616dadb0e2ebf6390 Mon Sep 17 00:00:00 2001
From: Dave Abrahams <dave@boostpro.com>
Date: Thu, 15 Jan 2004 19:06:25 +0000
Subject: [PATCH] Return base by const&

[SVN r21775]
---
 doc/facade-and-adaptor.html  | 16 ++++++----------
 doc/iterator_adaptor.html    |  9 ++++++---
 doc/iterator_adaptor_ref.rst |  8 ++++++--
 doc/iterator_facade.html     |  8 --------
 4 files changed, 18 insertions(+), 23 deletions(-)

diff --git a/doc/facade-and-adaptor.html b/doc/facade-and-adaptor.html
index f91c8a7..b55fbc5 100755
--- a/doc/facade-and-adaptor.html
+++ b/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>
diff --git a/doc/iterator_adaptor.html b/doc/iterator_adaptor.html
index 62e516a..020a4ba 100644
--- a/doc/iterator_adaptor.html
+++ b/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&amp; base_reference() const;
     Base&amp; 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>
diff --git a/doc/iterator_adaptor_ref.rst b/doc/iterator_adaptor_ref.rst
index ece0684..cc643d3 100644
--- a/doc/iterator_adaptor_ref.rst
+++ b/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
 -----------------------------------------------
diff --git a/doc/iterator_facade.html b/doc/iterator_facade.html
index df4c831..d607f4d 100644
--- a/doc/iterator_facade.html
+++ b/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,