[Boost-commit] svn:boost r43321 - trunk/libs/bind

From: pdimov_at_[hidden]
Date: 2008-02-19 10:09:10

Author: pdimov
Date: 2008-02-19 10:09:10 EST (Tue, 19 Feb 2008)
New Revision: 43321
URL: http://svn.boost.org/trac/boost/changeset/43321

Log:
Fix #1642.
Text files modified: 
   trunk/libs/bind/bind.html |    39 +++++++++++++++++++++------------------ 
   1 files changed, 21 insertions(+), 18 deletions(-)

Modified: trunk/libs/bind/bind.html
==============================================================================
--- trunk/libs/bind/bind.html	(original)
+++ trunk/libs/bind/bind.html	2008-02-19 10:09:10 EST (Tue, 19 Feb 2008)
@@ -307,21 +307,22 @@
                 <h3><a name="operators">Overloaded operators</a> (new in Boost 1.33)</h3>
                 <p>For convenience, the function objects produced by <tt>bind</tt> overload the 
                         logical not operator <code>!</code> and the relational and logical operators <code>==</code>,
-			<code>!=</code>, <code>&lt;</code>, <code>&lt;=</code>, <code>&gt;</code>,
-			<code>&gt;=</code>, <code>&amp;&amp;</code>, <code>||</code>.</p>
+			<code>!=</code>, <code>&lt;</code>, <code>&lt;=</code>, <code>&gt;</code>, <code>&gt;=</code>,
+			<code>&amp;&amp;</code>, <code>||</code>.</p>
                 <P><tt>!bind(f, ...)</tt> is equivalent to <tt>bind( <EM>logical_not</EM>(), bind(f, 
                                 ...) )</tt>, where <tt><EM>logical_not</EM></tt> is a function object that 
                         takes one argument <tt>x</tt> and returns <tt>!x</tt>.</P>
-		<P><tt>bind(f, ...) <EM>op</EM> x</tt>, where <EM>op</EM> is a relational or logical operator, 
-			is equivalent to <tt>bind( <EM>relation</EM>(), bind(f, ...), x )</tt>, where <em>relation</em>
-			is a function object that takes two arguments <tt>a</tt> and <tt>b</tt> and 
-			returns <tt>a <EM>op</EM> b</tt>.</P>
+		<P><tt>bind(f, ...) <EM>op</EM> x</tt>, where <EM>op</EM> is a relational or 
+			logical operator, is equivalent to <tt>bind( <EM>relation</EM>(), bind(f, ...), x )</tt>, 
+			where <em>relation</em> is a function object that takes two arguments <tt>a</tt>
+			and <tt>b</tt> and returns <tt>a <EM>op</EM> b</tt>.</P>
                 <P>What this means in practice is that you can conveniently negate the result of <tt>bind</tt>:</P>
                 <P><tt>std::remove_if( first, last, !bind( &amp;X::visible, _1 ) ); // remove invisible 
                                 objects</tt></P>
                 <P>and compare the result of <tt>bind</tt> against a value:</P>
                 <P><tt>std::find_if( first, last, bind( &amp;X::name, _1 ) == "Peter" );</tt></P>
-		<P><tt>std::find_if( first, last, bind( &amp;X::name, _1 ) == "Peter" || bind( &amp;X::name, _1 ) == "Paul" );</tt></P>
+		<P><tt>std::find_if( first, last, bind( &amp;X::name, _1 ) == "Peter" || bind( 
+				&amp;X::name, _1 ) == "Paul" );</tt></P>
                 <P>against a placeholder:</P>
                 <P><tt>bind( &amp;X::name, _1 ) == _2</tt></P>
                 <P>or against another <tt>bind</tt> expression:</P>
@@ -384,10 +385,12 @@
 }
 </pre>
                 <h2><a name="Limitations">Limitations</a></h2>
-		<p>The function objects generated by <b>bind</b> take their arguments by reference 
-			and cannot, therefore, accept non-const temporaries or literal constants. This 
-			is an inherent limitation of the C++ language, known as <A href="http://std.dkuug.dk/jtc1/sc22/wg21/docs/papers/2002/n1385.htm">
-				the forwarding problem</A>.</p>
+		<p>As a general rule, the function objects generated by <b>bind</b> take their 
+			arguments by reference and cannot, therefore, accept non-const temporaries or 
+			literal constants. This is an inherent limitation of the C++ language in its 
+			current (2003) incarnation, known as <A href="http://std.dkuug.dk/jtc1/sc22/wg21/docs/papers/2002/n1385.htm">
+				the forwarding problem</A>. (It will be fixed in the next standard, usually 
+			called C++0x.)</p>
                 <p>The library uses signatures of the form
                 </p>
                 <pre>template&lt;class T&gt; void f(T &amp; t);
@@ -395,17 +398,17 @@
                 <p>to accept arguments of arbitrary types and pass them on unmodified. As noted, 
                         this does not work with non-const r-values.
                 </p>
-		<p>An oft-proposed "solution" to this problem is to add an overload:
+		<p>On compilers that support partial ordering of function templates, a possible 
+			solution is to add an overload:
                 </p>
                 <pre>template&lt;class T&gt; void f(T &amp; t);
 template&lt;class T&gt; void f(T const &amp; t);
 </pre>
-		<p>Unfortunately, this (a) requires providing 512 overloads for nine arguments and 
-			(b) does not actually work for const arguments, both l- and r-values, since the 
-			two templates produce the exact same signature and cannot be partially ordered.
-		</p>
-		<p>[Note: this is a dark corner of the language, and the <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#214">
-				corresponding issue</a> has only recently been resolved.]
+		<p>Unfortunately, this requires providing 512 overloads for nine arguments, which 
+			is impractical. The library chooses a small subset: for up to two arguments, it 
+			provides the const overloads in full, for arities of three and more it provides 
+			a single additional overload with all of the arguments taken by const 
+			reference. This covers a reasonable portion of the use cases.
                 </p>
                 <h2><a name="FAQ">Frequently Asked Questions</a></h2>
                 <h3><a name="Q_doesnt_compile">Why doesn't this compile?</a></h3>