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

Added - an example of using boost::cref

Browse Source 
[SVN r29376]
This commit is contained in:
Victor A. Wagner Jr.
2005-06-02 15:29:01 +00:00
parent 9cfe194f80
commit 2a21f7df2c
1 changed files with 212 additions and 210 deletions
Download Patch File Download Diff File Expand all files Collapse all files

422
bind.html
View File

@@ -19,53 +19,53 @@
</table>
<h2>Contents</h2>
<h3 style="MARGIN-LEFT: 20pt"><A href="#Purpose">Purpose</A></h3>
<h4 style="MARGIN-LEFT: 40pt"><A href="#with_functions">Using bind with functions and
<h4 style="MARGIN-LEFT: 40pt"><A href="#with_functions">Using bind with functions and
function pointers</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#with_function_objects">Using bind with function
<h4 style="MARGIN-LEFT: 40pt"><A href="#with_function_objects">Using bind with function
objects</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#with_member_pointers">Using bind with pointers
<h4 style="MARGIN-LEFT: 40pt"><A href="#with_member_pointers">Using bind with pointers
to members</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#nested_binds">Using nested binds for function
<h4 style="MARGIN-LEFT: 40pt"><A href="#nested_binds">Using nested binds for function
composition</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#operators">Overloaded operators</A></h4>
<h3 style="MARGIN-LEFT: 20pt"><A href="#Examples">Examples</A></h3>
<h4 style="MARGIN-LEFT: 40pt"><A href="#with_algorithms">Using bind with standard
<h4 style="MARGIN-LEFT: 40pt"><A href="#with_algorithms">Using bind with standard
algorithms</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#with_boost_function">Using bind with
<h4 style="MARGIN-LEFT: 40pt"><A href="#with_boost_function">Using bind with
Boost.Function</A></h4>
<h3 style="MARGIN-LEFT: 20pt"><A href="#Limitations">Limitations</A></h3>
<h3 style="MARGIN-LEFT: 20pt"><A href="#FAQ">Frequently Asked Questions</A></h3>
<h4 style="MARGIN-LEFT: 40pt"><A href="#Q_doesnt_compile">Why doesn't this compile?</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#Q_does_compile">Why does this compile? It
<h4 style="MARGIN-LEFT: 40pt"><A href="#Q_does_compile">Why does this compile? It
should not.</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#Q_forms">What is the difference between bind(f,
<h4 style="MARGIN-LEFT: 40pt"><A href="#Q_forms">What is the difference between bind(f,
...) and bind&lt;R&gt;(f, ...)?</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#Q_win32_api">Does <b>bind</b> work with Windows
<h4 style="MARGIN-LEFT: 40pt"><A href="#Q_win32_api">Does <b>bind</b> work with Windows
API functions?</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#Q_com">Does <b>bind</b> work with COM methods?</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#Q_mac">Does <b>bind</b> work with Mac toolbox
<h4 style="MARGIN-LEFT: 40pt"><A href="#Q_mac">Does <b>bind</b> work with Mac toolbox
functions?</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#Q_extern_C">Does <b>bind</b> work with extern
<h4 style="MARGIN-LEFT: 40pt"><A href="#Q_extern_C">Does <b>bind</b> work with extern
"C" functions?</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#Q_auto_stdcall">Why doesn't <b>bind</b> automatically
<h4 style="MARGIN-LEFT: 40pt"><A href="#Q_auto_stdcall">Why doesn't <b>bind</b> automatically
recognize nonstandard functions?</A></h4>
<h3 style="MARGIN-LEFT: 20pt"><A href="#Troubleshooting">Troubleshooting</A></h3>
<h4 style="MARGIN-LEFT: 40pt"><A href="#err_num_args">Incorrect number of arguments</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#err_signature">The function object cannot be
<h4 style="MARGIN-LEFT: 40pt"><A href="#err_signature">The function object cannot be
called with the specified arguments</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#err_arg_access">Accessing an argument that does
<h4 style="MARGIN-LEFT: 40pt"><A href="#err_arg_access">Accessing an argument that does
not exist</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#err_short_form">Inappropriate use of bind(f,
<h4 style="MARGIN-LEFT: 40pt"><A href="#err_short_form">Inappropriate use of bind(f,
...)</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#err_long_form">Inappropriate use of
<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_const_arg"><b>const</b> in signatures</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#err_msvc_using">MSVC specific: using
<h4 style="MARGIN-LEFT: 40pt"><A href="#err_msvc_using">MSVC specific: using
boost::bind;</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#err_msvc_class_template">MSVC specific: class
<h4 style="MARGIN-LEFT: 40pt"><A href="#err_msvc_class_template">MSVC specific: class
templates shadow function templates</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#err_msvc_ellipsis">MSVC specific: ... in
<h4 style="MARGIN-LEFT: 40pt"><A href="#err_msvc_ellipsis">MSVC specific: ... in
signatures treated as type</A></h4>
<h3 style="MARGIN-LEFT: 20pt"><A href="#Interface">Interface</A></h3>
<h4 style="MARGIN-LEFT: 40pt"><A href="#Synopsis">Synopsis</A></h4>
@@ -77,16 +77,16 @@
<h4 style="MARGIN-LEFT: 40pt"><A href="#Files">Files</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#Dependencies">Dependencies</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#NumberOfArguments">Number of Arguments</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#stdcall">"__stdcall", "__cdecl", "__fastcall",
<h4 style="MARGIN-LEFT: 40pt"><A href="#stdcall">"__stdcall", "__cdecl", "__fastcall",
and "pascal" Support</A></h4>
<h4 style="MARGIN-LEFT: 40pt"><A href="#visit_each"><b>visit_each</b> support</A></h4>
<h3 style="MARGIN-LEFT: 20pt"><A href="#Acknowledgements">Acknowledgements</A></h3>
<h2><a name="Purpose">Purpose</a></h2>
<p><b>boost::bind</b> is a generalization of the standard functions <b>std::bind1st</b>
and <b>std::bind2nd</b>. It supports arbitrary function objects, functions,
function pointers, and member function pointers, and is able to bind any
and <b>std::bind2nd</b>. It supports arbitrary function objects, functions,
function pointers, and member function pointers, and is able to bind any
argument to a specific value or route input arguments into arbitrary positions. <b>bind</b>
does not place any requirements on the function object; in particular, it does
does not place any requirements on the function object; in particular, it does
not need the <b>result_type</b>, <b>first_argument_type</b> and <b>second_argument_type</b>
standard typedefs.
</p>
@@ -103,15 +103,15 @@ int g(int a, int b, int c)
return a + b + c;
}
</pre>
<p><tt>bind(f, 1, 2)</tt> will produce a "nullary" function object that takes no
arguments and returns <tt>f(1, 2)</tt>. Similarly, <tt>bind(g, 1, 2, 3)()</tt> is
<p><tt>bind(f, 1, 2)</tt> will produce a "nullary" function object that takes no
arguments and returns <tt>f(1, 2)</tt>. Similarly, <tt>bind(g, 1, 2, 3)()</tt> is
equivalent to <tt>g(1, 2, 3)</tt>.
</p>
<p>It is possible to selectively bind only some of the arguments. <tt>bind(f, _1, 5)(x)</tt>
is equivalent to <tt>f(x, 5)</tt>; here <b>_1</b>
is a placeholder argument that means "substitute with the first input
is a placeholder argument that means "substitute with the first input
argument."
<p>For comparison, here is the same operation expressed with the standard library
<p>For comparison, here is the same operation expressed with the standard library
primitives:
</p>
<pre>std::bind2nd(std::ptr_fun(f), 5)(x);
@@ -121,7 +121,7 @@ int g(int a, int b, int c)
<pre>std::bind1st(std::ptr_fun(f), 5)(x); // f(5, x)
bind(f, 5, _1)(x); // f(5, x)
</pre>
<p><b>bind</b> can handle functions with more than two arguments, and its argument
<p><b>bind</b> can handle functions with more than two arguments, and its argument
substitution mechanism is more general:
</p>
<pre>bind(f, _2, _1)(x, y); // f(y, x)
@@ -132,13 +132,13 @@ bind(g, _3, _3, _3)(x, y, z); // g(z, z, z)
bind(g, _1, _1, _1)(x, y, z); // g(x, x, x)
</pre>
<p>Note that, in the last example, the function object produced by <tt>bind(g, _1, _1,
_1)</tt> does not contain references to any arguments beyond the first, but
it can still be used with more than one argument. Any extra arguments are
silently ignored, just like the first and the second argument are ignored in
<p>Note that, in the last example, the function object produced by <tt>bind(g, _1, _1,
_1)</tt> does not contain references to any arguments beyond the first, but
it can still be used with more than one argument. Any extra arguments are
silently ignored, just like the first and the second argument are ignored in
the third example.
</p>
<p>The arguments that <b>bind</b> takes are copied and held internally by the
<p>The arguments that <b>bind</b> takes are copied and held internally by the
returned function object. For example, in the following code:
</p>
<pre>int i = 5;
@@ -146,17 +146,19 @@ bind(g, _1, _1, _1)(x, y, z); // g(x, x, x)
bind(f, i, _1);
</pre>
<p>a copy of the value of <b>i</b> is stored into the function object. <A href="ref.html">
boost::ref</A> and <A href="ref.html">boost::cref</A> can be used to make
boost::ref</A> and <A href="ref.html">boost::cref</A> can be used to make
the function object store a reference to an object, rather than a copy:
</p>
<pre>int i = 5;
bind(f, ref(i), _1);
bind(f, cref(42), _1);
</pre>
<h3><a name="with_function_objects">Using bind with function objects</a></h3>
<p><b>bind</b> is not limited to functions; it accepts arbitrary function objects.
<p><b>bind</b> is not limited to functions; it accepts arbitrary function objects.
In the general case, the return type of the generated function object's <b>operator()</b>
has to be specified explicitly (without a <b>typeof</b> operator the return
has to be specified explicitly (without a <b>typeof</b> operator the return
type cannot be inferred):
</p>
<pre>struct F
@@ -171,13 +173,13 @@ int x = 104;
bind&lt;int&gt;(f, _1, _1)(x); // f(x, x), i.e. zero
</pre>
<p>Some compilers have trouble with the <tt>bind&lt;R&gt;(f, ...)</tt> syntax. For
<p>Some compilers have trouble with the <tt>bind&lt;R&gt;(f, ...)</tt> syntax. For
portability reasons, an alternative way to express the above is supported:</p>
<pre>boost::bind(boost::type&lt;int&gt;(), f, _1, _1)(x);
</pre>
<P>Note, however, that the alternative syntax is provided only as a workaround. It
<P>Note, however, that the alternative syntax is provided only as a workaround. It
is not part of the interface.</P>
<P>When the function object exposes a nested type named <b>result_type</b>, the
<P>When the function object exposes a nested type named <b>result_type</b>, the
explicit return type can be omitted:
</P>
<pre>int x = 8;
@@ -187,10 +189,10 @@ bind(std::less&lt;int&gt;(), _1, 9)(x); // x &lt; 9
<p>[Note: the ability to omit the return type is not available on all compilers.]
</p>
<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
<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>
accepts member pointers as its first argument, and the behavior is as if <A href="mem_fn.html">
boost::mem_fn</A> has been used to convert the member pointer into a
boost::mem_fn</A> has been used to convert the member pointer into a
function object. In other words, the expression
</p>
<pre>bind(&amp;X::f, <i>args</i>)
@@ -199,11 +201,11 @@ bind(std::less&lt;int&gt;(), _1, 9)(x); // x &lt; 9
</p>
<pre>bind&lt;R&gt;(<A href="mem_fn.html" >mem_fn</A>(&amp;X::f), <i>args</i>)
</pre>
<p>where <b>R</b> is the return type of <b>X::f</b> (for member functions) or the
<p>where <b>R</b> is the return type of <b>X::f</b> (for member functions) or the
type of the member (for data members.)
</p>
<p>[Note: <b>mem_fn</b> creates function objects that are able to accept a pointer,
a reference, or a smart pointer to an object as its first argument; for
<p>[Note: <b>mem_fn</b> creates function objects that are able to accept a pointer,
a reference, or a smart pointer to an object as its first argument; for
additional information, see the <b>mem_fn</b> <A href="mem_fn.html">documentation</A>.]
</p>
<p>Example:
@@ -224,33 +226,33 @@ bind(&amp;X::f, &amp;x, _1)(i); //(&amp;x)-&gt;f(i)
bind(&amp;X::f, x, _1)(i); // (<i>internal copy of x</i>).f(i)
bind(&amp;X::f, p, _1)(i); // (<i>internal copy of p</i>)-&gt;f(i)
</pre>
<p>The last two examples are interesting in that they produce "self-contained"
function objects. <tt>bind(&amp;X::f, x, _1)</tt> stores a copy of <b>x</b>. <tt>bind(&amp;X::f,
<p>The last two examples are interesting in that they produce "self-contained"
function objects. <tt>bind(&amp;X::f, x, _1)</tt> stores a copy of <b>x</b>. <tt>bind(&amp;X::f,
p, _1)</tt> stores a copy of <b>p</b>, and since <b>p</b> is a <A href="../smart_ptr/shared_ptr.htm">
boost::shared_ptr</A>, the function object retains a reference to its
instance of <b>X</b> and will remain valid even when <b>p</b> goes out of scope
boost::shared_ptr</A>, the function object retains a reference to its
instance of <b>X</b> and will remain valid even when <b>p</b> goes out of scope
or is <b>reset()</b>.
</p>
<h3><a name="nested_binds">Using nested binds for function composition</a></h3>
<p>Some of the arguments passed to <b>bind</b> may be nested <b>bind</b> expressions
<p>Some of the arguments passed to <b>bind</b> may be nested <b>bind</b> expressions
themselves:
</p>
<pre>bind(f, bind(g, _1))(x); // f(g(x))
</pre>
<p>The inner <STRONG>bind</STRONG> expressions are evaluated, in unspecified order,
before the outer <STRONG>bind</STRONG> when the function object is called; the
<p>The inner <STRONG>bind</STRONG> expressions are evaluated, in unspecified order,
before the outer <STRONG>bind</STRONG> when the function object is called; the
results of the evaluation are then substituted in their place when the outer <STRONG>
bind</STRONG> is evaluated. In the example above, when the function object
is called with the argument list <tt>(x)</tt>, <tt>bind(g, _1)(x)</tt> is
evaluated first, yielding <tt>g(x)</tt>, and then <tt>bind(f, g(x))(x)</tt> is
bind</STRONG> is evaluated. In the example above, when the function object
is called with the argument list <tt>(x)</tt>, <tt>bind(g, _1)(x)</tt> is
evaluated first, yielding <tt>g(x)</tt>, and then <tt>bind(f, g(x))(x)</tt> is
evaluated, yielding the final result <tt>f(g(x))</tt>.
</p>
<P>This feature of <b>bind</b> can be used to perform function composition. See <A href="bind_as_compose.cpp">
bind_as_compose.cpp</A> for an example that demonstrates how to use <b>bind</b>
to achieve similar functionality to <A href="../compose/index.htm">Boost.Compose</A>.
</P>
<p>Note that the first argument - the bound function object - is not evaluated,
even when it's a function object that is produced by <STRONG>bind</STRONG> or a
<p>Note that the first argument - the bound function object - is not evaluated,
even when it's a function object that is produced by <STRONG>bind</STRONG> or a
placeholder argument, so the example below does not work as expected:
</p>
<pre>typedef void (*pf)(int);
@@ -260,9 +262,9 @@ std::vector&lt;pf&gt; v;
std::for_each(v.begin(), v.end(), bind(_1, 5));
</pre>
<p>The desired effect can be achieved via a helper function object <STRONG>apply</STRONG>
that applies its first argument, as a function object, to the rest of its
argument list. For convenience, an implementation of <STRONG>apply</STRONG> is
provided in the <STRONG>boost/bind/apply.hpp</STRONG> header file. Here is how
that applies its first argument, as a function object, to the rest of its
argument list. For convenience, an implementation of <STRONG>apply</STRONG> is
provided in the <STRONG>boost/bind/apply.hpp</STRONG> header file. Here is how
the modified version of the previous example looks like:
</p>
<pre>typedef void (*pf)(int);
@@ -271,38 +273,38 @@ std::vector&lt;pf&gt; v;
std::for_each(v.begin(), v.end(), bind(apply&lt;void&gt;(), _1, 5));
</pre>
<P>Although the first argument is, by default, not evaluated, all other arguments
are. Sometimes it is necessary not to evaluate arguments subsequent to the
first, even when they are nested <STRONG>bind</STRONG> subexpressions. This can
be achieved with the help of another function object, <STRONG>protect</STRONG>,
that masks the type so that <STRONG>bind</STRONG> does not recognize and
evaluate it. When called, <STRONG>protect</STRONG> simply forwards the argument
<P>Although the first argument is, by default, not evaluated, all other arguments
are. Sometimes it is necessary not to evaluate arguments subsequent to the
first, even when they are nested <STRONG>bind</STRONG> subexpressions. This can
be achieved with the help of another function object, <STRONG>protect</STRONG>,
that masks the type so that <STRONG>bind</STRONG> does not recognize and
evaluate it. When called, <STRONG>protect</STRONG> simply forwards the argument
list to the other function object unmodified.</P>
<P>The header <STRONG>boost/bind/protect.hpp</STRONG> contains an implementation of <STRONG>
protect</STRONG>. To protect a <STRONG>bind</STRONG> function object from
protect</STRONG>. To protect a <STRONG>bind</STRONG> function object from
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
<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>
<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
<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,
<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
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
<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
<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>against a placeholder:</P>
<P><tt>bind( &amp;X::name, _1 ) == _2</tt></P>
<P>or against another <tt>bind</tt> expression:</P>
<P><tt>std::sort( first, last, bind( &amp;X::name, _1 ) &lt; bind( &amp;X::name, _2 )
<P><tt>std::sort( first, last, bind( &amp;X::name, _1 ) &lt; bind( &amp;X::name, _2 )
); // sort by name</tt></P>
<h2><a name="Examples">Examples</a></h2>
<h3><a name="with_algorithms">Using bind with standard algorithms</a></h3>
@@ -361,15 +363,15 @@ 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
<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>The library uses signatures of the form
</p>
<pre>template&lt;class T&gt; void f(T &amp; t);
</pre>
<p>to accept arguments of arbitrary types and pass them on unmodified. As noted,
<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:
@@ -377,8 +379,8 @@ void connect()
<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
<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">
@@ -388,60 +390,60 @@ template&lt;class T&gt; void f(T const &amp; t);
<h3><a name="Q_doesnt_compile">Why doesn't this compile?</a></h3>
<p>See the <A href="#Troubleshooting">dedicated Troubleshooting section</A>.</p>
<h3><a name="Q_does_compile">Why does this compile? It should not.</a></h3>
<p>Probably because you used the general <tt>bind&lt;R&gt;(f, ...)</tt> syntax,
thereby instructing <b>bind</b> to not "inspect" <b>f</b> to detect arity and
<p>Probably because you used the general <tt>bind&lt;R&gt;(f, ...)</tt> syntax,
thereby instructing <b>bind</b> to not "inspect" <b>f</b> to detect arity and
return type errors.</p>
<h3><a name="Q_forms">What is the difference between bind(f, ...) and bind&lt;R&gt;(f,
<h3><a name="Q_forms">What is the difference between bind(f, ...) and bind&lt;R&gt;(f,
...)?</a></h3>
<p>The first form instructs <b>bind</b> to inspect the type of <b>f</b> in order to
determine its arity (number of arguments) and return type. Arity errors will be
detected at "bind time". This syntax, of course, places some requirements on <b>f</b>.
It must be a function, function pointer, member function pointer, or a function
object that defines a nested type named <b>result_type</b>; in short, it must
<p>The first form instructs <b>bind</b> to inspect the type of <b>f</b> in order to
determine its arity (number of arguments) and return type. Arity errors will be
detected at "bind time". This syntax, of course, places some requirements on <b>f</b>.
It must be a function, function pointer, member function pointer, or a function
object that defines a nested type named <b>result_type</b>; in short, it must
be something that <b>bind</b> can recognize.</p>
<p>The second form instructs <b>bind</b> to <b>not</b> attempt to recognize the
type of <b>f</b>. It is generally used with function objects that do not, or
cannot, expose <b>result_type</b>, but it can also be used with nonstandard
functions. For example, the current implementation does not automatically
recognize variable-argument functions like <b>printf</b>, so you will have to
use <tt>bind&lt;int&gt;(printf, ...)</tt>. Note that an alternative <tt>bind(type&lt;R&gt;(),
<p>The second form instructs <b>bind</b> to <b>not</b> attempt to recognize the
type of <b>f</b>. It is generally used with function objects that do not, or
cannot, expose <b>result_type</b>, but it can also be used with nonstandard
functions. For example, the current implementation does not automatically
recognize variable-argument functions like <b>printf</b>, so you will have to
use <tt>bind&lt;int&gt;(printf, ...)</tt>. Note that an alternative <tt>bind(type&lt;R&gt;(),
f, ...)</tt> syntax is supported for portability reasons.</p>
<p>Another important factor to consider is that compilers without partial template
specialization or function template partial ordering support cannot handle the
first form when <b>f</b> is a function object, and in most cases will not
handle the second form when <b>f</b> is a function (pointer) or a member
<p>Another important factor to consider is that compilers without partial template
specialization or function template partial ordering support cannot handle the
first form when <b>f</b> is a function object, and in most cases will not
handle the second form when <b>f</b> is a function (pointer) or a member
function pointer.</p>
<h3><a name="Q_win32_api">Does <b>bind</b> work with Windows API functions?</a></h3>
<p>Yes, if you <A href="#stdcall">#define BOOST_BIND_ENABLE_STDCALL</A>. An
alternative is to treat the function as a <A href="#with_function_objects">generic
<p>Yes, if you <A href="#stdcall">#define BOOST_BIND_ENABLE_STDCALL</A>. An
alternative is to treat the function as a <A href="#with_function_objects">generic
function object</A> and use the <tt>bind&lt;R&gt;(f, ...)</tt> syntax.</p>
<h3><a name="Q_com">Does <b>bind</b> work with COM methods?</a></h3>
<p>Yes, if you <A href="#stdcall">#define BOOST_MEM_FN_ENABLE_STDCALL</A>.</p>
<h3><a name="Q_mac">Does <b>bind</b> work with Mac toolbox functions?</a></h3>
<p>Yes, if you <A href="#stdcall">#define BOOST_BIND_ENABLE_PASCAL</A>. An
alternative is to treat the function as a <A href="#with_function_objects">generic
<p>Yes, if you <A href="#stdcall">#define BOOST_BIND_ENABLE_PASCAL</A>. An
alternative is to treat the function as a <A href="#with_function_objects">generic
function object</A> and use the <tt>bind&lt;R&gt;(f, ...)</tt> syntax.</p>
<h3><a name="Q_extern_C">Does <b>bind</b> work with extern "C" functions?</a></h3>
<p>Sometimes. On some platforms, pointers to extern "C" functions are equivalent to
"ordinary" function pointers, so they work fine. Other platforms treat them as
different types. A platform-specific implementation of <b>bind</b> is expected
to handle the problem transparently; this implementation does not. As usual,
the workaround is to treat the function as a <A href="#with_function_objects">generic
<p>Sometimes. On some platforms, pointers to extern "C" functions are equivalent to
"ordinary" function pointers, so they work fine. Other platforms treat them as
different types. A platform-specific implementation of <b>bind</b> is expected
to handle the problem transparently; this implementation does not. As usual,
the workaround is to treat the function as a <A href="#with_function_objects">generic
function object</A> and use the <tt>bind&lt;R&gt;(f, ...)</tt> syntax.</p>
<h3><a name="Q_auto_stdcall">Why doesn't <b>bind</b> automatically recognize
<h3><a name="Q_auto_stdcall">Why doesn't <b>bind</b> automatically recognize
nonstandard functions?</a></h3>
<p>Non-portable extensions, in general, should default to off to prevent vendor
lock-in. Had the <A href="#stdcall">appropriate macros</A> been defined
automatically, you could have accidentally taken advantage of them without
realizing that your code is, perhaps, no longer portable. In addition, some
compilers have the option to make <b>__stdcall</b> (<STRONG>__fastcall</STRONG>)
their default calling convention, in which case no separate support would be
<p>Non-portable extensions, in general, should default to off to prevent vendor
lock-in. Had the <A href="#stdcall">appropriate macros</A> been defined
automatically, you could have accidentally taken advantage of them without
realizing that your code is, perhaps, no longer portable. In addition, some
compilers have the option to make <b>__stdcall</b> (<STRONG>__fastcall</STRONG>)
their default calling convention, in which case no separate support would be
necessary.</p>
<h2><a name="Troubleshooting">Troubleshooting</a></h2>
<h3><a name="err_num_args">Incorrect number of arguments</a></h3>
<p>In a <tt>bind(f, a1, a2, ..., aN)</tt> expression, the function object <b>f</b> must
be able to take exactly <b>N</b> arguments. This error is normally detected at
"bind time"; in other words, the compilation error is reported on the line
<p>In a <tt>bind(f, a1, a2, ..., aN)</tt> expression, the function object <b>f</b> must
be able to take exactly <b>N</b> arguments. This error is normally detected at
"bind time"; in other words, the compilation error is reported on the line
where bind() is invoked:</p>
<pre>int f(int, int);
@@ -451,7 +453,7 @@ int main()
boost::bind(f, 1, 2); // OK
}
</pre>
<p>A common variation of this error is to forget that member functions have an
<p>A common variation of this error is to forget that member functions have an
implicit "this" argument:</p>
<pre>struct X
{
@@ -464,10 +466,10 @@ int main()
boost::bind(&amp;X::f, <b>_1</b>, 1); // OK
}
</pre>
<h3><a name="err_signature">The function object cannot be called with the specified
<h3><a name="err_signature">The function object cannot be called with the specified
arguments</a></h3>
<p>As in normal function calls, the function object that is bound must be
compatible with the argument list. The incompatibility will usually be detected
<p>As in normal function calls, the function object that is bound must be
compatible with the argument list. The incompatibility will usually be detected
by the compiler at "call time" and the result is typically an error in <b>bind.hpp</b>
on a line that looks like:</p>
<pre> return f(a[a1_], a[a2_]);
@@ -484,8 +486,8 @@ int main()
}
</pre>
<h3><a name="err_arg_access">Accessing an argument that does not exist</a></h3>
<p>The placeholder <b>_N</b> selects the argument at position <b>N</b> from the
argument list passed at "call time." Naturally, it is an error to attempt to
<p>The placeholder <b>_N</b> selects the argument at position <b>N</b> from the
argument list passed at "call time." Naturally, it is an error to attempt to
access beyond the end of this list:</p>
<pre>int f(int);
@@ -498,37 +500,37 @@ int main()
<p>The error is usually reported in <b>bind.hpp</b>, at a line similar to:</p>
<pre> return f(a[a1_]);
</pre>
<p>When emulating <tt>std::bind1st(f, a)</tt>, a common mistake of this category is
<p>When emulating <tt>std::bind1st(f, a)</tt>, a common mistake of this category is
to type <tt>bind(f, a, _2)</tt> instead of the correct <tt>bind(f, a, _1)</tt>.</p>
<h3><a name="err_short_form">Inappropriate use of bind(f, ...)</a></h3>
<p>The <tt>bind(f, a1, a2, ..., aN)</tt> <A href="#Q_forms">form</A> causes
automatic recognition of the type of <b>f</b>. It will not work with arbitrary
<p>The <tt>bind(f, a1, a2, ..., aN)</tt> <A href="#Q_forms">form</A> causes
automatic recognition of the type of <b>f</b>. It will not work with arbitrary
function objects; <b>f</b> must be a function or a member function pointer.</p>
<p>It is possible to use this form with function objects that define <b>result_type</b>,
but <b>only on compilers</b> that support partial specialization and partial
ordering. In particular, MSVC up to version 7.0 does not support this syntax
<p>It is possible to use this form with function objects that define <b>result_type</b>,
but <b>only on compilers</b> that support partial specialization and partial
ordering. In particular, MSVC up to version 7.0 does not support this syntax
for function objects.</p>
<h3><a name="err_long_form">Inappropriate use of bind&lt;R&gt;(f, ...)</a></h3>
<p>The <tt>bind&lt;R&gt;(f, a1, a2, ..., aN)</tt> <A href="#Q_forms">form</A> supports
<p>The <tt>bind&lt;R&gt;(f, a1, a2, ..., aN)</tt> <A href="#Q_forms">form</A> supports
arbitrary function objects.</p>
<p>It is possible (but not recommended) to use this form with functions or member
function pointers, but <b>only on compilers</b> that support partial ordering.
In particular, MSVC up to version 7.0 does not fully support this syntax for
<p>It is possible (but not recommended) to use this form with functions or member
function pointers, but <b>only on compilers</b> that support partial ordering.
In particular, MSVC up to version 7.0 does not fully support this syntax for
functions and member function pointers.</p>
<h3><a name="err_nonstd">Binding a nonstandard function</a></h3>
<p>By default, the <tt>bind(f, a1, a2, ..., aN)</tt> <A href="#Q_forms">form</A> recognizes
"ordinary" C++ functions and function pointers. <A href="#stdcall">Functions that
use a different calling convention</A>, or variable-argument functions such
as <STRONG>std::printf</STRONG>, do not work. The general <tt>bind&lt;R&gt;(f, a1,
a2, ..., aN)</tt> <A href="#Q_forms">form</A> works with nonstandard
<p>By default, the <tt>bind(f, a1, a2, ..., aN)</tt> <A href="#Q_forms">form</A> recognizes
"ordinary" C++ functions and function pointers. <A href="#stdcall">Functions that
use a different calling convention</A>, or variable-argument functions such
as <STRONG>std::printf</STRONG>, do not work. The general <tt>bind&lt;R&gt;(f, a1,
a2, ..., aN)</tt> <A href="#Q_forms">form</A> works with nonstandard
functions.
</p>
<p>On some platforms, extern "C" functions, like <b>std::strcmp</b>, are not
<p>On some platforms, extern "C" functions, like <b>std::strcmp</b>, are not
recognized by the short form of bind.
</p>
<P>See also <A href="#stdcall">"__stdcall" and "pascal" Support</A>.</P>
<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
<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:
</p>
<pre>int f(int const);
@@ -541,27 +543,27 @@ int main()
<p>Workaround: remove the <b>const</b> qualifier from the argument.
</p>
<h3><a name="err_msvc_using">MSVC specific: using boost::bind;</a></h3>
<p>On MSVC (up to version 7.0), when <b>boost::bind</b> is brought into scope with
<p>On MSVC (up to version 7.0), when <b>boost::bind</b> is brought into scope with
an using declaration:
</p>
<pre>using boost::bind;
</pre>
<p>the syntax <tt>bind&lt;R&gt;(f, ...)</tt> does not work. Workaround: either use
<p>the syntax <tt>bind&lt;R&gt;(f, ...)</tt> does not work. Workaround: either use
the qualified name, <b>boost::bind</b>, or use an using directive instead:
</p>
<pre>using namespace boost;
</pre>
<h3><a name="err_msvc_class_template">MSVC specific: class templates shadow function
<h3><a name="err_msvc_class_template">MSVC specific: class templates shadow function
templates</a></h3>
<p>On MSVC (up to version 7.0), a nested class template named <b>bind</b> will
shadow the function template <b>boost::bind</b>, breaking the <tt>bind&lt;R&gt;(f,
...)</tt> syntax. Unfortunately, some libraries contain nested class
templates named <b>bind</b> (ironically, such code is often an MSVC specific
<p>On MSVC (up to version 7.0), a nested class template named <b>bind</b> will
shadow the function template <b>boost::bind</b>, breaking the <tt>bind&lt;R&gt;(f,
...)</tt> syntax. Unfortunately, some libraries contain nested class
templates named <b>bind</b> (ironically, such code is often an MSVC specific
workaround.)</p>
<P>The workaround is to use the alternative <tt>bind(type&lt;R&gt;(), f, ...)</tt> syntax.</P>
<h3><a name="err_msvc_ellipsis">MSVC specific: ... in signatures treated as type</a></h3>
<p>MSVC (up to version 7.0) treats the ellipsis in a variable argument function
(such as <b>std::printf</b>) as a type. Therefore, it will accept the
<p>MSVC (up to version 7.0) treats the ellipsis in a variable argument function
(such as <b>std::printf</b>) as a type. Therefore, it will accept the
(incorrect in the current implementation) form:
</p>
<pre> bind(printf, "%s\n", _1);
@@ -629,10 +631,10 @@ namespace
<h3><a name="CommonRequirements">Common requirements</a></h3>
<p>All <tt><i>unspecified-N</i></tt> types returned by <b>bind</b> are <b>CopyConstructible</b>.
<tt><i>unspecified-N</i>::result_type</tt> is defined as the return type of <tt><i>unspecified-N</i>::operator()</tt>.</p>
<p>All <tt><i>unspecified-placeholder-N</i></tt> types are <b>CopyConstructible</b>.
<p>All <tt><i>unspecified-placeholder-N</i></tt> types are <b>CopyConstructible</b>.
Their copy constructors do not throw exceptions.</p>
<h3><a name="CommonDefinitions">Common definitions</a></h3>
<p>The function <20>(x, v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>), where m is
<p>The function <20>(x, v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>), where m is
a nonnegative integer, is defined as:</p>
<ul>
<li>
@@ -642,81 +644,81 @@ namespace
v<sub>k</sub>, when <tt>x</tt>
is (a copy of) the placeholder _k for some positive integer k;
<li>
<tt>x(v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>)</tt> when <tt>x</tt> is
<tt>x(v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>)</tt> when <tt>x</tt> is
(a copy of) a function object returned by <b>bind</b>;
<li>
<tt>x</tt> otherwise.</li></ul>
<h3><a name="bind">bind</a></h3>
<h4><a name="bind_1">template&lt;class R, class F&gt; <i>unspecified-1</i> bind(F f)</a></h4>
<blockquote>
<p><b>Returns:</b> A function object <i>&#955;</i> such that the expression <tt>&#955;(v<sub>1</sub>,
v<sub>2</sub>, ..., v<sub>m</sub>)</tt> is equivalent to <tt><b>f</b>()</tt>,
<p><b>Returns:</b> A function object <i>&#955;</i> such that the expression <tt>&#955;(v<sub>1</sub>,
v<sub>2</sub>, ..., v<sub>m</sub>)</tt> is equivalent to <tt><b>f</b>()</tt>,
implicitly converted to <b>R</b>.</p>
<p><b>Throws:</b> Nothing unless the copy constructor of <b>F</b> throws an
<p><b>Throws:</b> Nothing unless the copy constructor of <b>F</b> throws an
exception.</p>
</blockquote>
<h4><a name="bind_1_1">template&lt;class F&gt; <i>unspecified-1-1</i> bind(F f)</a></h4>
<blockquote>
<p><b>Effects:</b> Equivalent to <tt>bind&lt;typename F::result_type, F&gt;(f);</tt></p>
<p><b>Notes:</b> Implementations are allowed to infer the return type of <b>f</b> via
<p><b>Notes:</b> Implementations are allowed to infer the return type of <b>f</b> via
other means as an extension, without relying on the <tt>result_type</tt> member.</p>
</blockquote>
<h4><a name="bind_2">template&lt;class R&gt; <i>unspecified-2</i> bind(R (*f) ())</a></h4>
<blockquote>
<p><b>Returns:</b> A function object <i>&#955;</i> such that the expression <tt>&#955;(v<sub>1</sub>,
<p><b>Returns:</b> A function object <i>&#955;</i> such that the expression <tt>&#955;(v<sub>1</sub>,
v<sub>2</sub>, ..., v<sub>m</sub>)</tt> is equivalent to <tt><b>f</b>()</tt>.</p>
<p><b>Throws:</b> Nothing.</p>
</blockquote>
<h4><a name="bind_3">template&lt;class R, class F, class A1&gt; <i>unspecified-3</i> bind(F
<h4><a name="bind_3">template&lt;class R, class F, class A1&gt; <i>unspecified-3</i> bind(F
f, A1 a1)</a></h4>
<blockquote>
<p><b>Returns:</b> A function object <i>&#955;</i> such that the expression <tt>&#955;(v<sub>1</sub>,
v<sub>2</sub>, ..., v<sub>m</sub>)</tt> is equivalent to <tt><b>f</b>(<28>(<b>a1</b>,
v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>))</tt>, implicitly
<p><b>Returns:</b> A function object <i>&#955;</i> such that the expression <tt>&#955;(v<sub>1</sub>,
v<sub>2</sub>, ..., v<sub>m</sub>)</tt> is equivalent to <tt><b>f</b>(<28>(<b>a1</b>,
v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>))</tt>, implicitly
converted to <b>R</b>.</p>
<p><b>Throws:</b> Nothing unless the copy constructors of <b>F</b> or <b>A1</b> throw
<p><b>Throws:</b> Nothing unless the copy constructors of <b>F</b> or <b>A1</b> throw
an exception.</p>
</blockquote>
<h4><a name="bind_3_1">template&lt;class F, class A1&gt; <i>unspecified-3-1</i> bind(F
<h4><a name="bind_3_1">template&lt;class F, class A1&gt; <i>unspecified-3-1</i> bind(F
f, A1 a1)</a></h4>
<blockquote>
<p><b>Effects:</b> Equivalent to <tt>bind&lt;typename F::result_type, F, A1&gt;(f, a1);</tt></p>
<p><b>Notes:</b> Implementations are allowed to infer the return type of <b>f</b> via
<p><b>Notes:</b> Implementations are allowed to infer the return type of <b>f</b> via
other means as an extension, without relying on the <tt>result_type</tt> member.</p>
</blockquote>
<h4><a name="bind_4">template&lt;class R, class B1, class A1&gt; <i>unspecified-4</i> bind(R
<h4><a name="bind_4">template&lt;class R, class B1, class A1&gt; <i>unspecified-4</i> bind(R
(*f) (B1), A1 a1)</a></h4>
<blockquote>
<p><b>Returns:</b> A function object <i>&#955;</i> such that the expression <tt>&#955;(v<sub>1</sub>,
v<sub>2</sub>, ..., v<sub>m</sub>)</tt> is equivalent to <tt><b>f</b>(<28>(<b>a1</b>,
<p><b>Returns:</b> A function object <i>&#955;</i> such that the expression <tt>&#955;(v<sub>1</sub>,
v<sub>2</sub>, ..., v<sub>m</sub>)</tt> is equivalent to <tt><b>f</b>(<28>(<b>a1</b>,
v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>))</tt>.</p>
<p><b>Throws:</b> Nothing unless the copy constructor of <b>A1</b> throws an
<p><b>Throws:</b> Nothing unless the copy constructor of <b>A1</b> throws an
exception.</p>
</blockquote>
<h4><a name="bind_5">template&lt;class R, class T, class A1&gt; <i>unspecified-5</i> bind(R
<h4><a name="bind_5">template&lt;class R, class T, class A1&gt; <i>unspecified-5</i> bind(R
(T::*f) (), A1 a1)</a></h4>
<blockquote>
<p><b>Effects:</b> Equivalent to <tt>bind&lt;R&gt;(<A href="mem_fn.html">boost::mem_fn</A>(f),
<p><b>Effects:</b> Equivalent to <tt>bind&lt;R&gt;(<A href="mem_fn.html">boost::mem_fn</A>(f),
a1);</tt></p>
</blockquote>
<h4><a name="bind_6">template&lt;class R, class T, class A1&gt; <i>unspecified-6</i> bind(R
<h4><a name="bind_6">template&lt;class R, class T, class A1&gt; <i>unspecified-6</i> bind(R
(T::*f) () const, A1 a1)</a></h4>
<blockquote>
<p><b>Effects:</b> Equivalent to <tt>bind&lt;R&gt;(<A href="mem_fn.html">boost::mem_fn</A>(f),
<p><b>Effects:</b> Equivalent to <tt>bind&lt;R&gt;(<A href="mem_fn.html">boost::mem_fn</A>(f),
a1);</tt></p>
</blockquote>
<h4><a name="bind_6_1">template&lt;class R, class T, class A1&gt; <i>unspecified-6-1</i>
bind(R T::*f, A1 a1)</a></h4>
<blockquote>
<p><b>Effects:</b> Equivalent to <tt>bind&lt;R&gt;(<A href="mem_fn.html">boost::mem_fn</A>(f),
<p><b>Effects:</b> Equivalent to <tt>bind&lt;R&gt;(<A href="mem_fn.html">boost::mem_fn</A>(f),
a1);</tt></p>
</blockquote>
<h4><a name="bind_7">template&lt;class R, class F, class A1, class A2&gt; <i>unspecified-7</i>
bind(F f, A1 a1, A2 a2)</a></h4>
<blockquote>
<p><b>Returns:</b> A function object <i>&#955;</i> such that the expression <tt>&#955;(v<sub>1</sub>,
v<sub>2</sub>, ..., v<sub>m</sub>)</tt> is equivalent to <tt><b>f</b>(<28>(<b>a1</b>,
v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>), <20>(<b>a2</b>, v<sub>1</sub>,
<p><b>Returns:</b> A function object <i>&#955;</i> such that the expression <tt>&#955;(v<sub>1</sub>,
v<sub>2</sub>, ..., v<sub>m</sub>)</tt> is equivalent to <tt><b>f</b>(<28>(<b>a1</b>,
v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>), <20>(<b>a2</b>, v<sub>1</sub>,
v<sub>2</sub>, ..., v<sub>m</sub>))</tt>, implicitly converted to <b>R</b>.</p>
<p><b>Throws:</b> Nothing unless the copy constructors of <b>F</b>, <b>A1</b> or <b>A2</b>
throw an exception.</p>
@@ -724,35 +726,35 @@ namespace
<h4><a name="bind_7_1">template&lt;class F, class A1, class A2&gt; <i>unspecified-7-1</i>
bind(F f, A1 a1, A2 a2)</a></h4>
<blockquote>
<p><b>Effects:</b> Equivalent to <tt>bind&lt;typename F::result_type, F, A1, A2&gt;(f,
<p><b>Effects:</b> Equivalent to <tt>bind&lt;typename F::result_type, F, A1, A2&gt;(f,
a1, a2);</tt></p>
<p><b>Notes:</b> Implementations are allowed to infer the return type of <b>f</b> via
<p><b>Notes:</b> Implementations are allowed to infer the return type of <b>f</b> via
other means as an extension, without relying on the <tt>result_type</tt> member.</p>
</blockquote>
<h4><a name="bind_8">template&lt;class R, class B1, class B2, class A1, class A2&gt; <i>unspecified-8</i>
bind(R (*f) (B1, B2), A1 a1, A2 a2)</a></h4>
<blockquote>
<p><b>Returns:</b> A function object <i>&#955;</i> such that the expression <tt>&#955;(v<sub>1</sub>,
v<sub>2</sub>, ..., v<sub>m</sub>)</tt> is equivalent to <tt><b>f</b>(<28>(<b>a1</b>,
v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>), <20>(<b>a2</b>, v<sub>1</sub>,
<p><b>Returns:</b> A function object <i>&#955;</i> such that the expression <tt>&#955;(v<sub>1</sub>,
v<sub>2</sub>, ..., v<sub>m</sub>)</tt> is equivalent to <tt><b>f</b>(<28>(<b>a1</b>,
v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>), <20>(<b>a2</b>, v<sub>1</sub>,
v<sub>2</sub>, ..., v<sub>m</sub>))</tt>.</p>
<p><b>Throws:</b> Nothing unless the copy constructors of <b>A1</b> or <b>A2</b> throw
<p><b>Throws:</b> Nothing unless the copy constructors of <b>A1</b> or <b>A2</b> throw
an exception.</p>
</blockquote>
<h4><a name="bind_9">template&lt;class R, class T, class B1, class A1, class A2&gt; <i>unspecified-9</i>
bind(R (T::*f) (B1), A1 a1, A2 a2)</a></h4>
<blockquote>
<p><b>Effects:</b> Equivalent to <tt>bind&lt;R&gt;(<A href="mem_fn.html">boost::mem_fn</A>(f),
<p><b>Effects:</b> Equivalent to <tt>bind&lt;R&gt;(<A href="mem_fn.html">boost::mem_fn</A>(f),
a1, a2);</tt></p>
</blockquote>
<h4><a name="bind_10">template&lt;class R, class T, class B1, class A1, class A2&gt; <i>unspecified-10</i>
bind(R (T::*f) (B1) const, A1 a1, A2 a2)</a></h4>
<blockquote>
<p><b>Effects:</b> Equivalent to <tt>bind&lt;R&gt;(<A href="mem_fn.html">boost::mem_fn</A>(f),
<p><b>Effects:</b> Equivalent to <tt>bind&lt;R&gt;(<A href="mem_fn.html">boost::mem_fn</A>(f),
a1, a2);</tt></p>
</blockquote>
<h3><a name="AdditionalOverloads">Additional overloads</a></h3>
<p>Implementations are allowed to provide additional <b>bind</b> overloads in order
<p>Implementations are allowed to provide additional <b>bind</b> overloads in order
to support more arguments or different function pointer variations.</p>
<h2><a name="Implementation">Implementation</a></h2>
<h3><a name="Files">Files</a></h3>
@@ -782,7 +784,7 @@ namespace
<A href="../../boost/bind/protect.hpp">boost/bind/protect.hpp</A> (<STRONG>protect</STRONG>
helper function)
<LI>
<A href="../../boost/bind/make_adaptable.hpp">boost/bind/make_adaptable.hpp</A>
<A href="../../boost/bind/make_adaptable.hpp">boost/bind/make_adaptable.hpp</A>
(<STRONG>make_adaptable</STRONG>
helper function)
<li>
@@ -818,19 +820,19 @@ namespace
<A href="../../boost/type.hpp">boost/type.hpp</A></li>
</ul>
<h3><a name="NumberOfArguments">Number of Arguments</a></h3>
<p>This implementation supports function objects with up to nine arguments. This is
<p>This implementation supports function objects with up to nine arguments. This is
an implementation detail, not an inherent limitation of the design.</p>
<h3><a name="stdcall">"__stdcall", "__cdecl", "__fastcall", and "pascal" Support</a></h3>
<p>Some platforms allow several types of (member) functions that differ by their <b>calling
convention</b> (the rules by which the function is invoked: how are
arguments passed, how is the return value handled, and who cleans up the stack
<p>Some platforms allow several types of (member) functions that differ by their <b>calling
convention</b> (the rules by which the function is invoked: how are
arguments passed, how is the return value handled, and who cleans up the stack
- if any.)</p>
<p>For example, Windows API functions and COM interface member functions use a
calling convention known as <b>__stdcall</b>.Borland VCL components use <STRONG>__fastcall</STRONG>.
<p>For example, Windows API functions and COM interface member functions use a
calling convention known as <b>__stdcall</b>.Borland VCL components use <STRONG>__fastcall</STRONG>.
Mac toolbox functions use a <b>pascal</b> calling convention.</p>
<p>To use <b>bind</b> with <b>__stdcall</b> functions, <b>#define</b> the macro <b>BOOST_BIND_ENABLE_STDCALL</b>
before including <b>&lt;boost/bind.hpp&gt;</b>.</p>
<p>To use <b>bind</b> with <b>__stdcall</b> <b>member</b> functions, <b>#define</b>
<p>To use <b>bind</b> with <b>__stdcall</b> <b>member</b> functions, <b>#define</b>
the macro <b>BOOST_MEM_FN_ENABLE_STDCALL</b> before including <b>&lt;boost/bind.hpp&gt;</b>.</p>
<P>To use <B>bind</B> with <B>__fastcall</B> functions, <B>#define</B> the macro <B>BOOST_BIND_ENABLE_FASTCALL</B>
before including <B>&lt;boost/bind.hpp&gt;</B>.</P>
@@ -838,16 +840,16 @@ namespace
the macro <B>BOOST_MEM_FN_ENABLE_FASTCALL</B> before including <B>&lt;boost/bind.hpp&gt;</B>.</P>
<P>To use <b>bind</b> with <b>pascal</b> functions, <b>#define</b> the macro <b>BOOST_BIND_ENABLE_PASCAL</b>
before including <b>&lt;boost/bind.hpp&gt;</b>.</P>
<P>To use <B>bind</B> with <B>__cdecl</B> <B>member</B> functions, <B>#define</B> the
<P>To use <B>bind</B> with <B>__cdecl</B> <B>member</B> functions, <B>#define</B> the
macro <B>BOOST_MEM_FN_ENABLE_CDECL</B> before including <B>&lt;boost/bind.hpp&gt;</B>.</P>
<P><STRONG>It is best to define these macros in the project options, via -D on the
command line, or as the first line in the translation unit (.cpp file) where
bind is used.</STRONG> Not following this rule can lead to obscure errors
<P><STRONG>It is best to define these macros in the project options, via -D on the
command line, or as the first line in the translation unit (.cpp file) where
bind is used.</STRONG> Not following this rule can lead to obscure errors
when a header includes bind.hpp before the macro has been defined.</P>
<p>[Note: this is a non-portable extension. It is not part of the interface.]</p>
<p>[Note: Some compilers provide only minimal support for the <b>__stdcall</b> keyword.]</p>
<h3><a name="visit_each"><b>visit_each</b> support</a></h3>
<p>Function objects returned by <b>bind</b> support the experimental and
<p>Function objects returned by <b>bind</b> support the experimental and
undocumented, as of yet, <b>visit_each</b> enumeration interface.</p>
<p>See <A href="bind_visitor.cpp">bind_visitor.cpp</A> for an example.</p>
<h2><a name="Acknowledgements">Acknowledgements</a></h2>
@@ -858,40 +860,40 @@ namespace
by Jaakko J<>rvi;
<li>
The <a href="../lambda/">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
<a href="http://more.sourceforge.net/">Extensions to the
STL</a> by Petter Urkedal.</li></ul>
<p>Doug Gregor suggested that a visitor mechanism would allow <b>bind</b> to
<p>Doug Gregor suggested that a visitor mechanism would allow <b>bind</b> to
interoperate with a signal/slot library.</p>
<p>John Maddock fixed a MSVC-specific conflict between <b>bind</b> and the <A href="../type_traits/index.html">
type traits library</A>.</p>
<p>Numerous improvements were suggested during the formal review period by Ross
Smith, Richard Crossley, Jens Maurer, Ed Brey, and others. Review manager was
<p>Numerous improvements were suggested during the formal review period by Ross
Smith, Richard Crossley, Jens Maurer, Ed Brey, and others. Review manager was
Darin Adler.
</p>
<p>The precise semantics of <b>bind</b> were refined in discussions with Jaakko
<p>The precise semantics of <b>bind</b> were refined in discussions with Jaakko
J<>rvi.
</p>
<p>Dave Abrahams fixed a MSVC-specific conflict between <b>bind</b> and the <A href="../utility/iterator_adaptors.htm">
iterator adaptors library</A>.
</p>
<p>Dave Abrahams modified <b>bind</b> and <b>mem_fn</b> to support void returns on
<p>Dave Abrahams modified <b>bind</b> and <b>mem_fn</b> to support void returns on
deficient compilers.
</p>
<p>Mac Murrett contributed the "pascal" support enabled by
<p>Mac Murrett contributed the "pascal" support enabled by
BOOST_BIND_ENABLE_PASCAL.
</p>
<p>The alternative <tt>bind(type&lt;R&gt;(), f, ...)</tt> syntax was inspired by a
<p>The alternative <tt>bind(type&lt;R&gt;(), f, ...)</tt> syntax was inspired by a
discussion with Dave Abrahams and Joel de Guzman.</p>
<p><br>
<br>
<br>
<small>Copyright <20> 2001, 2002 by Peter Dimov and Multi Media Ltd. Copyright
2003-2005 Peter Dimov. Permission to copy, use, modify, sell and distribute
this document is granted provided this copyright notice appears in all copies.
This document is provided "as is" without express or implied warranty, and with
<small>Copyright <20> 2001, 2002 by Peter Dimov and Multi Media Ltd. Copyright
2003-2005 Peter Dimov. Permission to copy, use, modify, sell and distribute
this document is granted provided this copyright notice appears in all copies.
This document is provided "as is" without express or implied warranty, and with
no claim as to its suitability for any purpose.</small></p>
</body>
</html>