feedc0de/boost_bind
1
0
Fork 0
forked from boostorg/bind
Code Pull Requests Activity

Merge of new boost.thread code along with required changes from boost.bind

Browse Source 
[SVN r46474]
This commit is contained in:
Anthony Williams
2008-06-18 13:01:08 +00:00
parent 224e9f5eec
commit e22e641bbf
10 changed files with 916 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
bind.html
+78 -21
View File
@@ -60,6 +60,7 @@
<h4 style="MARGIN-LEFT: 40pt"><A href="#err_long_form">Inappropriate use of
bind&lt;R&gt;(f, ...)</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#err_nonstd">Binding a nonstandard function</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#err_overloaded">Binding an overloaded function</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#err_const_arg"><b>const</b> in signatures</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#err_msvc_using">MSVC specific: using
boost::bind;</A></h4>
@@ -188,6 +189,27 @@ bind(std::less&lt;int&gt;(), _1, 9)(x); // x &lt; 9
</pre>
<p>[Note: the ability to omit the return type is not available on all compilers.]
</p>
<P>By default, <STRONG>bind</STRONG> makes a copy of the provided function object. <code>
boost::ref</code> and <code>boost::cref</code> can be used to make it store
a reference to the function object, rather than a copy. This can be useful when
the function object is noncopyable, expensive to copy, or contains state; of
course, in this case the programmer is expected to ensure that the function
object is not destroyed while it's still being used.</P>
<pre>struct F2
{
int s;
typedef void result_type;
void operator()( int x ) { s += x; }
};
F2 f2 = { 0 };
int a[] = { 1, 2, 3 };
std::for_each( a, a+3, bind( ref(f2), _1 ) );
assert( f2.s == 6 );
</pre>
<h3><a name="with_member_pointers">Using bind with pointers to members</a></h3>
<p>Pointers to member functions and pointers to data members are not function
objects, because they do not support <tt>operator()</tt>. For convenience, <b>bind</b>
@@ -285,21 +307,23 @@ std::for_each(v.begin(), v.end(), bind(apply&lt;void&gt;(), _1, 5));
evaluation, use <tt>protect(bind(f, ...))</tt>.</P>
<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 <STRONG>!</STRONG> and the relational operators <STRONG>==</STRONG>,
<STRONG>!=</STRONG>, <STRONG>&lt;</STRONG>, <STRONG>&lt;=</STRONG>, <STRONG>&gt;</STRONG>,
<STRONG>&gt;=</STRONG>.</p>
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>
<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 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" );</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>
@@ -362,10 +386,12 @@ void connect()
}
</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);
@@ -373,17 +399,17 @@ void connect()
<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>
@@ -528,6 +554,37 @@ int main()
recognized by the short form of bind.
</p>
<P>See also <A href="#stdcall">"__stdcall" and "pascal" Support</A>.</P>
<h3><a name="err_overloaded">Binding an overloaded function</a></h3>
<p>An attempt to bind an overloaded function usually results in an error, as there
is no way to tell which overload was meant to be bound. This is a common
problem with member functions with two overloads, const and non-const, as in
this simplified example:</p>
<pre>struct X
{
int&amp; get();
int const&amp; get() const;
};
int main()
{
boost::bind( &amp;X::get, _1 );
}
</pre>
<P>The ambiguity can be resolved manually by casting the (member) function pointer
to the desired type:</P>
<pre>int main()
{
boost::bind( static_cast&lt; int const&amp; (X::*) () const &gt;( &amp;X::get ), _1 );
}
</pre>
<P>Another, arguably more readable, alternative is to introduce a temporary
variable:</P>
<pre>int main()
{
int const&amp; (X::*get) () const = &amp;X::get;
boost::bind( get, _1 );
}
</pre>
<h3><a name="err_const_arg"><b>const</b> in signatures</a></h3>
<p>Some compilers, including MSVC 6.0 and Borland C++ 5.5.1, have problems with the
top-level <b>const</b> in function signatures:
@@ -859,7 +916,7 @@ namespace
by Jaakko Järvi;
<li>
The <a href="../lambda/index.html">Lambda Library</a>
(now part of Boost) by Jaakko Järvi and Gary Powell (the successor to the
(now part of Boost) by Jaakko Järvi and Gary Powell (the successor to the
Binder Library);
<li>
<a href="http://more.sourceforge.net/">Extensions to the STL</a> by Petter
@@ -890,7 +947,7 @@ namespace
<br>
<br>
<small>Copyright © 2001, 2002 by Peter Dimov and Multi Media Ltd. Copyright
2003-2005 Peter Dimov. Distributed under the Boost Software License, Version
2003-2008 Peter Dimov. Distributed under the Boost Software License, Version
1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or
copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p>
</body>