diff options
| author | Lorry Tar Creator <lorry-tar-importer@baserock.org> | 2015-04-08 03:09:47 +0000 |
|---|---|---|
| committer | <> | 2015-05-05 14:37:32 +0000 |
| commit | f2541bb90af059680aa7036f315f052175999355 (patch) | |
| tree | a5b214744b256f07e1dc2bd7273035a7808c659f /libs/bind | |
| parent | ed232fdd34968697a68783b3195b1da4226915b5 (diff) | |
| download | boost-tarball-master.tar.gz | |
Imported from /home/lorry/working-area/delta_boost-tarball/boost_1_58_0.tar.bz2.HEADboost_1_58_0master
Diffstat (limited to 'libs/bind')
30 files changed, 4641 insertions, 1401 deletions
diff --git a/libs/bind/bind.html b/libs/bind/bind.html index fc4756f2e..bcc5add98 100644 --- a/libs/bind/bind.html +++ b/libs/bind/bind.html @@ -1,997 +1,28 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<!DOCTYPE html> <html> - <head> - <title>Boost: bind.hpp documentation</title> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - </head> - <body style="MARGIN-LEFT: 5%; MARGIN-RIGHT: 5%" bgColor="white"> - <table width="100%" border="0"> - <tr> - <td width="277"><A href="../../index.htm"><IMG height="86" alt="boost.png (6897 bytes)" src="../../boost.png" width="277" border="0"></A> - </td> - <td align="center"> - <h1>bind.hpp</h1> - </td> - </tr> - <tr> - <td colSpan="2" height="64"> </td> - </tr> - </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 - function pointers</A></h4> - <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 - to members</A></h4> - <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 - algorithms</A></h4> - <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 - should not.</A></h4> - <h4 style="MARGIN-LEFT: 40pt"><A href="#Q_forms">What is the difference between bind(f, - ...) and bind<R>(f, ...)?</A></h4> - <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 - functions?</A></h4> - <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 - 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 - called with the specified arguments</A></h4> - <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, - ...)</A></h4> - <h4 style="MARGIN-LEFT: 40pt"><A href="#err_long_form">Inappropriate use of - bind<R>(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_modeling_stl_function_object_concepts">Modeling STL function object concepts</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> - <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 - 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> - <h4 style="MARGIN-LEFT: 40pt"><A href="#CommonRequirements">Common requirements</A></h4> - <h4 style="MARGIN-LEFT: 40pt"><A href="#CommonDefinitions">Common definitions</A></h4> - <h4 style="MARGIN-LEFT: 40pt"><A href="#bind">bind</A></h4> - <h4 style="MARGIN-LEFT: 40pt"><A href="#AdditionalOverloads">Additional overloads</A></h4> - <h3 style="MARGIN-LEFT: 20pt"><A href="#Implementation">Implementation</A></h3> - <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", - 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 - 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 - not need the <b>result_type</b>, <b>first_argument_type</b> and <b>second_argument_type</b> - standard typedefs. - </p> - <h3><a name="with_functions">Using bind with functions and function pointers</a></h3> - <p>Given these definitions: - </p> - <pre>int f(int a, int b) -{ - return a + b; -} - -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 - 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 - argument." - <p>For comparison, here is the same operation expressed with the standard library - primitives: - </p> - <pre>std::bind2nd(std::ptr_fun(f), 5)(x); -</pre> - <p><b>bind</b> covers the functionality of <b>std::bind1st</b> as well: - </p> - <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 - substitution mechanism is more general: - </p> - <pre>bind(f, _2, _1)(x, y); // f(y, x) - -bind(g, _1, 9, _1)(x); // g(x, 9, x) - -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 - the third example. - </p> - <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; - -bind(f, i, _1); -</pre> - <p>a copy of the value of <b>i</b> is stored into the function object. <A href="../core/doc/html/core/ref.html"> - boost::ref</A> and <A href="../core/doc/html/core/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. - 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 - type cannot be inferred): - </p> - <pre>struct F -{ - int operator()(int a, int b) { return a - b; } - bool operator()(long a, long b) { return a == b; } -}; - -F f; - -int x = 104; - -bind<int>(f, _1, _1)(x); // f(x, x), i.e. zero -</pre> - <p>Some compilers have trouble with the <tt>bind<R>(f, ...)</tt> syntax. For - portability reasons, an alternative way to express the above is supported:</p> - <pre>boost::bind(boost::type<int>(), f, _1, _1)(x); -</pre> - <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 - explicit return type can be omitted: - </P> - <pre>int x = 8; - -bind(std::less<int>(), _1, 9)(x); // x < 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> - 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 - function object. In other words, the expression - </p> - <pre>bind(&X::f, <i>args</i>) -</pre> - <p>is equivalent to - </p> - <pre>bind<R>(<A href="mem_fn.html" >mem_fn</A>(&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 - 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 - additional information, see the <b>mem_fn</b> <A href="mem_fn.html">documentation</A>.] - </p> - <p>Example: - </p> - <pre>struct X -{ - bool f(int a); -}; - -X x; - -shared_ptr<X> p(new X); - -int i = 5; - -bind(&X::f, ref(x), _1)(i); // x.f(i) -bind(&X::f, &x, _1)(i); //(&x)->f(i) -bind(&X::f, x, _1)(i); // (<i>internal copy of x</i>).f(i) -bind(&X::f, p, _1)(i); // (<i>internal copy of p</i>)->f(i) -</pre> - <p>The last two examples are interesting in that they produce "self-contained" - function objects. <tt>bind(&X::f, x, _1)</tt> stores a copy of <b>x</b>. <tt>bind(&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 - 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 - 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 - 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 - 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="http://www.boost.org/doc/libs/1_31_0/libs/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 - placeholder argument, so the example below does not work as expected: - </p> - <pre>typedef void (*pf)(int); - -std::vector<pf> 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 - the modified version of the previous example looks like: - </p> - <pre>typedef void (*pf)(int); - -std::vector<pf> v; - -std::for_each(v.begin(), v.end(), bind(apply<void>(), _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 - 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 - 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 <code>!</code> and the relational and logical operators <code>==</code>, - <code>!=</code>, <code><</code>, <code><=</code>, <code>></code>, <code>>=</code>, - <code>&&</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>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( &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( &X::name, _1 ) == "Peter" );</tt></P> - <P><tt>std::find_if( first, last, bind( &X::name, _1 ) == "Peter" || bind( - &X::name, _1 ) == "Paul" );</tt></P> - <P>against a placeholder:</P> - <P><tt>bind( &X::name, _1 ) == _2</tt></P> - <P>or against another <tt>bind</tt> expression:</P> - <P><tt>std::sort( first, last, bind( &X::name, _1 ) < bind( &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> - <pre>class image; - -class animation -{ -public: - - void advance(int ms); - bool inactive() const; - void render(image & target) const; -}; - -std::vector<animation> anims; - -template<class C, class P> void erase_if(C & c, P pred) -{ - c.erase(std::remove_if(c.begin(), c.end(), pred), c.end()); -} - -void update(int ms) -{ - std::for_each(anims.begin(), anims.end(), boost::bind(&animation::advance, _1, ms)); - erase_if(anims, boost::mem_fn(&animation::inactive)); -} - -void render(image & target) -{ - std::for_each(anims.begin(), anims.end(), boost::bind(&animation::render, _1, boost::ref(target))); -} -</pre> - <h3><a name="with_boost_function">Using bind with Boost.Function</a></h3> - <pre>class button -{ -public: - - <A href="../function/index.html" >boost::function</A><void()> onClick; -}; - -class player -{ -public: - - void play(); - void stop(); -}; - -button playButton, stopButton; -player thePlayer; - -void connect() -{ - playButton.onClick = boost::bind(&player::play, &thePlayer); - stopButton.onClick = boost::bind(&player::stop, &thePlayer); -} -</pre> - <h2><a name="Limitations">Limitations</a></h2> - <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://www.open-std.org/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<class T> void f(T & t); -</pre> - <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>On compilers that support partial ordering of function templates, a possible - solution is to add an overload: - </p> - <pre>template<class T> void f(T & t); -template<class T> void f(T const & t); -</pre> - <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> - <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<R>(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<R>(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 - 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<int>(printf, ...)</tt>. Note that an alternative <tt>bind(type<R>(), - 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 - 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 - function object</A> and use the <tt>bind<R>(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 - function object</A> and use the <tt>bind<R>(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 - function object</A> and use the <tt>bind<R>(f, ...)</tt> syntax.</p> - <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 - 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 - where bind() is invoked:</p> - <pre>int f(int, int); - -int main() -{ - boost::bind(f, 1); // error, f takes two arguments - boost::bind(f, 1, 2); // OK -} -</pre> - <p>A common variation of this error is to forget that member functions have an - implicit "this" argument:</p> - <pre>struct X -{ - int f(int); -} - -int main() -{ - boost::bind(&X::f, 1); // error, X::f takes two arguments - boost::bind(&X::f, <b>_1</b>, 1); // OK -} -</pre> - <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 - 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_]); -</pre> - <p>An example of this kind of error:</p> - <pre>int f(int); - -int main() -{ - boost::bind(f, "incompatible"); // OK so far, no call - boost::bind(f, "incompatible")(); // error, "incompatible" is not an int - boost::bind(f, _1); // OK - boost::bind(f, _1)("incompatible"); // error, "incompatible" is not an int -} -</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 - access beyond the end of this list:</p> - <pre>int f(int); - -int main() -{ - boost::bind(f, _1); // OK - boost::bind(f, _1)(); // error, there is no argument number 1 -} -</pre> - <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 - 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 - 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 - for function objects.</p> - <h3><a name="err_long_form">Inappropriate use of bind<R>(f, ...)</a></h3> - <p>The <tt>bind<R>(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 - 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<R>(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 - 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& get(); - int const& get() const; -}; - -int main() -{ - boost::bind( &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< int const& (X::*) () const >( &X::get ), _1 ); -} -</pre> - <P>Another, arguably more readable, alternative is to introduce a temporary - variable:</P> -<pre>int main() -{ - int const& (X::*get) () const = &X::get; - boost::bind( get, _1 ); -} -</pre> - <h3><a name="err_modeling_stl_function_object_concepts">Modeling STL function object concepts</a></h3> - <p>The function objects that are produced by <b>boost::bind</b> do not model the - STL <a href="http://www.sgi.com/tech/stl/UnaryFunction.html">Unary Function</a> or - <a href="http://www.sgi.com/tech/stl/BinaryFunction.html">Binary Function</a> concepts, - even when the function objects are unary or binary operations, because the function object - types are missing public typedefs <tt>result_type</tt> and <tt>argument_type</tt> or - <tt>first_argument_type</tt> and <tt>second_argument_type</tt>. In cases where these - typedefs are desirable, however, the utility function <tt>make_adaptable</tt> - can be used to adapt unary and binary function objects to these concepts. This allows - unary and binary function objects resulting from <b>boost::bind</b> to be combined with - STL templates such as <a href="http://msdn.microsoft.com/en-us/library/se0409db%28v=VS.90%29.aspx"><tt>std::unary_negate</tt></a> - and <a href="http://msdn.microsoft.com/en-us/library/833073z4%28v=VS.90%29.aspx"><tt>std::binary_negate</tt></a>.</p> - - <p>The <tt>make_adaptable</tt> function is defined in <<a href="../../boost/bind/make_adaptable.hpp">boost/bind/make_adaptable.hpp</a>>, - which must be included explicitly in addition to <boost/bind.hpp>:</p> - <pre> -#include <boost/bind/make_adaptable.hpp> - -template <class R, class F> <i>unspecified-type</i> make_adaptable(F f); - -template<class R, class A1, class F> <i>unspecified-unary-functional-type</i> make_adaptable(F f); - -template<class R, class A1, class A2, class F> <i>unspecified-binary-functional-type</i> make_adaptable(F f); - -template<class R, class A1, class A2, class A3, class F> <i>unspecified-ternary-functional-type</i> make_adaptable(F f); - -template<class R, class A1, class A2, class A3, class A4, class F> <i>unspecified-4-ary-functional-type</i> make_adaptable(F f); - </pre> - - <p>This example shows how to use <tt>make_adaptable</tt> to make a predicate for "is not a space":</p> - <pre>typedef char char_t; -std::locale loc(""); -const std::ctype<char_t>& ct = std::use_facet<std::ctype<char_t> >(loc); - -auto isntspace = std::not1( boost::make_adaptable<bool, char_t>( boost::bind(&std::ctype<char_t>::is, &ct, std::ctype_base::space, _1) ) ); -</pre> - - <p>In this example, <b>boost::bind</b> creates the "is a space" (unary) predicate. - It is then passed to <tt>make_adaptable</tt> so that a function object modeling - the Unary Function concept can be created, serving as the argument to - <a href="http://msdn.microsoft.com/en-us/library/syyszzf8%28v=VS.90%29.aspx"><tt>std::not1</tt></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 - top-level <b>const</b> in function signatures: - </p> - <pre>int f(int const); - -int main() -{ - boost::bind(f, 1); // error -} -</pre> - <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 - an using declaration: - </p> - <pre>using boost::bind; -</pre> - <p>the syntax <tt>bind<R>(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 - 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<R>(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<R>(), 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 - (incorrect in the current implementation) form: - </p> - <pre> bind(printf, "%s\n", _1); -</pre> - <p>and will reject the correct version: - </p> - <pre> bind<int>(printf, "%s\n", _1); -</pre> - <h2><a name="Interface">Interface</a></h2> - <h3><a name="Synopsis">Synopsis</a></h3> - <pre>namespace boost -{ - -// no arguments - -template<class R, class F> <i>unspecified-1</i> <A href="#bind_1" >bind</A>(F f); - -template<class F> <i>unspecified-1-1</i> <A href="#bind_1_1" >bind</A>(F f); - -template<class R> <i>unspecified-2</i> <A href="#bind_2" >bind</A>(R (*f) ()); - -// one argument - -template<class R, class F, class A1> <i>unspecified-3</i> <A href="#bind_3" >bind</A>(F f, A1 a1); - -template<class F, class A1> <i>unspecified-3-1</i> <A href="#bind_3_1" >bind</A>(F f, A1 a1); - -template<class R, class B1, class A1> <i>unspecified-4</i> <A href="#bind_4" >bind</A>(R (*f) (B1), A1 a1); - -template<class R, class T, class A1> <i>unspecified-5</i> <A href="#bind_5" >bind</A>(R (T::*f) (), A1 a1); - -template<class R, class T, class A1> <i>unspecified-6</i> <A href="#bind_6" >bind</A>(R (T::*f) () const, A1 a1); - -template<class R, class T, class A1> <i>unspecified-6-1</i> <A href="#bind_6_1" >bind</A>(R T::*f, A1 a1); - -// two arguments - -template<class R, class F, class A1, class A2> <i>unspecified-7</i> <A href="#bind_7" >bind</A>(F f, A1 a1, A2 a2); - -template<class F, class A1, class A2> <i>unspecified-7-1</i> <A href="#bind_7_1" >bind</A>(F f, A1 a1, A2 a2); - -template<class R, class B1, class B2, class A1, class A2> <i>unspecified-8</i> <A href="#bind_8" >bind</A>(R (*f) (B1, B2), A1 a1, A2 a2); - -template<class R, class T, class B1, class A1, class A2> <i>unspecified-9</i> <A href="#bind_9" >bind</A>(R (T::*f) (B1), A1 a1, A2 a2); - -template<class R, class T, class B1, class A1, class A2> <i>unspecified-10</i> <A href="#bind_10" >bind</A>(R (T::*f) (B1) const, A1 a1, A2 a2); - -// implementation defined number of additional overloads for more arguments - -} - -namespace -{ - -<i>unspecified-placeholder-type-1</i> _1; - -<i>unspecified-placeholder-type-2</i> _2; - -<i>unspecified-placeholder-type-3</i> _3; - -// implementation defined number of additional placeholder definitions - -} -</pre> - <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>. - Their copy constructors do not throw exceptions.</p> - <h3><a name="CommonDefinitions">Common definitions</a></h3> - <p>The function µ(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> - <tt>x.get()</tt>, when <tt>x</tt> is of type <tt><A href="../core/doc/html/core/ref.html">boost::reference_wrapper</A><T></tt> - for some type <tt>T</tt>; - <li> - 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 - (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<class R, class F> <i>unspecified-1</i> bind(F f)</a></h4> - <blockquote> - <p><b>Returns:</b> A function object <i>λ</i> such that the expression <tt>λ(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 - exception.</p> - </blockquote> - <h4><a name="bind_1_1">template<class F> <i>unspecified-1-1</i> bind(F f)</a></h4> - <blockquote> - <p><b>Effects:</b> Equivalent to <tt>bind<typename F::result_type, F>(f);</tt></p> - <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<class R> <i>unspecified-2</i> bind(R (*f) ())</a></h4> - <blockquote> - <p><b>Returns:</b> A function object <i>λ</i> such that the expression <tt>λ(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<class R, class F, class A1> <i>unspecified-3</i> bind(F - f, A1 a1)</a></h4> - <blockquote> - <p><b>Returns:</b> A function object <i>λ</i> such that the expression <tt>λ(v<sub>1</sub>, - v<sub>2</sub>, ..., v<sub>m</sub>)</tt> is equivalent to <tt><b>f</b>(µ(<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 - an exception.</p> - </blockquote> - <h4><a name="bind_3_1">template<class F, class A1> <i>unspecified-3-1</i> bind(F - f, A1 a1)</a></h4> - <blockquote> - <p><b>Effects:</b> Equivalent to <tt>bind<typename F::result_type, F, A1>(f, a1);</tt></p> - <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<class R, class B1, class A1> <i>unspecified-4</i> bind(R - (*f) (B1), A1 a1)</a></h4> - <blockquote> - <p><b>Returns:</b> A function object <i>λ</i> such that the expression <tt>λ(v<sub>1</sub>, - v<sub>2</sub>, ..., v<sub>m</sub>)</tt> is equivalent to <tt><b>f</b>(µ(<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 - exception.</p> - </blockquote> - <h4><a name="bind_5">template<class R, class T, class A1> <i>unspecified-5</i> bind(R - (T::*f) (), A1 a1)</a></h4> - <blockquote> - <p><b>Effects:</b> Equivalent to <tt>bind<R>(<A href="mem_fn.html">boost::mem_fn</A>(f), - a1);</tt></p> - </blockquote> - <h4><a name="bind_6">template<class R, class T, class A1> <i>unspecified-6</i> bind(R - (T::*f) () const, A1 a1)</a></h4> - <blockquote> - <p><b>Effects:</b> Equivalent to <tt>bind<R>(<A href="mem_fn.html">boost::mem_fn</A>(f), - a1);</tt></p> - </blockquote> - <h4><a name="bind_6_1">template<class R, class T, class A1> <i>unspecified-6-1</i> - bind(R T::*f, A1 a1)</a></h4> - <blockquote> - <p><b>Effects:</b> Equivalent to <tt>bind<R>(<A href="mem_fn.html">boost::mem_fn</A>(f), - a1);</tt></p> - </blockquote> - <h4><a name="bind_7">template<class R, class F, class A1, class A2> <i>unspecified-7</i> - bind(F f, A1 a1, A2 a2)</a></h4> - <blockquote> - <p><b>Returns:</b> A function object <i>λ</i> such that the expression <tt>λ(v<sub>1</sub>, - v<sub>2</sub>, ..., v<sub>m</sub>)</tt> is equivalent to <tt><b>f</b>(µ(<b>a1</b>, - v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>), µ(<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> - </blockquote> - <h4><a name="bind_7_1">template<class F, class A1, class A2> <i>unspecified-7-1</i> - bind(F f, A1 a1, A2 a2)</a></h4> - <blockquote> - <p><b>Effects:</b> Equivalent to <tt>bind<typename F::result_type, F, A1, A2>(f, - a1, a2);</tt></p> - <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<class R, class B1, class B2, class A1, class A2> <i>unspecified-8</i> - bind(R (*f) (B1, B2), A1 a1, A2 a2)</a></h4> - <blockquote> - <p><b>Returns:</b> A function object <i>λ</i> such that the expression <tt>λ(v<sub>1</sub>, - v<sub>2</sub>, ..., v<sub>m</sub>)</tt> is equivalent to <tt><b>f</b>(µ(<b>a1</b>, - v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>), µ(<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 - an exception.</p> - </blockquote> - <h4><a name="bind_9">template<class R, class T, class B1, class A1, class A2> <i>unspecified-9</i> - bind(R (T::*f) (B1), A1 a1, A2 a2)</a></h4> - <blockquote> - <p><b>Effects:</b> Equivalent to <tt>bind<R>(<A href="mem_fn.html">boost::mem_fn</A>(f), - a1, a2);</tt></p> - </blockquote> - <h4><a name="bind_10">template<class R, class T, class B1, class A1, class A2> <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<R>(<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 - to support more arguments or different function pointer variations.</p> - <h2><a name="Implementation">Implementation</a></h2> - <h3><a name="Files">Files</a></h3> - <ul> - <li> - <A href="../../boost/bind.hpp">boost/bind.hpp</A> - (main header) - <li> - <A href="../../boost/bind/bind_cc.hpp">boost/bind/bind_cc.hpp</A> - (used by bind.hpp, do not include directly) - <li> - <A href="../../boost/bind/bind_mf_cc.hpp">boost/bind/bind_mf_cc.hpp</A> - (used by bind.hpp, do not include directly) - <li> - <A href="../../boost/bind/bind_template.hpp">boost/bind/bind_template.hpp</A> - (used by bind.hpp, do not include directly) - <LI> - <A href="../../boost/bind/arg.hpp">boost/bind/arg.hpp</A> - (defines the type of the placeholder arguments) - <LI> - <A href="../../boost/bind/placeholders.hpp">boost/bind/placeholders.hpp</A> - (defines the _1, _2, ... _9 placeholders) - <LI> - <A href="../../boost/bind/apply.hpp">boost/bind/apply.hpp</A> (<STRONG>apply</STRONG> - helper function object) - <LI> - <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> - (<STRONG>make_adaptable</STRONG> - helper function) - <li> - <A href="test/bind_test.cpp">libs/bind/test/bind_test.cpp</A> - (test) - <li> - <A href="bind_as_compose.cpp">libs/bind/bind_as_compose.cpp</A> - (function composition example) - <li> - <A href="bind_visitor.cpp">libs/bind/bind_visitor.cpp</A> - (visitor example) - <li> - <A href="test/bind_stdcall_test.cpp">libs/bind/test/bind_stdcall_test.cpp</A> - (test with __stdcall functions) - <li> - <A href="test/bind_stdcall_mf_test.cpp">libs/bind/test/bind_stdcall_mf_test.cpp</A> - (test with __stdcall member functions) - <li> - <A href="test/bind_fastcall_test.cpp">libs/bind/test/bind_fastcall_test.cpp</A> - (test with __fastcall functions) - <li> - <A href="test/bind_fastcall_mf_test.cpp">libs/bind/test/bind_fastcall_mf_test.cpp</A> - (test with __fastcall member functions)</li></ul> - <h3><a name="Dependencies">Dependencies</a></h3> - <ul> - <li> - <A href="../config/config.htm">Boost.Config</A> - <li> - <A href="../core/doc/html/core/ref.html">boost/ref.hpp</A> - <li> - <A href="mem_fn.html">boost/mem_fn.hpp</A> - <li> - <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 - 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 - - 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>. - 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><boost/bind.hpp></b>.</p> - <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><boost/bind.hpp></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><boost/bind.hpp></B>.</P> - <P>To use <B>bind</B> with <B>__fastcall</B> <B>member</B> functions, <B>#define</B> - the macro <B>BOOST_MEM_FN_ENABLE_FASTCALL</B> before including <B><boost/bind.hpp></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><boost/bind.hpp></b>.</P> - <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><boost/bind.hpp></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 - 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 - 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> - <p>Earlier efforts that have influenced the library design:</p> - <ul> - <li> - The <a href="http://staff.cs.utu.fi/BL/">Binder Library</a> - 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 - Binder Library); - <li> - <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 - 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 - Darin Adler. - </p> - <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 - deficient compilers. - </p> - <p>Mac Murrett contributed the "pascal" support enabled by - BOOST_BIND_ENABLE_PASCAL. - </p> - <p>The alternative <tt>bind(type<R>(), f, ...)</tt> syntax was inspired by a - discussion with Dave Abrahams and Joel de Guzman.</p> - <p><br> - <br> - <br> - <small>Copyright © 2001, 2002 by Peter Dimov and Multi Media Ltd. Copyright - 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> +<head> +<title>Boost.Bind</title> +<meta charset="utf-8"> +<meta http-equiv="refresh" content="0; url=doc/html/bind.html"> +<style> + body { + background: #fff; + color: #000; + } + a { + color: #00f; + text-decoration: none; + } +</style> +</head> +<body> + <p> + Automatic redirection failed, please go to + <a href="doc/html/bind.html">doc/html/bind.html</a> + </p> + <p> + © 2001, 2002 Peter Dimov and Multi Media Ltd.<br> + © 2003-2008 Peter Dimov + </p> +</body> </html> diff --git a/libs/bind/doc/Jamfile.v2 b/libs/bind/doc/Jamfile.v2 new file mode 100644 index 000000000..c481aa611 --- /dev/null +++ b/libs/bind/doc/Jamfile.v2 @@ -0,0 +1,50 @@ +# Copyright (c) 2002 Douglas Gregor <doug.gregor -at- gmail.com> + +# Distributed under 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) + +project doc/bind ; + +import boostbook ; +import quickbook ; + +xml bind_ : bind.qbk ; +boostbook standalone_bind + : + bind_ + : + <xsl:param>boost.root=../../../.. + # File name of HTML output: + <xsl:param>root.filename=bind + # How far down we chunk nested sections, basically all of them: + <xsl:param>chunk.section.depth=0 + # Don't put the first section on the same page as the TOC: + <xsl:param>chunk.first.sections=0 + # How far down sections get TOC's + <xsl:param>toc.section.depth=2 + # Max depth in each TOC: + <xsl:param>toc.max.depth=2 + # How far down we go with TOC's + <xsl:param>generate.section.toc.level=0 + ; + +xml mem_fn_ : mem_fn.qbk ; +boostbook standalone_mem_fn + : + mem_fn_ + : + <xsl:param>boost.root=../../../.. + # File name of HTML output: + <xsl:param>root.filename=mem_fn + # How far down we chunk nested sections, basically all of them: + <xsl:param>chunk.section.depth=0 + # Don't put the first section on the same page as the TOC: + <xsl:param>chunk.first.sections=0 + # How far down sections get TOC's + <xsl:param>toc.section.depth=2 + # Max depth in each TOC: + <xsl:param>toc.max.depth=2 + # How far down we go with TOC's + <xsl:param>generate.section.toc.level=0 + ; diff --git a/libs/bind/doc/bind.qbk b/libs/bind/doc/bind.qbk new file mode 100644 index 000000000..807ba681f --- /dev/null +++ b/libs/bind/doc/bind.qbk @@ -0,0 +1,35 @@ +[/ + / Copyright (c) 2001, 2002 Peter Dimov and Multi Media Ltd. + / Copyright (c) 2003-2008 Peter Dimov + / + / Distributed under 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) + /] + +[library Boost.Bind + [quickbook 1.6] + [id bind] + [copyright 2001, 2002 Peter Dimov and Multi Media Ltd.] + [copyright 2003-2008 Peter Dimov] + [dirname bind] + [license Distributed under the + [@http://boost.org/LICENSE_1_0.txt Boost Software License, + Version 1.0]. + ] +] + +[template simplesect[title] +[block '''<simplesect><title>'''[title]'''</title>''']] + +[template endsimplesect[] +[block '''</simplesect>''']] + +[include bind/purpose.qbk] +[include bind/examples.qbk] +[include bind/limitations.qbk] +[include bind/faq.qbk] +[include bind/troubleshooting.qbk] +[include bind/interface.qbk] +[include bind/implementation.qbk] +[include bind/acknowledgements.qbk] diff --git a/libs/bind/doc/bind/acknowledgements.qbk b/libs/bind/doc/bind/acknowledgements.qbk new file mode 100644 index 000000000..3c87519de --- /dev/null +++ b/libs/bind/doc/bind/acknowledgements.qbk @@ -0,0 +1,48 @@ +[/ + / Copyright (c) 2001, 2002 Peter Dimov and Multi Media Ltd. + / Copyright (c) 2003-2008 Peter Dimov + / + / Distributed under 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) + /] + +[section:acknowledgements Acknowledgements] + +Earlier efforts that have influenced the library design: + +* The [@http://staff.cs.utu.fi/BL/ Binder Library] by Jaakko J\u00E4rvi; + +* The [@boost:/libs/lambda/index.html Lambda Library] (now part of Boost) by + Jaakko J\u00E4rvi and Gary Powell (the successor to the Binder Library); + +* [@http://more.sourceforge.net/ Extensions to the STL] by Petter Urkedal. + +Doug Gregor suggested that a visitor mechanism would allow `bind` to +interoperate with a signal/slot library. + +John Maddock fixed a MSVC-specific conflict between `bind` and the +[@boost:/libs/type_traits/index.html type traits library]. + +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. + +The precise semantics of `bind` were refined in discussions with Jaakko +J\u00E4rvi. + +Dave Abrahams fixed a MSVC-specific conflict between `bind` and the +[@boost:/libs/utility/iterator_adaptors.htm iterator adaptors library]. + +Dave Abrahams modified `bind` and `mem_fn` to support `void` returns on +deficient compilers. + +Mac Murrett contributed the "pascal" support enabled by +`BOOST_BIND_ENABLE_PASCAL`. + +The alternative `bind(type<R>(), f, ...)` syntax was inspired by a discussion +with Dave Abrahams and Joel de Guzman. + +This documentation was ported to Quickbook by AgustÃn Bergé. + +[endsect] diff --git a/libs/bind/doc/bind/examples.qbk b/libs/bind/doc/bind/examples.qbk new file mode 100644 index 000000000..7a36d0616 --- /dev/null +++ b/libs/bind/doc/bind/examples.qbk @@ -0,0 +1,70 @@ +[/ + / Copyright (c) 2001, 2002 Peter Dimov and Multi Media Ltd. + / Copyright (c) 2003-2008 Peter Dimov + / + / Distributed under 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) + /] + +[section:examples Examples] + +[section Using bind with standard algorithms] + + class image; + + class animation + { + public: + void advance(int ms); + bool inactive() const; + void render(image & target) const; + }; + + std::vector<animation> anims; + + template<class C, class P> void erase_if(C & c, P pred) + { + c.erase(std::remove_if(c.begin(), c.end(), pred), c.end()); + } + + void update(int ms) + { + std::for_each(anims.begin(), anims.end(), boost::bind(&animation::advance, _1, ms)); + erase_if(anims, boost::mem_fn(&animation::inactive)); + } + + void render(image & target) + { + std::for_each(anims.begin(), anims.end(), boost::bind(&animation::render, _1, boost::ref(target))); + } + +[endsect] + +[section Using bind with Boost.Function] + + class button + { + public: + ``[@boost:/libs/function/index.html `boost::function`]``<void()> onClick; + }; + + class player + { + public: + void play(); + void stop(); + }; + + button playButton, stopButton; + player thePlayer; + + void connect() + { + playButton.onClick = boost::bind(&player::play, &thePlayer); + stopButton.onClick = boost::bind(&player::stop, &thePlayer); + } + +[endsect] + +[endsect] diff --git a/libs/bind/doc/bind/faq.qbk b/libs/bind/doc/bind/faq.qbk new file mode 100644 index 000000000..8406a19f1 --- /dev/null +++ b/libs/bind/doc/bind/faq.qbk @@ -0,0 +1,99 @@ +[/ + / Copyright (c) 2001, 2002 Peter Dimov and Multi Media Ltd. + / Copyright (c) 2003-2008 Peter Dimov + / + / Distributed under 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) + /] + +[section:faq Frequently Asked Questions] + +[section Why doesn't this compile?] + +See the dedicated [link bind.troubleshooting Troubleshooting section]. + +[endsect] + +[section Why does this compile? It should not.] + +Probably because you used the general `bind<R>(f, ...)` syntax, thereby +instructing `bind` to not "inspect" f to detect arity and return type errors. + +[endsect] + +[section:Q_forms What is the difference between `bind(f, ...)` and `bind<R>(f, ...)`?] + +The first form instructs `bind` to inspect the type of `f` 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 `f`. It must be a function, function pointer, member function pointer, or a +function object that defines a nested type named `result_type`; in short, it +must be something that `bind` can recognize. + +The second form instructs `bind` to not attempt to recognize the type of `f`. +It is generally used with function objects that do not, or cannot, expose +`result_type`, but it can also be used with nonstandard functions. For example, +the current implementation does not automatically recognize variable-argument +functions like `printf`, so you will have to use `bind<int>(printf, ...)`. +Note that an alternative `bind(type<R>(), f, ...)` syntax is supported for +portability reasons. + +Another important factor to consider is that compilers without partial +template specialization or function template partial ordering support cannot +handle the first form when `f` is a function object, and in most cases will +not handle the second form when `f` is a function (pointer) or a member +function pointer. + +[endsect] + +[section Does bind work with Windows API functions?] + +Yes, if you [link bind.implementation.stdcall `#define +BOOST_BIND_ENABLE_STDCALL`]. An alternative is to treat the function as a +[link bind.purpose.with_function_objects generic function object] and use the +`bind<R>(f, ...)` syntax. + +[endsect] + +[section Does bind work with COM methods?] + +Yes, if you [link bind.implementation.stdcall `#define +BOOST_MEM_FN_ENABLE_STDCALL`]. + +[endsect] + +[section Does bind work with Mac toolbox functions?] + +Yes, if you [link bind.implementation.stdcall `#define +BOOST_BIND_ENABLE_PASCAL`]. An alternative is to treat the function as a [link +bind.purpose.with_function_objects generic function object] and use the +`bind<R>(f, ...)` syntax. + +[endsect] + +[section Does bind work with extern "C" functions?] + +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 `bind` is expected +to handle the problem transparently; this implementation does not. As usual, +the workaround is to treat the function as a [link +bind.purpose.with_function_objects generic function object] and use the +`bind<R>(f, ...)` syntax. + +[endsect] + +[section Why doesn't bind automatically recognize nonstandard functions?] + +Non-portable extensions, in general, should default to off to prevent vendor +lock-in. Had the [link bind.implementation.stdcall appropriate macros] 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 `__stdcall` (`__fastcall`) their +default calling convention, in which case no separate support would be +necessary. + +[endsect] + +[endsect] diff --git a/libs/bind/doc/bind/implementation.qbk b/libs/bind/doc/bind/implementation.qbk new file mode 100644 index 000000000..40d339ada --- /dev/null +++ b/libs/bind/doc/bind/implementation.qbk @@ -0,0 +1,98 @@ +[/ + / Copyright (c) 2001, 2002 Peter Dimov and Multi Media Ltd. + / Copyright (c) 2003-2008 Peter Dimov + / + / Distributed under 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) + /] + +[section:implementation Implementation] + +[section Files] + +* [@../../include/boost/bind.hpp boost/bind.hpp] (main header) +* [@../../include/boost/bind/bind_cc.hpp boost/bind/bind_cc.hpp] (used by `bind.hpp`, do not include directly) +* [@../../include/boost/bind/bind_mf_cc.hpp boost/bind/bind_mf_cc.hpp] (used by `bind.hpp`, do not include directly) +* [@../../include/boost/bind/bind_template.hpp boost/bind/bind_template.hpp] (used by `bind.hpp`, do not include directly) +* [@../../include/boost/bind/arg.hpp boost/bind/arg.hpp] (defines the type of the placeholder arguments) +* [@../../include/boost/bind/placeholders.hpp boost/bind/placeholders.hpp] (defines the `_1`, `_2`, ... `_9` placeholders) +* [@../../include/boost/bind/apply.hpp boost/bind/apply.hpp] (`apply` helper function object) +* [@../../include/boost/bind/protect.hpp boost/bind/protect.hpp] (`protect` helper function) +* [@../../include/boost/bind/make_adaptable.hpp boost/bind/make_adaptable.hpp] (`make_adaptable` helper function) +* [@../../test/bind_test.cpp libs/bind/test/bind_test.cpp] (test) +* [@../../bind_as_compose.cpp libs/bind/bind_as_compose.cpp] (function composition example) +* [@../../bind_visitor.cpp libs/bind/bind_visitor.cpp] (visitor example) +* [@../../test/bind_stdcall_test.cpp libs/bind/test/bind_stdcall_test.cpp] (test with `__stdcall` functions) +* [@../../test/bind_stdcall_mf_test.cpp libs/bind/test/bind_stdcall_mf_test.cpp] (test with `__stdcall` member functions) +* [@../../test/bind_fastcall_test.cpp libs/bind/test/bind_fastcall_test.] (test with `__fastcall` functions) +* [@../../test/bind_fastcall_mf_test.cpp libs/bind/test/bind_fastcall_mf_test.cpp] (test with `__fastcall` member functions) + +[endsect] + +[section Dependencies] + +* [@boost:/libs/config/config.htm Boost.Config] +* [@boost:/libs/core/doc/html/core/ref.html boost/ref.hpp] +* [@boost:/libs/bind/mem_fn.html boost/mem_fn.hpp] +* [@boost:/boost/type.hpp boost/type.hpp] + +[endsect] + +[section Number of Arguments] + +This implementation supports function objects with up to nine arguments. This +is an implementation detail, not an inherent limitation of the design. + +[endsect] + +[section:stdcall `__stdcall`, `__cdecl`, `__fastcall`, and `pascal` Support] + +Some platforms allow several types of (member) functions that differ by their +calling convention (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.) + +For example, Windows API functions and COM interface member functions use a +calling convention known as `__stdcall`. Borland VCL components use +`__fastcall`. Mac toolbox functions use a `pascal` calling convention. + +To use `bind` with `__stdcall` functions, `#define` the macro +`BOOST_BIND_ENABLE_STDCALL` before including `<boost/bind.hpp>`. + +To use `bind` with `__stdcall` member functions, `#define` the macro +`BOOST_MEM_FN_ENABLE_STDCALL` before including `<boost/bind.hpp>`. + +To use `bind` with `__fastcall` functions, `#define` the macro +`BOOST_BIND_ENABLE_FASTCALL` before including `<boost/bind.hpp>`. + +To use `bind` with `__fastcall` member functions, `#define` the macro +`BOOST_MEM_FN_ENABLE_FASTCALL` before including `<boost/bind.hpp>`. + +To use `bind` with `pascal` functions, `#define` the macro +`BOOST_BIND_ENABLE_PASCAL` before including `<boost/bind.hpp>`. + +To use `bind` with `__cdecl` member functions, `#define` the macro +`BOOST_MEM_FN_ENABLE_CDECL` before including `<boost/bind.hpp>`. + +[*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.] Not following this rule can lead to obscure errors when a +header includes `bind.hpp` before the macro has been defined. + +/[Note:/ this is a non-portable extension. It is not part of the interface./]/ + +/[Note:/ Some compilers provide only minimal support for the `__stdcall` keyword./]/ + +[endsect] + +[section `visit_each` support] + +Function objects returned by `bind` support the experimental and undocumented, +as of yet, `visit_each` enumeration interface. + +See [@../../bind_visitor.cpp bind_visitor.cpp] for an example. + +[endsect] + +[endsect] diff --git a/libs/bind/doc/bind/interface.qbk b/libs/bind/doc/bind/interface.qbk new file mode 100644 index 000000000..cd83f9cb3 --- /dev/null +++ b/libs/bind/doc/bind/interface.qbk @@ -0,0 +1,216 @@ +[/ + / Copyright (c) 2001, 2002 Peter Dimov and Multi Media Ltd. + / Copyright (c) 2003-2008 Peter Dimov + / + / Distributed under 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) + /] + +[section:interface Interface] + +[section:synopsys Synopsis] + + namespace boost + { + // no arguments + + template<class R, class F> ``/unspecified-1/`` ``[link bind_1 `bind`]``(F f); + + template<class F> ``/unspecified-1-1/`` ``[link bind_1_1 `bind`]``(F f); + + template<class R> ``/unspecified-2/`` ``[link bind_2 `bind`]``(R (*f) ()); + + // one argument + + template<class R, class F, class A1> ``/unspecified-3/`` ``[link bind_3 `bind`]``(F f, A1 a1); + + template<class F, class A1> ``/unspecified-3-1/`` ``[link bind_3_1 `bind`]``(F f, A1 a1); + + template<class R, class B1, class A1> ``/unspecified-4/`` ``[link bind_4 `bind`]``(R (*f) (B1), A1 a1); + + template<class R, class T, class A1> ``/unspecified-5/`` ``[link bind_5 `bind`]``(R (T::*f) (), A1 a1); + + template<class R, class T, class A1> ``/unspecified-6/`` ``[link bind_6 `bind`]``(R (T::*f) () const, A1 a1); + + template<class R, class T, class A1> ``/unspecified-6-1/`` ``[link bind_6_1 `bind`]``(R T::*f, A1 a1); + + // two arguments + + template<class R, class F, class A1, class A2> ``/unspecified-7/`` ``[link bind_7 `bind`]``(F f, A1 a1, A2 a2); + + template<class F, class A1, class A2> ``/unspecified-7-1/`` ``[link bind_7_1 `bind`]``(F f, A1 a1, A2 a2); + + template<class R, class B1, class B2, class A1, class A2> ``/unspecified-8/`` ``[link bind_8 `bind`]``(R (*f) (B1, B2), A1 a1, A2 a2); + + template<class R, class T, class B1, class A1, class A2> ``/unspecified-9/`` ``[link bind_9 `bind`]``(R (T::*f) (B1), A1 a1, A2 a2); + + template<class R, class T, class B1, class A1, class A2> ``/unspecified-10/`` ``[link bind_10 `bind`]``(R (T::*f) (B1) const, A1 a1, A2 a2); + + // implementation defined number of additional overloads for more arguments + } + + namespace + { + ``/unspecified-placeholder-type-1/`` _1; + + ``/unspecified-placeholder-type-2/`` _2; + + ``/unspecified-placeholder-type-3/`` _3; + + // implementation defined number of additional placeholder definitions + } + +[endsect] + +[section Common requirements] + +All /unspecified-N/ types returned by `bind` are /CopyConstructible/. /unspecified-N/`::result_type` is defined as the return type of /unspecified-N/`::operator()`. + +All /unspecified-placeholder-N/ types are /CopyConstructible/. Their copy constructors do not throw exceptions. + +[endsect] + +[section Common definitions] + +The function \u03BC`(x, v1, v2, ..., vm)`, where `m` is a nonnegative integer, is +defined as: + +* `x.get()`, when `x` is of type [@boost:/libs/core/doc/html/core/ref.html `boost::reference_wrapper`]`<T>` for some type + `T`; + +* `vk`, when `x` is (a copy of) the placeholder /_k/ for some positive integer + /k/; + +* `x(v1, v2, ..., vm)` when `x` is (a copy of) a function object returned by + `bind`; + +* `x` otherwise. + +[endsect] + +[section `bind`] + +[#bind_1] + + template<class R, class F> ``/unspecified-1/`` bind(F f) + +* /Returns:/ A function object \u03BB such that the expression \u03BB`(v1, v2, ..., vm)` +is equivalent to `f()`, implicitly converted to `R`. + +* /Throws:/ Nothing unless the copy constructor of `F` throws an exception. + +[#bind_1_1] + + template<class F> ``/unspecified-1-1/`` bind(F f) + +* /Effects:/ Equivalent to `bind<typename F::result_type, F>(f)`. + +* /Notes:/ Implementations are allowed to infer the return type of `f` via other +means as an extension, without relying on the `result_type` member. + +[#bind_2] + + template<class R> ``/unspecified-2/`` bind(R (*f) ()) + +* /Returns:/ A function object \u03BB such that the expression \u03BB`(v1, v2, ..., vm)` +is equivalent to `f()`. + +* /Throws:/ Nothing. + +[#bind_3] + + template<class R, class F, class A1> ``/unspecified-3/`` bind(F f, A1 a1) + +* /Returns:/ A function object \u03BB such that the expression \u03BB`(v1, v2, ..., vm)` +is equivalent to `f(`\u03BC`(a1, v1, v2, ..., vm))`, implicitly converted to `R`. + +* /Throws:/ Nothing unless the copy constructors of `F` or `A1` throw an exception. + +[#bind_3_1] + + template<class F, class A1> ``/unspecified-3-1/`` bind(F f, A1 a1) + +* /Effects:/ Equivalent to `bind<typename F::result_type, F, A1>(f, a1)`. + +* /Notes:/ Implementations are allowed to infer the return type of `f` via other +means as an extension, without relying on the `result_type` member. + +[#bind_4] + + template<class R, class B1, class A1> ``/unspecified-4/`` bind(R (*f) (B1), A1 a1) + +* /Returns:/ A function object \u03BB such that the expression \u03BB`(v1, v2, ..., vm)` +is equivalent to `f(`\u03BC`(a1, v1, v2, ..., vm))`. + +* /Throws:/ Nothing unless the copy constructor of `A1` throws an exception. + +[#bind_5] + + template<class R, class T, class A1> ``/unspecified-5/`` bind(R (T::*f) (), A1 a1) + +* /Effects:/ Equivalent to `bind<R>(`[@boost:/libs/bind/mem_fn.html `boost::mem_fn`]`(f), a1)`. + +[#bind_6] + + template<class R, class T, class A1> ``/unspecified-6/`` bind(R (T::*f) () const, A1 a1) + +* /Effects:/ Equivalent to `bind<R>(`[@boost:/libs/bind/mem_fn.html `boost::mem_fn`]`(f), a1)`. + +[#bind_6_1] + + template<class R, class T, class A1> ``/unspecified-6-1/`` bind(R T::*f, A1 a1) + +* /Effects:/ Equivalent to `bind<R>(`[@boost:/libs/bind/mem_fn.html `boost::mem_fn`]`(f), a1)`. + +[#bind_7] + + template<class R, class F, class A1, class A2> ``/unspecified-7/`` bind(F f, A1 a1, A2 a2) + +* /Returns:/ A function object \u03BB such that the expression \u03BB`(v1, v2, ..., vm)` +is equivalent to `f(`\u03BC`(a1, v1, v2, ..., vm), `\u03BC`(a2, v1, v2, ..., vm))`, +implicitly converted to `R`. + +* /Throws:/ Nothing unless the copy constructors of `F`, `A1` or `A2` throw an +exception. + +[#bind_7_1] + + template<class F, class A1, class A2> ``/unspecified-7-1/`` bind(F f, A1 a1, A2 a2) + +* /Effects:/ Equivalent to `bind<typename F::result_type, F, A1, A2>(f, a1, a2)`. + +* /Notes:/ Implementations are allowed to infer the return type of `f` via other +means as an extension, without relying on the `result_type` member. + +[#bind_8] + + template<class R, class B1, class B2, class A1, class A2> ``/unspecified-8/`` bind(R (*f) (B1, B2), A1 a1, A2 a2) + +* /Returns:/ A function object \u03BB such that the expression \u03BB`(v1, v2, ..., vm)` +is equivalent to `f(`\u03BC`(a1, v1, v2, ..., vm), `\u03BC`(a2, v1, v2, ..., vm))`. + +* /Throws:/ Nothing unless the copy constructors of `A1` or `A2` throw an exception. + +[#bind_9] + + template<class R, class T, class B1, class A1, class A2> ``/unspecified-9/`` bind(R (T::*f) (B1), A1 a1, A2 a2) + +* /Effects:/ Equivalent to `bind<R>(`[@boost:/libs/bind/mem_fn.html `boost::mem_fn`]`(f), a1, a2)`. + +[#bind_10] + + template<class R, class T, class B1, class A1, class A2> ``/unspecified-10/`` bind(R (T::*f) (B1) const, A1 a1, A2 a2) + +* /Effects:/ Equivalent to `bind<R>(`[@boost:/libs/bind/mem_fn.html `boost::mem_fn`]`(f), a1, a2)`. + +[endsect] + +[section Additional overloads] + +Implementations are allowed to provide additional `bind` overloads in order to +support more arguments or different function pointer variations. + +[endsect] + +[endsect] diff --git a/libs/bind/doc/bind/limitations.qbk b/libs/bind/doc/bind/limitations.qbk new file mode 100644 index 000000000..a3b2305c8 --- /dev/null +++ b/libs/bind/doc/bind/limitations.qbk @@ -0,0 +1,37 @@ +[/ + / Copyright (c) 2001, 2002 Peter Dimov and Multi Media Ltd. + / Copyright (c) 2003-2008 Peter Dimov + / + / Distributed under 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) + /] + +[section:limitations Limitations] + +As a general rule, the function objects generated by `bind` 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 the [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2002/n1385.htm forwarding problem]. +(It will be fixed in the next standard, usually called C++0x.) + +The library uses signatures of the form + + template<class T> void f(T & t); + +to accept arguments of arbitrary types and pass them on unmodified. As noted, +this does not work with non-const r-values. + +On compilers that support partial ordering of function templates, a possible +solution is to add an overload: + + template<class T> void f(T & t); + template<class T> void f(T const & t); + +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. + +[endsect] diff --git a/libs/bind/doc/bind/purpose.qbk b/libs/bind/doc/bind/purpose.qbk new file mode 100644 index 000000000..8ec1e79f7 --- /dev/null +++ b/libs/bind/doc/bind/purpose.qbk @@ -0,0 +1,273 @@ +[/ + / Copyright (c) 2001, 2002 Peter Dimov and Multi Media Ltd. + / Copyright (c) 2003-2008 Peter Dimov + / + / Distributed under 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) + /] + +[section:purpose Purpose] + +`boost::bind` is a generalization of the standard functions `std::bind1st` and +`std::bind2nd`. 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. `bind` does +not place any requirements on the function object; in particular, it does not +need the `result_type`, `first_argument_type` and `second_argument_type` +standard typedefs. + +[section Using bind with functions and function pointers] + +Given these definitions: + + int f(int a, int b) + { + return a + b; + } + + int g(int a, int b, int c) + { + return a + b + c; + } + +`bind(f, 1, 2)` will produce a "nullary" function object that takes no +arguments and returns `f(1, 2)`. Similarly, `bind(g, 1, 2, 3)()` is equivalent + `to g(1, 2, 3)`. + +It is possible to selectively bind only some of the arguments. +`bind(f, _1, 5)(x)` is equivalent to `f(x, 5)`; here `_1` is a /placeholder/ +argument that means "substitute with the first input argument." + +For comparison, here is the same operation expressed with the standard library +primitives: + + std::bind2nd(std::ptr_fun(f), 5)(x); + +`bind` covers the functionality of `std::bind1st` as well: + + std::bind1st(std::ptr_fun(f), 5)(x); // f(5, x) + bind(f, 5, _1)(x); // f(5, x) + +`bind` can handle functions with more than two arguments, and its argument +substitution mechanism is more general: + + bind(f, _2, _1)(x, y); // f(y, x) + bind(g, _1, 9, _1)(x); // g(x, 9, x) + bind(g, _3, _3, _3)(x, y, z); // g(z, z, z) + bind(g, _1, _1, _1)(x, y, z); // g(x, x, x) + +Note that, in the last example, the function object produced by +`bind(g, _1, _1, _1)` 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. + +The arguments that `bind` takes are copied and held internally by the returned +function object. For example, in the following code: + + int i = 5; + bind(f, i, _1); + +a copy of the value of `i` is stored into the function object. +[@boost:/libs/core/doc/html/core/ref.html `boost::ref`] and +[@boost:/libs/core/doc/html/core/ref.html `boost::cref`] can be used to make the function +object store a reference to an object, rather than a copy: + + int i = 5; + bind(f, ref(i), _1); + bind(f, cref(i), _1); + +[endsect] + +[section:with_function_objects Using bind with function objects] + +`bind` is not limited to functions; it accepts arbitrary function objects. In +the general case, the return type of the generated function object's +`operator()` has to be specified explicitly (without a `typeof` operator the +return type cannot be inferred): + + struct F + { + int operator()(int a, int b) { return a - b; } + bool operator()(long a, long b) { return a == b; } + }; + + F f; + int x = 104; + bind<int>(f, _1, _1)(x); // f(x, x), i.e. zero + +Some compilers have trouble with the `bind<R>(f, ...)` syntax. For portability +reasons, an alternative way to express the above is supported: + + boost::bind(boost::type<int>(), f, _1, _1)(x); + +Note, however, that the alternative syntax is provided only as a workaround. +It is not part of the interface. + +When the function object exposes a nested type named `result_type`, the explicit +return type can be omitted: + + int x = 8; + bind(std::less<int>(), _1, 9)(x); // x < 9 + +/[Note:/ the ability to omit the return type is not available on all compilers./]/ + +By default, `bind` makes a copy of the provided function object. `boost::ref` +and `boost::cref` 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 +non-copyable, 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. + + 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); + +[endsect] + +[section Using bind with pointers to members] + +Pointers to member functions and pointers to data members are not function +objects, because they do not support `operator()`. For convenience, `bind` +accepts member pointers as its first argument, and the behavior is as if +[@boost:/libs/bind/mem_fn.html `boost::mem_fn`] has been used to convert the +member pointer into a function object. In other words, the expression + + bind(&X::f, args) + +is equivalent to + + bind<R>(``[@boost:/libs/bind/mem_fn.html `mem_fn`]``(&X::f), args) + +where `R` is the return type of `X::f` (for member functions) or the type of +the member (for data members.) + +/[Note:/ `mem_fn` 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 `mem_fn` +[@boost:/libs/bind/mem_fn.html documentation]./]/ + +Example: + + struct X + { + bool f(int a); + }; + + X x; + shared_ptr<X> p(new X); + int i = 5; + + bind(&X::f, ref(x), _1)(i); // x.f(i) + bind(&X::f, &x, _1)(i); // (&x)->f(i) + bind(&X::f, x, _1)(i); // (internal copy of x).f(i) + bind(&X::f, p, _1)(i); // (internal copy of p)->f(i) + +The last two examples are interesting in that they produce "self-contained" +function objects. `bind(&X::f, x, _1)` stores a copy of `x`. +`bind(&X::f, p, _1)` stores a copy of `p`, and since `p` is a +[@boost:/libs/smart_ptr/shared_ptr.htm `boost::shared_ptr`], the function +object retains a reference to its instance of `X` and will remain valid even +when `p` goes out of scope or is `reset()`. + +[endsect] + +[section Using nested binds for function composition] + +Some of the arguments passed to `bind` may be nested /bind expressions/ +themselves: + + bind(f, bind(g, _1))(x); // f(g(x)) + +The inner /bind expressions/ are evaluated, in unspecified order, before the +outer `bind` when the function object is called; the results of the evaluation +are then substituted in their place when the outer `bind` is evaluated. In the +example above, when the function object is called with the argument list `(x)`, +`bind(g, _1)(x)` is evaluated first, yielding `g(x)`, and then +`bind(f, g(x))(x)` is evaluated, yielding the final result `f(g(x))`. + +This feature of `bind` can be used to perform function composition. See +[@../../bind_as_compose.cpp bind_as_compose.cpp] for an example that +demonstrates how to use `bind` to achieve similar functionality to +[@http://www.boost.org/doc/libs/1_31_0/libs/compose/index.htm Boost.Compose]. + +Note that the first argument - the bound function object - is not evaluated, +even when it's a function object that is produced by `bind` or a /placeholder/ +argument, so the example below does not work as expected: + + typedef void (*pf)(int); + + std::vector<pf> v; + std::for_each(v.begin(), v.end(), bind(_1, 5)); + +The desired effect can be achieved via a helper function object `apply` that +applies its first argument, as a function object, to the rest of its argument +list. For convenience, an implementation of `apply` is provided in the +[@../../include/boost/bind/apply.hpp apply.hpp] header file. Here is how the +modified version of the previous example looks like: + + typedef void (*pf)(int); + + std::vector<pf> v; + std::for_each(v.begin(), v.end(), bind(apply<void>(), _1, 5)); + +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 /bind subexpressions/. This can be achieved +with the help of another function object, `protect`, that masks the type so +that `bind` does not recognize and evaluate it. When called, protect simply +forwards the argument list to the other function object unmodified. + +The header [@../../include/boost/bind/protect.hpp protect.hpp] contains an +implementation of `protect`. To `protect` a bind function object from +evaluation, use `protect(bind(f, ...))`. + +[endsect] + +[section Overloaded operators (new in Boost 1.33)] + +For convenience, the function objects produced by `bind` overload the logical +not operator `!` and the relational and logical operators `==, !=, <, <=, >, +>=, &&, ||`. + +`!bind(f, ...)` is equivalent to `bind(logical_not(), bind(f, ...))`, where +`logical_not` is a function object that takes one argument `x` and returns +`!x`. + +`bind(f, ...) op x`, where _op_ is a relational or logical operator, is +equivalent to `bind(relation(), bind(f, ...), x)`, where `relation` is a +function object that takes two arguments `a` and `b` and returns `a op b`. + +What this means in practice is that you can conveniently negate the result of +`bind`: + + std::remove_if(first, last, !bind(&X::visible, _1)); // remove invisible objects + +and compare the result of `bind` against a value: + + std::find_if(first, last, bind(&X::name, _1) == "Peter"); + std::find_if(first, last, bind(&X::name, _1) == "Peter" || bind(&X::name, _1) == "Paul"); + +against a /placeholder/: + + bind(&X::name, _1) == _2 + +or against another /bind expression/: + + std::sort(first, last, bind(&X::name, _1) < bind(&X::name, _2)); // sort by name + +[endsect] + +[endsect] diff --git a/libs/bind/doc/bind/troubleshooting.qbk b/libs/bind/doc/bind/troubleshooting.qbk new file mode 100644 index 000000000..2897a3dde --- /dev/null +++ b/libs/bind/doc/bind/troubleshooting.qbk @@ -0,0 +1,268 @@ +[/ + / Copyright (c) 2001, 2002 Peter Dimov and Multi Media Ltd. + / Copyright (c) 2003-2008 Peter Dimov + / + / Distributed under 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) + /] + +[section:troubleshooting Troubleshooting] + +[section Incorrect number of arguments] + +In a `bind(f, a1, a2, ..., aN)` expression, the function object `f` must be +able to take exactly N arguments. This error is normally detected at "bind +time"; in other words, the compilation error is reported on the line where +`bind()` is invoked: + + int f(int, int); + + int main() + { + boost::bind(f, 1); // error, f takes two arguments + boost::bind(f, 1, 2); // OK + } + +A common variation of this error is to forget that member functions have an +implicit "this" argument: + + struct X + { + int f(int); + } + + int main() + { + boost::bind(&X::f, 1); // error, X::f takes two arguments + boost::bind(&X::f, _1, 1); // OK + } + +[endsect] + +[section The function object cannot be called with the specified arguments] + +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 `bind.hpp` on a line that looks like: + + return f(a[a1_], a[a2_]); + +An example of this kind of error: + + int f(int); + + int main() + { + boost::bind(f, "incompatible"); // OK so far, no call + boost::bind(f, "incompatible")(); // error, "incompatible" is not an int + boost::bind(f, _1); // OK + boost::bind(f, _1)("incompatible"); // error, "incompatible" is not an int + } + +[endsect] + +[section Accessing an argument that does not exist] + +The placeholder `_N` selects the argument at position `N` from the argument +list passed at "call time." Naturally, it is an error to attempt to access +beyond the end of this list: + + int f(int); + + int main() + { + boost::bind(f, _1); // OK + boost::bind(f, _1)(); // error, there is no argument number 1 + } + +The error is usually reported in `bind.hpp`, at a line similar to: + + return f(a[a1_]); + +When emulating `std::bind1st(f, a)`, a common mistake of this category is to +type `bind(f, a, _2)` instead of the correct `bind(f, a, _1)`. + +[endsect] + +[section Inappropriate use of `bind(f, ...)`] + +The `bind(f, a1, a2, ..., aN)` [link bind.faq.Q_forms form] causes automatic +recognition of the type of `f`. It will not work with arbitrary function +objects; `f` must be a function or a member function pointer. + +It is possible to use this form with function objects that define +`result_type`, but only on compilers that support partial specialization and +partial ordering. In particular, MSVC up to version 7.0 does not support this +syntax for function objects. + +[endsect] + +[section Inappropriate use of `bind<R>(f, ...)`] + +The `bind<R>(f, a1, a2, ..., aN)` [link bind.faq.Q_forms form] supports +arbitrary function objects. + +It is possible (but not recommended) to use this form with functions or member +function pointers, but only on compilers that support partial ordering. In +particular, MSVC up to version 7.0 does not fully support this syntax for +functions and member function pointers. + +[endsect] + +[section Binding a nonstandard function] + +By default, the `bind(f, a1, a2, ..., aN)` [link bind.faq.Q_forms form] +recognizes "ordinary" C++ functions and function pointers. [link +bind.implementation.stdcall Functions that use a different calling convention], +or variable-argument functions such as `std::printf`, do not work. The general +`bind<R>(f, a1, a2, ..., aN)` [link bind.faq.Q_forms form] works with +nonstandard functions. + +On some platforms, extern "C" functions, like `std::strcmp`, are not +recognized by the short form of `bind`. + +See also [link bind.implementation.stdcall `__stdcall` and `pascal` Support]. + +[endsect] + +[section Binding an overloaded function] + +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: + + struct X + { + int& get(); + int const& get() const; + }; + + int main() + { + boost::bind(&X::get, _1); + } + +The ambiguity can be resolved manually by casting the (member) function +pointer to the desired type: + + int main() + { + boost::bind(static_cast< int const& (X::*) () const >(&X::get), _1); + } + +Another, arguably more readable, alternative is to introduce a temporary +variable: + + int main() + { + int const& (X::*get) () const = &X::get; + boost::bind(get, _1); + } + +[endsect] + +[section Modeling STL function object concepts] + +The function objects that are produced by `bind` do not model the STL +[@http://www.sgi.com/tech/stl/UnaryFunction.html /Unary Function/] or +[@http://www.sgi.com/tech/stl/BinaryFunction.html /Binary Function/] concepts, +even when the function objects are unary or binary operations, because the +function object types are missing public typedefs `result_type` and +`argument_type` or `first_argument_type` and `second_argument_type`. In cases +where these typedefs are desirable, however, the utility function +`make_adaptable` can be used to adapt unary and binary function objects to +these concepts. This allows unary and binary function objects resulting from +`bind` to be combined with STL templates such as +[@http://en.cppreference.com/w/cpp/utility/functional/unary_negate `std::unary_negate`] +and [@http://en.cppreference.com/w/cpp/utility/functional/binary_negate `std::binary_negate`]. + +The `make_adaptable` function is defined in [@../../include/boost/bind/make_adaptable.hpp +`<boost/bind/make_adaptable.hpp>`], which must be included explicitly in +addition to [@../../include/boost/bind.hpp `<boost/bind.hpp>`]: + + #include <boost/bind/make_adaptable.hpp> + + template <class R, class F> ``/unspecified-type/`` make_adaptable(F f); + + template<class R, class A1, class F> ``/unspecified-unary-functional-type/`` make_adaptable(F f); + + template<class R, class A1, class A2, class F> ``/unspecified-binary-functional-type/`` make_adaptable(F f); + + template<class R, class A1, class A2, class A3, class F> ``/unspecified-ternary-functional-type/`` make_adaptable(F f); + + template<class R, class A1, class A2, class A3, class A4, class F> ``/unspecified-4-ary-functional-type/`` make_adaptable(F f); + +This example shows how to use `make_adaptable` to make a predicate for "is not a space": + + typedef char char_t; + std::locale loc(""); + const std::ctype<char_t>& ct = std::use_facet<std::ctype<char_t> >(loc); + + auto isntspace = std::not1(boost::make_adaptable<bool, char_t>(boost::bind(&std::ctype<char_t>::is, &ct, std::ctype_base::space, _1))); + +In this example, `bind` creates the "is a space" (unary) predicate. It is then +passed to `make_adaptable` so that a function object modeling the /Unary +Function/ concept can be created, serving as the argument to +[@http://en.cppreference.com/w/cpp/utility/functional/not1 `std::not1`]. + +[endsect] + +[section `const` in signatures] + +Some compilers, including MSVC 6.0 and Borland C++ 5.5.1, have problems with +the top-level `const` in function signatures: + + int f(int const); + + int main() + { + boost::bind(f, 1); // error + } + +Workaround: remove the `const` qualifier from the argument. + +[endsect] + +[section MSVC specific: `using boost::bind;`] + +On MSVC (up to version 7.0), when `boostbind` is brought into scope with an +using declaration: + + using boost::bind; + +the syntax `bind<R>(f, ...)` does not work. Workaround: either use the +qualified name, `boost::bind`, or use an using directive instead: + + using namespace boost; + +[endsect] + +[section MSVC specific: class templates shadow function templates] + +On MSVC (up to version 7.0), a nested class template named `bind` will shadow +the function template `boost::bind`, breaking the `bind<R>(f, ...)`syntax. +Unfortunately, some libraries contain nested class templates named `bind` +(ironically, such code is often an MSVC specific workaround.) + +The workaround is to use the alternative `bind(type<R>(), f, ...)` syntax. + +[endsect] + +[section MSVC specific: `...` in signatures treated as type] + +MSVC (up to version 7.0) treats the ellipsis in a variable argument function +(such as `std::printf`) as a type. Therefore, it will accept the (incorrect in +the current implementation) form: + + bind(printf, "%s\n", _1); + +and will reject the correct version: + + bind<int>(printf, "%s\n", _1); + +[endsect] + +[endsect] diff --git a/libs/bind/doc/html/bind.html b/libs/bind/doc/html/bind.html new file mode 100644 index 000000000..491582b70 --- /dev/null +++ b/libs/bind/doc/html/bind.html @@ -0,0 +1,1552 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Chapter 1. Boost.Bind</title> +<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="bind.html" title="Chapter 1. Boost.Bind"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td> +<td align="center"><a href="../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"></div> +<div class="chapter"> +<div class="titlepage"><div> +<div><h2 class="title"> +<a name="bind"></a>Chapter 1. Boost.Bind</h2></div> +<div><p class="copyright">Copyright © 2001, 2002 Peter Dimov and Multi Media Ltd.</p></div> +<div><p class="copyright">Copyright © 2003-2008 Peter Dimov</p></div> +<div><div class="legalnotice"> +<a name="bind.legal"></a><p> + Distributed under the <a href="http://boost.org/LICENSE_1_0.txt" target="_top">Boost + Software License, Version 1.0</a>. + </p> +</div></div> +</div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="bind.html#bind.purpose">Purpose</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="bind.html#bind.purpose.using_bind_with_functions_and_fu">Using + bind with functions and function pointers</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.purpose.with_function_objects">Using bind with function + objects</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.purpose.using_bind_with_pointers_to_memb">Using + bind with pointers to members</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.purpose.using_nested_binds_for_function_">Using + nested binds for function composition</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.purpose.overloaded_operators_new_in_boos">Overloaded + operators (new in Boost 1.33)</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="bind.html#bind.examples">Examples</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="bind.html#bind.examples.using_bind_with_standard_algorit">Using + bind with standard algorithms</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.examples.using_bind_with_boost_function">Using bind + with Boost.Function</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="bind.html#bind.limitations">Limitations</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.faq">Frequently Asked Questions</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="bind.html#bind.faq.why_doesn_t_this_compile">Why doesn't this compile?</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.faq.why_does_this_compile_it_should_">Why does this + compile? It should not.</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.faq.Q_forms">What is the difference between <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code> and + <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code>?</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.faq.does_bind_work_with_windows_api_">Does bind + work with Windows API functions?</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.faq.does_bind_work_with_com_methods">Does bind work + with COM methods?</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.faq.does_bind_work_with_mac_toolbox_">Does bind + work with Mac toolbox functions?</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.faq.does_bind_work_with_extern_c_fun">Does bind + work with extern "C" functions?</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.faq.why_doesn_t_bind_automatically_r">Why doesn't + bind automatically recognize nonstandard functions?</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="bind.html#bind.troubleshooting">Troubleshooting</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="bind.html#bind.troubleshooting.incorrect_number_of_arguments">Incorrect + number of arguments</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.troubleshooting.the_function_object_cannot_be_ca">The + function object cannot be called with the specified arguments</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.troubleshooting.accessing_an_argument_that_does_">Accessing + an argument that does not exist</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.troubleshooting.inappropriate_use_of_bind_f">Inappropriate + use of <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code></a></span></dt> +<dt><span class="section"><a href="bind.html#bind.troubleshooting.inappropriate_use_of_bind_r_f">Inappropriate + use of <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code></a></span></dt> +<dt><span class="section"><a href="bind.html#bind.troubleshooting.binding_a_nonstandard_function">Binding + a nonstandard function</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.troubleshooting.binding_an_overloaded_function">Binding + an overloaded function</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.troubleshooting.modeling_stl_function_object_con">Modeling + STL function object concepts</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.troubleshooting.const_in_signatures"><code class="computeroutput"><span class="keyword">const</span></code> in signatures</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.troubleshooting.msvc_specific_using_boost_bind">MSVC + specific: <code class="computeroutput"><span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">;</span></code></a></span></dt> +<dt><span class="section"><a href="bind.html#bind.troubleshooting.msvc_specific_class_templates_sh">MSVC + specific: class templates shadow function templates</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.troubleshooting.msvc_specific_in_signatures_trea">MSVC + specific: <code class="computeroutput"><span class="special">...</span></code> in signatures treated + as type</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="bind.html#bind.interface">Interface</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="bind.html#bind.interface.synopsys">Synopsis</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.interface.common_requirements">Common requirements</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.interface.common_definitions">Common definitions</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.interface.bind"><code class="computeroutput"><span class="identifier">bind</span></code></a></span></dt> +<dt><span class="section"><a href="bind.html#bind.interface.additional_overloads">Additional overloads</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="bind.html#bind.implementation">Implementation</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="bind.html#bind.implementation.files">Files</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.implementation.dependencies">Dependencies</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.implementation.number_of_arguments">Number of Arguments</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.implementation.stdcall"><code class="computeroutput"><span class="identifier">__stdcall</span></code>, + <code class="computeroutput"><span class="identifier">__cdecl</span></code>, <code class="computeroutput"><span class="identifier">__fastcall</span></code>, + and <code class="computeroutput"><span class="identifier">pascal</span></code> Support</a></span></dt> +<dt><span class="section"><a href="bind.html#bind.implementation.visit_each_support"><code class="computeroutput"><span class="identifier">visit_each</span></code> support</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="bind.html#bind.acknowledgements">Acknowledgements</a></span></dt> +</dl> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="bind.purpose"></a><a class="link" href="bind.html#bind.purpose" title="Purpose">Purpose</a> +</h2></div></div></div> +<p> + <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span></code> is a generalization of the standard + functions <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bind1st</span></code> and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bind2nd</span></code>. + 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. <code class="computeroutput"><span class="identifier">bind</span></code> + does not place any requirements on the function object; in particular, it does + not need the <code class="computeroutput"><span class="identifier">result_type</span></code>, + <code class="computeroutput"><span class="identifier">first_argument_type</span></code> and <code class="computeroutput"><span class="identifier">second_argument_type</span></code> standard typedefs. + </p> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.purpose.using_bind_with_functions_and_fu"></a><a class="link" href="bind.html#bind.purpose.using_bind_with_functions_and_fu" title="Using bind with functions and function pointers">Using + bind with functions and function pointers</a> +</h3></div></div></div> +<p> + Given these definitions: + </p> +<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">b</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">a</span> <span class="special">+</span> <span class="identifier">b</span><span class="special">;</span> +<span class="special">}</span> + +<span class="keyword">int</span> <span class="identifier">g</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">b</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">c</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">a</span> <span class="special">+</span> <span class="identifier">b</span> <span class="special">+</span> <span class="identifier">c</span><span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">)</span></code> + will produce a "nullary" function object that takes no arguments + and returns <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">)</span></code>. Similarly, <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">g</span><span class="special">,</span> + <span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">,</span> <span class="number">3</span><span class="special">)()</span></code> is equivalent <code class="computeroutput"><span class="identifier">to</span> + <span class="identifier">g</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">,</span> <span class="number">3</span><span class="special">)</span></code>. + </p> +<p> + It is possible to selectively bind only some of the arguments. <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">,</span> + <span class="number">5</span><span class="special">)(</span><span class="identifier">x</span><span class="special">)</span></code> is equivalent + to <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="number">5</span><span class="special">)</span></code>; here <code class="computeroutput"><span class="identifier">_1</span></code> + is a <span class="emphasis"><em>placeholder</em></span> argument that means "substitute + with the first input argument." + </p> +<p> + For comparison, here is the same operation expressed with the standard library + primitives: + </p> +<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bind2nd</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">ptr_fun</span><span class="special">(</span><span class="identifier">f</span><span class="special">),</span> <span class="number">5</span><span class="special">)(</span><span class="identifier">x</span><span class="special">);</span> +</pre> +<p> + <code class="computeroutput"><span class="identifier">bind</span></code> covers the functionality + of <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bind1st</span></code> as well: + </p> +<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bind1st</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">ptr_fun</span><span class="special">(</span><span class="identifier">f</span><span class="special">),</span> <span class="number">5</span><span class="special">)(</span><span class="identifier">x</span><span class="special">);</span> <span class="comment">// f(5, x)</span> +<span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="number">5</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)(</span><span class="identifier">x</span><span class="special">);</span> <span class="comment">// f(5, x)</span> +</pre> +<p> + <code class="computeroutput"><span class="identifier">bind</span></code> can handle functions + with more than two arguments, and its argument substitution mechanism is + more general: + </p> +<pre class="programlisting"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">_2</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">y</span><span class="special">);</span> <span class="comment">// f(y, x)</span> +<span class="identifier">bind</span><span class="special">(</span><span class="identifier">g</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">,</span> <span class="number">9</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)(</span><span class="identifier">x</span><span class="special">);</span> <span class="comment">// g(x, 9, x)</span> +<span class="identifier">bind</span><span class="special">(</span><span class="identifier">g</span><span class="special">,</span> <span class="identifier">_3</span><span class="special">,</span> <span class="identifier">_3</span><span class="special">,</span> <span class="identifier">_3</span><span class="special">)(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">y</span><span class="special">,</span> <span class="identifier">z</span><span class="special">);</span> <span class="comment">// g(z, z, z)</span> +<span class="identifier">bind</span><span class="special">(</span><span class="identifier">g</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">y</span><span class="special">,</span> <span class="identifier">z</span><span class="special">);</span> <span class="comment">// g(x, x, x)</span> +</pre> +<p> + Note that, in the last example, the function object produced by <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">g</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">,</span> + <span class="identifier">_1</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)</span></code> 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 <code class="computeroutput"><span class="identifier">bind</span></code> takes + are copied and held internally by the returned function object. For example, + in the following code: + </p> +<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">5</span><span class="special">;</span> +<span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">i</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">);</span> +</pre> +<p> + a copy of the value of <code class="computeroutput"><span class="identifier">i</span></code> + is stored into the function object. <a href="../../../../libs/core/doc/html/core/ref.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">ref</span></code></a> and <a href="../../../../libs/core/doc/html/core/ref.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">cref</span></code></a> can be used to make the function + object store a reference to an object, rather than a copy: + </p> +<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">5</span><span class="special">;</span> +<span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">ref</span><span class="special">(</span><span class="identifier">i</span><span class="special">),</span> <span class="identifier">_1</span><span class="special">);</span> +<span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">cref</span><span class="special">(</span><span class="identifier">i</span><span class="special">),</span> <span class="identifier">_1</span><span class="special">);</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.purpose.with_function_objects"></a><a class="link" href="bind.html#bind.purpose.with_function_objects" title="Using bind with function objects">Using bind with function + objects</a> +</h3></div></div></div> +<p> + <code class="computeroutput"><span class="identifier">bind</span></code> is not limited to functions; + it accepts arbitrary function objects. In the general case, the return type + of the generated function object's <code class="computeroutput"><span class="keyword">operator</span><span class="special">()</span></code> has to be specified explicitly (without + a <code class="computeroutput"><span class="identifier">typeof</span></code> operator the return + type cannot be inferred): + </p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">F</span> +<span class="special">{</span> + <span class="keyword">int</span> <span class="keyword">operator</span><span class="special">()(</span><span class="keyword">int</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">b</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">a</span> <span class="special">-</span> <span class="identifier">b</span><span class="special">;</span> <span class="special">}</span> + <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">()(</span><span class="keyword">long</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">long</span> <span class="identifier">b</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">a</span> <span class="special">==</span> <span class="identifier">b</span><span class="special">;</span> <span class="special">}</span> +<span class="special">};</span> + +<span class="identifier">F</span> <span class="identifier">f</span><span class="special">;</span> +<span class="keyword">int</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">104</span><span class="special">;</span> +<span class="identifier">bind</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)(</span><span class="identifier">x</span><span class="special">);</span> <span class="comment">// f(x, x), i.e. zero</span> +</pre> +<p> + Some compilers have trouble with the <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code> + syntax. For portability reasons, an alternative way to express the above + is supported: + </p> +<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">type</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(),</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)(</span><span class="identifier">x</span><span class="special">);</span> +</pre> +<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 <code class="computeroutput"><span class="identifier">result_type</span></code>, + the explicit return type can be omitted: + </p> +<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">8</span><span class="special">;</span> +<span class="identifier">bind</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">less</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(),</span> <span class="identifier">_1</span><span class="special">,</span> <span class="number">9</span><span class="special">)(</span><span class="identifier">x</span><span class="special">);</span> <span class="comment">// x < 9</span> +</pre> +<p> + <span class="emphasis"><em>[Note:</em></span> the ability to omit the return type is not available + on all compilers.<span class="emphasis"><em>]</em></span> + </p> +<p> + By default, <code class="computeroutput"><span class="identifier">bind</span></code> makes a + copy of the provided function object. <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">ref</span></code> and + <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">cref</span></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 non-copyable, 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 class="programlisting"><span class="keyword">struct</span> <span class="identifier">F2</span> +<span class="special">{</span> + <span class="keyword">int</span> <span class="identifier">s</span><span class="special">;</span> + + <span class="keyword">typedef</span> <span class="keyword">void</span> <span class="identifier">result_type</span><span class="special">;</span> + <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">{</span> <span class="identifier">s</span> <span class="special">+=</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span> +<span class="special">};</span> + +<span class="identifier">F2</span> <span class="identifier">f2</span> <span class="special">=</span> <span class="special">{</span> <span class="number">0</span> <span class="special">};</span> +<span class="keyword">int</span> <span class="identifier">a</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span> <span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">,</span> <span class="number">3</span> <span class="special">};</span> + +<span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span> <span class="identifier">a</span><span class="special">+</span><span class="number">3</span><span class="special">,</span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">f2</span><span class="special">),</span> <span class="identifier">_1</span><span class="special">));</span> + +<span class="identifier">assert</span><span class="special">(</span><span class="identifier">f2</span><span class="special">.</span><span class="identifier">s</span> <span class="special">==</span> <span class="number">6</span><span class="special">);</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.purpose.using_bind_with_pointers_to_memb"></a><a class="link" href="bind.html#bind.purpose.using_bind_with_pointers_to_memb" title="Using bind with pointers to members">Using + bind with pointers to members</a> +</h3></div></div></div> +<p> + Pointers to member functions and pointers to data members are not function + objects, because they do not support <code class="computeroutput"><span class="keyword">operator</span><span class="special">()</span></code>. For convenience, <code class="computeroutput"><span class="identifier">bind</span></code> + accepts member pointers as its first argument, and the behavior is as if + <a href="../../../../libs/bind/mem_fn.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span></code></a> + has been used to convert the member pointer into a function object. In other + words, the expression + </p> +<pre class="programlisting"><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">args</span><span class="special">)</span> +</pre> +<p> + is equivalent to + </p> +<pre class="programlisting"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><a href="../../../../libs/bind/mem_fn.html" target="_top"><code class="computeroutput"><span class="identifier">mem_fn</span></code></a><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">),</span> <span class="identifier">args</span><span class="special">)</span> +</pre> +<p> + where <code class="computeroutput"><span class="identifier">R</span></code> is the return type + of <code class="computeroutput"><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span></code> (for member functions) or the type of + the member (for data members.) + </p> +<p> + <span class="emphasis"><em>[Note:</em></span> <code class="computeroutput"><span class="identifier">mem_fn</span></code> + 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 <code class="computeroutput"><span class="identifier">mem_fn</span></code> <a href="../../../../libs/bind/mem_fn.html" target="_top">documentation</a>.<span class="emphasis"><em>]</em></span> + </p> +<p> + Example: + </p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">X</span> +<span class="special">{</span> + <span class="keyword">bool</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">a</span><span class="special">);</span> +<span class="special">};</span> + +<span class="identifier">X</span> <span class="identifier">x</span><span class="special">;</span> +<span class="identifier">shared_ptr</span><span class="special"><</span><span class="identifier">X</span><span class="special">></span> <span class="identifier">p</span><span class="special">(</span><span class="keyword">new</span> <span class="identifier">X</span><span class="special">);</span> +<span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">5</span><span class="special">;</span> + +<span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">ref</span><span class="special">(</span><span class="identifier">x</span><span class="special">),</span> <span class="identifier">_1</span><span class="special">)(</span><span class="identifier">i</span><span class="special">);</span> <span class="comment">// x.f(i)</span> +<span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="special">&</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)(</span><span class="identifier">i</span><span class="special">);</span> <span class="comment">// (&x)->f(i)</span> +<span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)(</span><span class="identifier">i</span><span class="special">);</span> <span class="comment">// (internal copy of x).f(i)</span> +<span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)(</span><span class="identifier">i</span><span class="special">);</span> <span class="comment">// (internal copy of p)->f(i)</span> +</pre> +<p> + The last two examples are interesting in that they produce "self-contained" + function objects. <code class="computeroutput"><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">x</span><span class="special">,</span> + <span class="identifier">_1</span><span class="special">)</span></code> + stores a copy of <code class="computeroutput"><span class="identifier">x</span></code>. <code class="computeroutput"><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">p</span><span class="special">,</span> + <span class="identifier">_1</span><span class="special">)</span></code> + stores a copy of <code class="computeroutput"><span class="identifier">p</span></code>, and since + <code class="computeroutput"><span class="identifier">p</span></code> is a <a href="../../../../libs/smart_ptr/shared_ptr.htm" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span></code></a>, the function object + retains a reference to its instance of <code class="computeroutput"><span class="identifier">X</span></code> + and will remain valid even when <code class="computeroutput"><span class="identifier">p</span></code> + goes out of scope or is <code class="computeroutput"><span class="identifier">reset</span><span class="special">()</span></code>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.purpose.using_nested_binds_for_function_"></a><a class="link" href="bind.html#bind.purpose.using_nested_binds_for_function_" title="Using nested binds for function composition">Using + nested binds for function composition</a> +</h3></div></div></div> +<p> + Some of the arguments passed to <code class="computeroutput"><span class="identifier">bind</span></code> + may be nested <span class="emphasis"><em>bind expressions</em></span> themselves: + </p> +<pre class="programlisting"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">g</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">))(</span><span class="identifier">x</span><span class="special">);</span> <span class="comment">// f(g(x))</span> +</pre> +<p> + The inner <span class="emphasis"><em>bind expressions</em></span> are evaluated, in unspecified + order, before the outer <code class="computeroutput"><span class="identifier">bind</span></code> + when the function object is called; the results of the evaluation are then + substituted in their place when the outer <code class="computeroutput"><span class="identifier">bind</span></code> + is evaluated. In the example above, when the function object is called with + the argument list <code class="computeroutput"><span class="special">(</span><span class="identifier">x</span><span class="special">)</span></code>, <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">g</span><span class="special">,</span> + <span class="identifier">_1</span><span class="special">)(</span><span class="identifier">x</span><span class="special">)</span></code> is evaluated + first, yielding <code class="computeroutput"><span class="identifier">g</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span></code>, and + then <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">g</span><span class="special">(</span><span class="identifier">x</span><span class="special">))(</span><span class="identifier">x</span><span class="special">)</span></code> is evaluated, + yielding the final result <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span><span class="identifier">g</span><span class="special">(</span><span class="identifier">x</span><span class="special">))</span></code>. + </p> +<p> + This feature of <code class="computeroutput"><span class="identifier">bind</span></code> can + be used to perform function composition. See <a href="../../bind_as_compose.cpp" target="_top">bind_as_compose.cpp</a> + for an example that demonstrates how to use <code class="computeroutput"><span class="identifier">bind</span></code> + to achieve similar functionality to <a href="http://www.boost.org/doc/libs/1_31_0/libs/compose/index.htm" target="_top">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 <code class="computeroutput"><span class="identifier">bind</span></code> + or a <span class="emphasis"><em>placeholder</em></span> argument, so the example below does + not work as expected: + </p> +<pre class="programlisting"><span class="keyword">typedef</span> <span class="keyword">void</span> <span class="special">(*</span><span class="identifier">pf</span><span class="special">)(</span><span class="keyword">int</span><span class="special">);</span> + +<span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="identifier">pf</span><span class="special">></span> <span class="identifier">v</span><span class="special">;</span> +<span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">v</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">_1</span><span class="special">,</span> <span class="number">5</span><span class="special">));</span> +</pre> +<p> + The desired effect can be achieved via a helper function object <code class="computeroutput"><span class="identifier">apply</span></code> that applies its first argument, + as a function object, to the rest of its argument list. For convenience, + an implementation of <code class="computeroutput"><span class="identifier">apply</span></code> + is provided in the <a href="../../include/boost/bind/apply.hpp" target="_top">apply.hpp</a> + header file. Here is how the modified version of the previous example looks + like: + </p> +<pre class="programlisting"><span class="keyword">typedef</span> <span class="keyword">void</span> <span class="special">(*</span><span class="identifier">pf</span><span class="special">)(</span><span class="keyword">int</span><span class="special">);</span> + +<span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="identifier">pf</span><span class="special">></span> <span class="identifier">v</span><span class="special">;</span> +<span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">v</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">apply</span><span class="special"><</span><span class="keyword">void</span><span class="special">>(),</span> <span class="identifier">_1</span><span class="special">,</span> <span class="number">5</span><span class="special">));</span> +</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 <span class="emphasis"><em>bind subexpressions</em></span>. + This can be achieved with the help of another function object, <code class="computeroutput"><span class="identifier">protect</span></code>, that masks the type so that <code class="computeroutput"><span class="identifier">bind</span></code> does not recognize and evaluate it. + When called, protect simply forwards the argument list to the other function + object unmodified. + </p> +<p> + The header <a href="../../include/boost/bind/protect.hpp" target="_top">protect.hpp</a> + contains an implementation of <code class="computeroutput"><span class="identifier">protect</span></code>. + To <code class="computeroutput"><span class="identifier">protect</span></code> a bind function + object from evaluation, use <code class="computeroutput"><span class="identifier">protect</span><span class="special">(</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...))</span></code>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.purpose.overloaded_operators_new_in_boos"></a><a class="link" href="bind.html#bind.purpose.overloaded_operators_new_in_boos" title="Overloaded operators (new in Boost 1.33)">Overloaded + operators (new in Boost 1.33)</a> +</h3></div></div></div> +<p> + For convenience, the function objects produced by <code class="computeroutput"><span class="identifier">bind</span></code> + overload the logical not operator <code class="computeroutput"><span class="special">!</span></code> + and the relational and logical operators <code class="computeroutput"><span class="special">==,</span> + <span class="special">!=,</span> <span class="special"><,</span> + <span class="special"><=,</span> <span class="special">>,</span> + <span class="special">>=,</span> <span class="special">&&,</span> + <span class="special">||</span></code>. + </p> +<p> + <code class="computeroutput"><span class="special">!</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> + <span class="special">...)</span></code> is equivalent to <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">logical_not</span><span class="special">(),</span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> + <span class="special">...))</span></code>, where <code class="computeroutput"><span class="identifier">logical_not</span></code> + is a function object that takes one argument <code class="computeroutput"><span class="identifier">x</span></code> + and returns <code class="computeroutput"><span class="special">!</span><span class="identifier">x</span></code>. + </p> +<p> + <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span> + <span class="identifier">op</span> <span class="identifier">x</span></code>, + where <span class="underline">op</span> is a relational or logical + operator, is equivalent to <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">relation</span><span class="special">(),</span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> + <span class="special">...),</span> <span class="identifier">x</span><span class="special">)</span></code>, where <code class="computeroutput"><span class="identifier">relation</span></code> + is a function object that takes two arguments <code class="computeroutput"><span class="identifier">a</span></code> + and <code class="computeroutput"><span class="identifier">b</span></code> and returns <code class="computeroutput"><span class="identifier">a</span> <span class="identifier">op</span> <span class="identifier">b</span></code>. + </p> +<p> + What this means in practice is that you can conveniently negate the result + of <code class="computeroutput"><span class="identifier">bind</span></code>: + </p> +<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">remove_if</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">,</span> <span class="special">!</span><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">visible</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">));</span> <span class="comment">// remove invisible objects</span> +</pre> +<p> + and compare the result of <code class="computeroutput"><span class="identifier">bind</span></code> + against a value: + </p> +<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">find_if</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">,</span> <span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)</span> <span class="special">==</span> <span class="string">"Peter"</span><span class="special">);</span> +<span class="identifier">std</span><span class="special">::</span><span class="identifier">find_if</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">,</span> <span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)</span> <span class="special">==</span> <span class="string">"Peter"</span> <span class="special">||</span> <span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)</span> <span class="special">==</span> <span class="string">"Paul"</span><span class="special">);</span> +</pre> +<p> + against a <span class="emphasis"><em>placeholder</em></span>: + </p> +<pre class="programlisting"><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)</span> <span class="special">==</span> <span class="identifier">_2</span> +</pre> +<p> + or against another <span class="emphasis"><em>bind expression</em></span>: + </p> +<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">sort</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">,</span> <span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)</span> <span class="special"><</span> <span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">_2</span><span class="special">));</span> <span class="comment">// sort by name</span> +</pre> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="bind.examples"></a><a class="link" href="bind.html#bind.examples" title="Examples">Examples</a> +</h2></div></div></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.examples.using_bind_with_standard_algorit"></a><a class="link" href="bind.html#bind.examples.using_bind_with_standard_algorit" title="Using bind with standard algorithms">Using + bind with standard algorithms</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">image</span><span class="special">;</span> + +<span class="keyword">class</span> <span class="identifier">animation</span> +<span class="special">{</span> +<span class="keyword">public</span><span class="special">:</span> + <span class="keyword">void</span> <span class="identifier">advance</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">ms</span><span class="special">);</span> + <span class="keyword">bool</span> <span class="identifier">inactive</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">void</span> <span class="identifier">render</span><span class="special">(</span><span class="identifier">image</span> <span class="special">&</span> <span class="identifier">target</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +<span class="special">};</span> + +<span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="identifier">animation</span><span class="special">></span> <span class="identifier">anims</span><span class="special">;</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">C</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">P</span><span class="special">></span> <span class="keyword">void</span> <span class="identifier">erase_if</span><span class="special">(</span><span class="identifier">C</span> <span class="special">&</span> <span class="identifier">c</span><span class="special">,</span> <span class="identifier">P</span> <span class="identifier">pred</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">c</span><span class="special">.</span><span class="identifier">erase</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">remove_if</span><span class="special">(</span><span class="identifier">c</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">c</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">pred</span><span class="special">),</span> <span class="identifier">c</span><span class="special">.</span><span class="identifier">end</span><span class="special">());</span> +<span class="special">}</span> + +<span class="keyword">void</span> <span class="identifier">update</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">ms</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">anims</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">anims</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">animation</span><span class="special">::</span><span class="identifier">advance</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">,</span> <span class="identifier">ms</span><span class="special">));</span> + <span class="identifier">erase_if</span><span class="special">(</span><span class="identifier">anims</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span><span class="special">(&</span><span class="identifier">animation</span><span class="special">::</span><span class="identifier">inactive</span><span class="special">));</span> +<span class="special">}</span> + +<span class="keyword">void</span> <span class="identifier">render</span><span class="special">(</span><span class="identifier">image</span> <span class="special">&</span> <span class="identifier">target</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">anims</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">anims</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">animation</span><span class="special">::</span><span class="identifier">render</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">target</span><span class="special">)));</span> +<span class="special">}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.examples.using_bind_with_boost_function"></a><a class="link" href="bind.html#bind.examples.using_bind_with_boost_function" title="Using bind with Boost.Function">Using bind + with Boost.Function</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">button</span> +<span class="special">{</span> +<span class="keyword">public</span><span class="special">:</span> + <a href="../../../../libs/function/index.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">function</span></code></a><span class="special"><</span><span class="keyword">void</span><span class="special">()></span> <span class="identifier">onClick</span><span class="special">;</span> +<span class="special">};</span> + +<span class="keyword">class</span> <span class="identifier">player</span> +<span class="special">{</span> +<span class="keyword">public</span><span class="special">:</span> + <span class="keyword">void</span> <span class="identifier">play</span><span class="special">();</span> + <span class="keyword">void</span> <span class="identifier">stop</span><span class="special">();</span> +<span class="special">};</span> + +<span class="identifier">button</span> <span class="identifier">playButton</span><span class="special">,</span> <span class="identifier">stopButton</span><span class="special">;</span> +<span class="identifier">player</span> <span class="identifier">thePlayer</span><span class="special">;</span> + +<span class="keyword">void</span> <span class="identifier">connect</span><span class="special">()</span> +<span class="special">{</span> + <span class="identifier">playButton</span><span class="special">.</span><span class="identifier">onClick</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">player</span><span class="special">::</span><span class="identifier">play</span><span class="special">,</span> <span class="special">&</span><span class="identifier">thePlayer</span><span class="special">);</span> + <span class="identifier">stopButton</span><span class="special">.</span><span class="identifier">onClick</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">player</span><span class="special">::</span><span class="identifier">stop</span><span class="special">,</span> <span class="special">&</span><span class="identifier">thePlayer</span><span class="special">);</span> +<span class="special">}</span> +</pre> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="bind.limitations"></a><a class="link" href="bind.html#bind.limitations" title="Limitations">Limitations</a> +</h2></div></div></div> +<p> + As a general rule, the function objects generated by <code class="computeroutput"><span class="identifier">bind</span></code> + 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 the <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2002/n1385.htm" target="_top">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 class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">T</span> <span class="special">&</span> <span class="identifier">t</span><span class="special">);</span> +</pre> +<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> + On compilers that support partial ordering of function templates, a possible + solution is to add an overload: + </p> +<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">T</span> <span class="special">&</span> <span class="identifier">t</span><span class="special">);</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span> <span class="special">&</span> <span class="identifier">t</span><span class="special">);</span> +</pre> +<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> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="bind.faq"></a><a class="link" href="bind.html#bind.faq" title="Frequently Asked Questions">Frequently Asked Questions</a> +</h2></div></div></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.faq.why_doesn_t_this_compile"></a><a class="link" href="bind.html#bind.faq.why_doesn_t_this_compile" title="Why doesn't this compile?">Why doesn't this compile?</a> +</h3></div></div></div> +<p> + See the dedicated <a class="link" href="bind.html#bind.troubleshooting" title="Troubleshooting">Troubleshooting section</a>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.faq.why_does_this_compile_it_should_"></a><a class="link" href="bind.html#bind.faq.why_does_this_compile_it_should_" title="Why does this compile? It should not.">Why does this + compile? It should not.</a> +</h3></div></div></div> +<p> + Probably because you used the general <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code> + syntax, thereby instructing <code class="computeroutput"><span class="identifier">bind</span></code> + to not "inspect" f to detect arity and return type errors. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.faq.Q_forms"></a><a class="link" href="bind.html#bind.faq.Q_forms" title="What is the difference between bind(f, ...) and bind<R>(f, ...)?">What is the difference between <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code> and + <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code>?</a> +</h3></div></div></div> +<p> + The first form instructs <code class="computeroutput"><span class="identifier">bind</span></code> + to inspect the type of <code class="computeroutput"><span class="identifier">f</span></code> + 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 <code class="computeroutput"><span class="identifier">f</span></code>. + It must be a function, function pointer, member function pointer, or a function + object that defines a nested type named <code class="computeroutput"><span class="identifier">result_type</span></code>; + in short, it must be something that <code class="computeroutput"><span class="identifier">bind</span></code> + can recognize. + </p> +<p> + The second form instructs <code class="computeroutput"><span class="identifier">bind</span></code> + to not attempt to recognize the type of <code class="computeroutput"><span class="identifier">f</span></code>. + It is generally used with function objects that do not, or cannot, expose + <code class="computeroutput"><span class="identifier">result_type</span></code>, but it can also + be used with nonstandard functions. For example, the current implementation + does not automatically recognize variable-argument functions like <code class="computeroutput"><span class="identifier">printf</span></code>, so you will have to use <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(</span><span class="identifier">printf</span><span class="special">,</span> <span class="special">...)</span></code>. Note + that an alternative <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">type</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(),</span> <span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code> + 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 <code class="computeroutput"><span class="identifier">f</span></code> is + a function object, and in most cases will not handle the second form when + <code class="computeroutput"><span class="identifier">f</span></code> is a function (pointer) + or a member function pointer. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.faq.does_bind_work_with_windows_api_"></a><a class="link" href="bind.html#bind.faq.does_bind_work_with_windows_api_" title="Does bind work with Windows API functions?">Does bind + work with Windows API functions?</a> +</h3></div></div></div> +<p> + Yes, if you <a class="link" href="bind.html#bind.implementation.stdcall" title="__stdcall, __cdecl, __fastcall, and pascal Support"><code class="computeroutput"><span class="preprocessor">#define</span> + <span class="identifier">BOOST_BIND_ENABLE_STDCALL</span></code></a>. + An alternative is to treat the function as a <a class="link" href="bind.html#bind.purpose.with_function_objects" title="Using bind with function objects">generic + function object</a> and use the <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code> + syntax. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.faq.does_bind_work_with_com_methods"></a><a class="link" href="bind.html#bind.faq.does_bind_work_with_com_methods" title="Does bind work with COM methods?">Does bind work + with COM methods?</a> +</h3></div></div></div> +<p> + Yes, if you <a class="link" href="bind.html#bind.implementation.stdcall" title="__stdcall, __cdecl, __fastcall, and pascal Support"><code class="computeroutput"><span class="preprocessor">#define</span> + <span class="identifier">BOOST_MEM_FN_ENABLE_STDCALL</span></code></a>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.faq.does_bind_work_with_mac_toolbox_"></a><a class="link" href="bind.html#bind.faq.does_bind_work_with_mac_toolbox_" title="Does bind work with Mac toolbox functions?">Does bind + work with Mac toolbox functions?</a> +</h3></div></div></div> +<p> + Yes, if you <a class="link" href="bind.html#bind.implementation.stdcall" title="__stdcall, __cdecl, __fastcall, and pascal Support"><code class="computeroutput"><span class="preprocessor">#define</span> + <span class="identifier">BOOST_BIND_ENABLE_PASCAL</span></code></a>. + An alternative is to treat the function as a <a class="link" href="bind.html#bind.purpose.with_function_objects" title="Using bind with function objects">generic + function object</a> and use the <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code> + syntax. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.faq.does_bind_work_with_extern_c_fun"></a><a class="link" href="bind.html#bind.faq.does_bind_work_with_extern_c_fun" title='Does bind work with extern "C" functions?'>Does bind + work with extern "C" functions?</a> +</h3></div></div></div> +<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 <code class="computeroutput"><span class="identifier">bind</span></code> is expected to handle + the problem transparently; this implementation does not. As usual, the workaround + is to treat the function as a <a class="link" href="bind.html#bind.purpose.with_function_objects" title="Using bind with function objects">generic + function object</a> and use the <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code> + syntax. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.faq.why_doesn_t_bind_automatically_r"></a><a class="link" href="bind.html#bind.faq.why_doesn_t_bind_automatically_r" title="Why doesn't bind automatically recognize nonstandard functions?">Why doesn't + bind automatically recognize nonstandard functions?</a> +</h3></div></div></div> +<p> + Non-portable extensions, in general, should default to off to prevent vendor + lock-in. Had the <a class="link" href="bind.html#bind.implementation.stdcall" title="__stdcall, __cdecl, __fastcall, and pascal Support">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 <code class="computeroutput"><span class="identifier">__stdcall</span></code> (<code class="computeroutput"><span class="identifier">__fastcall</span></code>) + their default calling convention, in which case no separate support would + be necessary. + </p> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="bind.troubleshooting"></a><a class="link" href="bind.html#bind.troubleshooting" title="Troubleshooting">Troubleshooting</a> +</h2></div></div></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.troubleshooting.incorrect_number_of_arguments"></a><a class="link" href="bind.html#bind.troubleshooting.incorrect_number_of_arguments" title="Incorrect number of arguments">Incorrect + number of arguments</a> +</h3></div></div></div> +<p> + In a <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">,</span> + <span class="special">...,</span> <span class="identifier">aN</span><span class="special">)</span></code> expression, the function object <code class="computeroutput"><span class="identifier">f</span></code> must be able to take exactly N arguments. + This error is normally detected at "bind time"; in other words, + the compilation error is reported on the line where <code class="computeroutput"><span class="identifier">bind</span><span class="special">()</span></code> is invoked: + </p> +<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">int</span><span class="special">);</span> + +<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> +<span class="special">{</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="number">1</span><span class="special">);</span> <span class="comment">// error, f takes two arguments</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">);</span> <span class="comment">// OK</span> +<span class="special">}</span> +</pre> +<p> + A common variation of this error is to forget that member functions have + an implicit "this" argument: + </p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">X</span> +<span class="special">{</span> + <span class="keyword">int</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span><span class="special">);</span> +<span class="special">}</span> + +<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> +<span class="special">{</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="number">1</span><span class="special">);</span> <span class="comment">// error, X::f takes two arguments</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">,</span> <span class="number">1</span><span class="special">);</span> <span class="comment">// OK</span> +<span class="special">}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.troubleshooting.the_function_object_cannot_be_ca"></a><a class="link" href="bind.html#bind.troubleshooting.the_function_object_cannot_be_ca" title="The function object cannot be called with the specified arguments">The + function object cannot be called with the specified arguments</a> +</h3></div></div></div> +<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 + <code class="computeroutput"><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span></code> on a line that looks like: + </p> +<pre class="programlisting"><span class="keyword">return</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">a</span><span class="special">[</span><span class="identifier">a1_</span><span class="special">],</span> <span class="identifier">a</span><span class="special">[</span><span class="identifier">a2_</span><span class="special">]);</span> +</pre> +<p> + An example of this kind of error: + </p> +<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span><span class="special">);</span> + +<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> +<span class="special">{</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="string">"incompatible"</span><span class="special">);</span> <span class="comment">// OK so far, no call</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="string">"incompatible"</span><span class="special">)();</span> <span class="comment">// error, "incompatible" is not an int</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">);</span> <span class="comment">// OK</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)(</span><span class="string">"incompatible"</span><span class="special">);</span> <span class="comment">// error, "incompatible" is not an int</span> +<span class="special">}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.troubleshooting.accessing_an_argument_that_does_"></a><a class="link" href="bind.html#bind.troubleshooting.accessing_an_argument_that_does_" title="Accessing an argument that does not exist">Accessing + an argument that does not exist</a> +</h3></div></div></div> +<p> + The placeholder <code class="computeroutput"><span class="identifier">_N</span></code> selects + the argument at position <code class="computeroutput"><span class="identifier">N</span></code> + 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 class="programlisting"><span class="keyword">int</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span><span class="special">);</span> + +<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> +<span class="special">{</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">);</span> <span class="comment">// OK</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)();</span> <span class="comment">// error, there is no argument number 1</span> +<span class="special">}</span> +</pre> +<p> + The error is usually reported in <code class="computeroutput"><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span></code>, at + a line similar to: + </p> +<pre class="programlisting"><span class="keyword">return</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">a</span><span class="special">[</span><span class="identifier">a1_</span><span class="special">]);</span> +</pre> +<p> + When emulating <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bind1st</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">a</span><span class="special">)</span></code>, a common mistake of this category is to + type <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">_2</span><span class="special">)</span></code> + instead of the correct <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> + <span class="identifier">a</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)</span></code>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.troubleshooting.inappropriate_use_of_bind_f"></a><a class="link" href="bind.html#bind.troubleshooting.inappropriate_use_of_bind_f" title="Inappropriate use of bind(f, ...)">Inappropriate + use of <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code></a> +</h3></div></div></div> +<p> + The <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">,</span> + <span class="special">...,</span> <span class="identifier">aN</span><span class="special">)</span></code> <a class="link" href="bind.html#bind.faq.Q_forms" title="What is the difference between bind(f, ...) and bind<R>(f, ...)?">form</a> + causes automatic recognition of the type of <code class="computeroutput"><span class="identifier">f</span></code>. + It will not work with arbitrary function objects; <code class="computeroutput"><span class="identifier">f</span></code> + must be a function or a member function pointer. + </p> +<p> + It is possible to use this form with function objects that define <code class="computeroutput"><span class="identifier">result_type</span></code>, but only on compilers that + support partial specialization and partial ordering. In particular, MSVC + up to version 7.0 does not support this syntax for function objects. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.troubleshooting.inappropriate_use_of_bind_r_f"></a><a class="link" href="bind.html#bind.troubleshooting.inappropriate_use_of_bind_r_f" title="Inappropriate use of bind<R>(f, ...)">Inappropriate + use of <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code></a> +</h3></div></div></div> +<p> + The <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">,</span> + <span class="special">...,</span> <span class="identifier">aN</span><span class="special">)</span></code> <a class="link" href="bind.html#bind.faq.Q_forms" title="What is the difference between bind(f, ...) and bind<R>(f, ...)?">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 only on compilers 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> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.troubleshooting.binding_a_nonstandard_function"></a><a class="link" href="bind.html#bind.troubleshooting.binding_a_nonstandard_function" title="Binding a nonstandard function">Binding + a nonstandard function</a> +</h3></div></div></div> +<p> + By default, the <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">,</span> + <span class="special">...,</span> <span class="identifier">aN</span><span class="special">)</span></code> <a class="link" href="bind.html#bind.faq.Q_forms" title="What is the difference between bind(f, ...) and bind<R>(f, ...)?">form</a> + recognizes "ordinary" C++ functions and function pointers. <a class="link" href="bind.html#bind.implementation.stdcall" title="__stdcall, __cdecl, __fastcall, and pascal Support">Functions that use a different calling + convention</a>, or variable-argument functions such as <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">printf</span></code>, + do not work. The general <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">,</span> + <span class="special">...,</span> <span class="identifier">aN</span><span class="special">)</span></code> <a class="link" href="bind.html#bind.faq.Q_forms" title="What is the difference between bind(f, ...) and bind<R>(f, ...)?">form</a> + works with nonstandard functions. + </p> +<p> + On some platforms, extern "C" functions, like <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">strcmp</span></code>, + are not recognized by the short form of <code class="computeroutput"><span class="identifier">bind</span></code>. + </p> +<p> + See also <a class="link" href="bind.html#bind.implementation.stdcall" title="__stdcall, __cdecl, __fastcall, and pascal Support"><code class="computeroutput"><span class="identifier">__stdcall</span></code> + and <code class="computeroutput"><span class="identifier">pascal</span></code> Support</a>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.troubleshooting.binding_an_overloaded_function"></a><a class="link" href="bind.html#bind.troubleshooting.binding_an_overloaded_function" title="Binding an overloaded function">Binding + an overloaded function</a> +</h3></div></div></div> +<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 class="programlisting"><span class="keyword">struct</span> <span class="identifier">X</span> +<span class="special">{</span> + <span class="keyword">int</span><span class="special">&</span> <span class="identifier">get</span><span class="special">();</span> + <span class="keyword">int</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">get</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="special">};</span> + +<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> +<span class="special">{</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">get</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">);</span> +<span class="special">}</span> +</pre> +<p> + The ambiguity can be resolved manually by casting the (member) function pointer + to the desired type: + </p> +<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> +<span class="special">{</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="keyword">static_cast</span><span class="special"><</span> <span class="keyword">int</span> <span class="keyword">const</span><span class="special">&</span> <span class="special">(</span><span class="identifier">X</span><span class="special">::*)</span> <span class="special">()</span> <span class="keyword">const</span> <span class="special">>(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">get</span><span class="special">),</span> <span class="identifier">_1</span><span class="special">);</span> +<span class="special">}</span> +</pre> +<p> + Another, arguably more readable, alternative is to introduce a temporary + variable: + </p> +<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> +<span class="special">{</span> + <span class="keyword">int</span> <span class="keyword">const</span><span class="special">&</span> <span class="special">(</span><span class="identifier">X</span><span class="special">::*</span><span class="identifier">get</span><span class="special">)</span> <span class="special">()</span> <span class="keyword">const</span> <span class="special">=</span> <span class="special">&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">get</span><span class="special">;</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">get</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">);</span> +<span class="special">}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.troubleshooting.modeling_stl_function_object_con"></a><a class="link" href="bind.html#bind.troubleshooting.modeling_stl_function_object_con" title="Modeling STL function object concepts">Modeling + STL function object concepts</a> +</h3></div></div></div> +<p> + The function objects that are produced by <code class="computeroutput"><span class="identifier">bind</span></code> + do not model the STL <a href="http://www.sgi.com/tech/stl/UnaryFunction.html" target="_top"><span class="emphasis"><em>Unary + Function</em></span></a> or <a href="http://www.sgi.com/tech/stl/BinaryFunction.html" target="_top"><span class="emphasis"><em>Binary + Function</em></span></a> concepts, even when the function objects are + unary or binary operations, because the function object types are missing + public typedefs <code class="computeroutput"><span class="identifier">result_type</span></code> + and <code class="computeroutput"><span class="identifier">argument_type</span></code> or <code class="computeroutput"><span class="identifier">first_argument_type</span></code> and <code class="computeroutput"><span class="identifier">second_argument_type</span></code>. + In cases where these typedefs are desirable, however, the utility function + <code class="computeroutput"><span class="identifier">make_adaptable</span></code> can be used + to adapt unary and binary function objects to these concepts. This allows + unary and binary function objects resulting from <code class="computeroutput"><span class="identifier">bind</span></code> + to be combined with STL templates such as <a href="http://en.cppreference.com/w/cpp/utility/functional/unary_negate" target="_top"><code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">unary_negate</span></code></a> + and <a href="http://en.cppreference.com/w/cpp/utility/functional/binary_negate" target="_top"><code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">binary_negate</span></code></a>. + </p> +<p> + The <code class="computeroutput"><span class="identifier">make_adaptable</span></code> function + is defined in <a href="../../include/boost/bind/make_adaptable.hpp" target="_top"><code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bind</span><span class="special">/</span><span class="identifier">make_adaptable</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a>, + which must be included explicitly in addition to <a href="../../include/boost/bind.hpp" target="_top"><code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a>: + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bind</span><span class="special">/</span><span class="identifier">make_adaptable</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F</span><span class="special">></span> <span class="emphasis"><em>unspecified-type</em></span> <span class="identifier">make_adaptable</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F</span><span class="special">></span> <span class="emphasis"><em>unspecified-unary-functional-type</em></span> <span class="identifier">make_adaptable</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F</span><span class="special">></span> <span class="emphasis"><em>unspecified-binary-functional-type</em></span> <span class="identifier">make_adaptable</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A3</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F</span><span class="special">></span> <span class="emphasis"><em>unspecified-ternary-functional-type</em></span> <span class="identifier">make_adaptable</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A3</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A4</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F</span><span class="special">></span> <span class="emphasis"><em>unspecified-4-ary-functional-type</em></span> <span class="identifier">make_adaptable</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">);</span> +</pre> +<p> + This example shows how to use <code class="computeroutput"><span class="identifier">make_adaptable</span></code> + to make a predicate for "is not a space": + </p> +<pre class="programlisting"><span class="keyword">typedef</span> <span class="keyword">char</span> <span class="identifier">char_t</span><span class="special">;</span> +<span class="identifier">std</span><span class="special">::</span><span class="identifier">locale</span> <span class="identifier">loc</span><span class="special">(</span><span class="string">""</span><span class="special">);</span> +<span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ctype</span><span class="special"><</span><span class="identifier">char_t</span><span class="special">>&</span> <span class="identifier">ct</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">use_facet</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">ctype</span><span class="special"><</span><span class="identifier">char_t</span><span class="special">></span> <span class="special">>(</span><span class="identifier">loc</span><span class="special">);</span> + +<span class="keyword">auto</span> <span class="identifier">isntspace</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">not1</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_adaptable</span><span class="special"><</span><span class="keyword">bool</span><span class="special">,</span> <span class="identifier">char_t</span><span class="special">>(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">ctype</span><span class="special"><</span><span class="identifier">char_t</span><span class="special">>::</span><span class="identifier">is</span><span class="special">,</span> <span class="special">&</span><span class="identifier">ct</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ctype_base</span><span class="special">::</span><span class="identifier">space</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)));</span> +</pre> +<p> + In this example, <code class="computeroutput"><span class="identifier">bind</span></code> creates + the "is a space" (unary) predicate. It is then passed to <code class="computeroutput"><span class="identifier">make_adaptable</span></code> so that a function object + modeling the <span class="emphasis"><em>Unary Function</em></span> concept can be created, + serving as the argument to <a href="http://en.cppreference.com/w/cpp/utility/functional/not1" target="_top"><code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">not1</span></code></a>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.troubleshooting.const_in_signatures"></a><a class="link" href="bind.html#bind.troubleshooting.const_in_signatures" title="const in signatures"><code class="computeroutput"><span class="keyword">const</span></code> in signatures</a> +</h3></div></div></div> +<p> + Some compilers, including MSVC 6.0 and Borland C++ 5.5.1, have problems with + the top-level <code class="computeroutput"><span class="keyword">const</span></code> in function + signatures: + </p> +<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span> <span class="keyword">const</span><span class="special">);</span> + +<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> +<span class="special">{</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="number">1</span><span class="special">);</span> <span class="comment">// error</span> +<span class="special">}</span> +</pre> +<p> + Workaround: remove the <code class="computeroutput"><span class="keyword">const</span></code> + qualifier from the argument. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.troubleshooting.msvc_specific_using_boost_bind"></a><a class="link" href="bind.html#bind.troubleshooting.msvc_specific_using_boost_bind" title="MSVC specific: using boost::bind;">MSVC + specific: <code class="computeroutput"><span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">;</span></code></a> +</h3></div></div></div> +<p> + On MSVC (up to version 7.0), when <code class="computeroutput"><span class="identifier">boostbind</span></code> + is brought into scope with an using declaration: + </p> +<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">;</span> +</pre> +<p> + the syntax <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code> + does not work. Workaround: either use the qualified name, <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span></code>, + or use an using directive instead: + </p> +<pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">;</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.troubleshooting.msvc_specific_class_templates_sh"></a><a class="link" href="bind.html#bind.troubleshooting.msvc_specific_class_templates_sh" title="MSVC specific: class templates shadow function templates">MSVC + specific: class templates shadow function templates</a> +</h3></div></div></div> +<p> + On MSVC (up to version 7.0), a nested class template named <code class="computeroutput"><span class="identifier">bind</span></code> will shadow the function template + <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span></code>, breaking the <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code>syntax. + Unfortunately, some libraries contain nested class templates named <code class="computeroutput"><span class="identifier">bind</span></code> (ironically, such code is often an + MSVC specific workaround.) + </p> +<p> + The workaround is to use the alternative <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">type</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(),</span> <span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code> + syntax. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.troubleshooting.msvc_specific_in_signatures_trea"></a><a class="link" href="bind.html#bind.troubleshooting.msvc_specific_in_signatures_trea" title="MSVC specific: ... in signatures treated as type">MSVC + specific: <code class="computeroutput"><span class="special">...</span></code> in signatures treated + as type</a> +</h3></div></div></div> +<p> + MSVC (up to version 7.0) treats the ellipsis in a variable argument function + (such as <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">printf</span></code>) as a type. Therefore, it will accept + the (incorrect in the current implementation) form: + </p> +<pre class="programlisting"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">printf</span><span class="special">,</span> <span class="string">"%s\n"</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">);</span> +</pre> +<p> + and will reject the correct version: + </p> +<pre class="programlisting"><span class="identifier">bind</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(</span><span class="identifier">printf</span><span class="special">,</span> <span class="string">"%s\n"</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">);</span> +</pre> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="bind.interface"></a><a class="link" href="bind.html#bind.interface" title="Interface">Interface</a> +</h2></div></div></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.interface.synopsys"></a><a class="link" href="bind.html#bind.interface.synopsys" title="Synopsis">Synopsis</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> +<span class="special">{</span> +<span class="comment">// no arguments</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F</span><span class="special">></span> <span class="emphasis"><em>unspecified-1</em></span> <a class="link" href="bind.html#bind_1"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">></span> <span class="emphasis"><em>unspecified-1-1</em></span> <a class="link" href="bind.html#bind_1_1"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="emphasis"><em>unspecified-2</em></span> <a class="link" href="bind.html#bind_2"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">());</span> + +<span class="comment">// one argument</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-3</em></span> <a class="link" href="bind.html#bind_3"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-3-1</em></span> <a class="link" href="bind.html#bind_3_1"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">B1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-4</em></span> <a class="link" href="bind.html#bind_4"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">(</span><span class="identifier">B1</span><span class="special">),</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-5</em></span> <a class="link" href="bind.html#bind_5"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">(),</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-6</em></span> <a class="link" href="bind.html#bind_6"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">()</span> <span class="keyword">const</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-6-1</em></span> <a class="link" href="bind.html#bind_6_1"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="identifier">T</span><span class="special">::*</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">);</span> + +<span class="comment">// two arguments</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-7</em></span> <a class="link" href="bind.html#bind_7"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">A2</span> <span class="identifier">a2</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-7-1</em></span> <a class="link" href="bind.html#bind_7_1"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">A2</span> <span class="identifier">a2</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">B1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">B2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-8</em></span> <a class="link" href="bind.html#bind_8"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">(</span><span class="identifier">B1</span><span class="special">,</span> <span class="identifier">B2</span><span class="special">),</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">A2</span> <span class="identifier">a2</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">B1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-9</em></span> <a class="link" href="bind.html#bind_9"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">(</span><span class="identifier">B1</span><span class="special">),</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">A2</span> <span class="identifier">a2</span><span class="special">);</span> + +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">B1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-10</em></span> <a class="link" href="bind.html#bind_10"><code class="computeroutput"><span class="identifier">bind</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">(</span><span class="identifier">B1</span><span class="special">)</span> <span class="keyword">const</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">A2</span> <span class="identifier">a2</span><span class="special">);</span> + +<span class="comment">// implementation defined number of additional overloads for more arguments</span> +<span class="special">}</span> + +<span class="keyword">namespace</span> +<span class="special">{</span> + <span class="emphasis"><em>unspecified-placeholder-type-1</em></span> <span class="identifier">_1</span><span class="special">;</span> + + <span class="emphasis"><em>unspecified-placeholder-type-2</em></span> <span class="identifier">_2</span><span class="special">;</span> + + <span class="emphasis"><em>unspecified-placeholder-type-3</em></span> <span class="identifier">_3</span><span class="special">;</span> + +<span class="comment">// implementation defined number of additional placeholder definitions</span> +<span class="special">}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.interface.common_requirements"></a><a class="link" href="bind.html#bind.interface.common_requirements" title="Common requirements">Common requirements</a> +</h3></div></div></div> +<p> + All <span class="emphasis"><em>unspecified-N</em></span> types returned by <code class="computeroutput"><span class="identifier">bind</span></code> + are <span class="emphasis"><em>CopyConstructible</em></span>. <span class="emphasis"><em>unspecified-N</em></span><code class="computeroutput"><span class="special">::</span><span class="identifier">result_type</span></code> + is defined as the return type of <span class="emphasis"><em>unspecified-N</em></span><code class="computeroutput"><span class="special">::</span><span class="keyword">operator</span><span class="special">()</span></code>. + </p> +<p> + All <span class="emphasis"><em>unspecified-placeholder-N</em></span> types are <span class="emphasis"><em>CopyConstructible</em></span>. + Their copy constructors do not throw exceptions. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.interface.common_definitions"></a><a class="link" href="bind.html#bind.interface.common_definitions" title="Common definitions">Common definitions</a> +</h3></div></div></div> +<p> + The function μ<code class="computeroutput"><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">v1</span><span class="special">,</span> + <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">)</span></code>, where <code class="computeroutput"><span class="identifier">m</span></code> + is a nonnegative integer, is defined as: + </p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">x</span><span class="special">.</span><span class="identifier">get</span><span class="special">()</span></code>, + when <code class="computeroutput"><span class="identifier">x</span></code> is of type <a href="../../../../libs/core/doc/html/core/ref.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">reference_wrapper</span></code></a><code class="computeroutput"><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code> for some type <code class="computeroutput"><span class="identifier">T</span></code>; + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">vk</span></code>, when <code class="computeroutput"><span class="identifier">x</span></code> is (a copy of) the placeholder <span class="emphasis"><em>_k</em></span> + for some positive integer <span class="emphasis"><em>k</em></span>; + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">x</span><span class="special">(</span><span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">)</span></code> when <code class="computeroutput"><span class="identifier">x</span></code> + is (a copy of) a function object returned by <code class="computeroutput"><span class="identifier">bind</span></code>; + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">x</span></code> otherwise. + </li> +</ul></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.interface.bind"></a><a class="link" href="bind.html#bind.interface.bind" title="bind"><code class="computeroutput"><span class="identifier">bind</span></code></a> +</h3></div></div></div> +<a name="bind_1"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F</span><span class="special">></span> <span class="emphasis"><em>unspecified-1</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> A function object λ such that the + expression λ<code class="computeroutput"><span class="special">(</span><span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">)</span></code> + is equivalent to <code class="computeroutput"><span class="identifier">f</span><span class="special">()</span></code>, + implicitly converted to <code class="computeroutput"><span class="identifier">R</span></code>. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing unless the copy constructor of + <code class="computeroutput"><span class="identifier">F</span></code> throws an exception. + </li> +</ul></div> +<a name="bind_1_1"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">></span> <span class="emphasis"><em>unspecified-1-1</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Effects:</em></span> Equivalent to <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="keyword">typename</span> + <span class="identifier">F</span><span class="special">::</span><span class="identifier">result_type</span><span class="special">,</span> + <span class="identifier">F</span><span class="special">>(</span><span class="identifier">f</span><span class="special">)</span></code>. + </li> +<li class="listitem"> + <span class="emphasis"><em>Notes:</em></span> Implementations are allowed to infer the + return type of <code class="computeroutput"><span class="identifier">f</span></code> via + other means as an extension, without relying on the <code class="computeroutput"><span class="identifier">result_type</span></code> + member. + </li> +</ul></div> +<a name="bind_2"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="emphasis"><em>unspecified-2</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">())</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> A function object λ such that the + expression λ<code class="computeroutput"><span class="special">(</span><span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">)</span></code> + is equivalent to <code class="computeroutput"><span class="identifier">f</span><span class="special">()</span></code>. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing. + </li> +</ul></div> +<a name="bind_3"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-3</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> A function object λ such that the + expression λ<code class="computeroutput"><span class="special">(</span><span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">)</span></code> + is equivalent to <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span></code>μ<code class="computeroutput"><span class="special">(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">))</span></code>, + implicitly converted to <code class="computeroutput"><span class="identifier">R</span></code>. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing unless the copy constructors of + <code class="computeroutput"><span class="identifier">F</span></code> or <code class="computeroutput"><span class="identifier">A1</span></code> + throw an exception. + </li> +</ul></div> +<a name="bind_3_1"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-3-1</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Effects:</em></span> Equivalent to <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="keyword">typename</span> + <span class="identifier">F</span><span class="special">::</span><span class="identifier">result_type</span><span class="special">,</span> + <span class="identifier">F</span><span class="special">,</span> + <span class="identifier">A1</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">a1</span><span class="special">)</span></code>. + </li> +<li class="listitem"> + <span class="emphasis"><em>Notes:</em></span> Implementations are allowed to infer the + return type of <code class="computeroutput"><span class="identifier">f</span></code> via + other means as an extension, without relying on the <code class="computeroutput"><span class="identifier">result_type</span></code> + member. + </li> +</ul></div> +<a name="bind_4"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">B1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-4</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">(</span><span class="identifier">B1</span><span class="special">),</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> A function object λ such that the + expression λ<code class="computeroutput"><span class="special">(</span><span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">)</span></code> + is equivalent to <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span></code>μ<code class="computeroutput"><span class="special">(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">))</span></code>. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing unless the copy constructor of + <code class="computeroutput"><span class="identifier">A1</span></code> throws an exception. + </li> +</ul></div> +<a name="bind_5"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-5</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">(),</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <span class="emphasis"><em>Effects:</em></span> Equivalent to <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span></code><a href="../../../../libs/bind/mem_fn.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span></code></a><code class="computeroutput"><span class="special">(</span><span class="identifier">f</span><span class="special">),</span> <span class="identifier">a1</span><span class="special">)</span></code>. + </li></ul></div> +<a name="bind_6"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-6</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">()</span> <span class="keyword">const</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <span class="emphasis"><em>Effects:</em></span> Equivalent to <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span></code><a href="../../../../libs/bind/mem_fn.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span></code></a><code class="computeroutput"><span class="special">(</span><span class="identifier">f</span><span class="special">),</span> <span class="identifier">a1</span><span class="special">)</span></code>. + </li></ul></div> +<a name="bind_6_1"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-6-1</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">R</span> <span class="identifier">T</span><span class="special">::*</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <span class="emphasis"><em>Effects:</em></span> Equivalent to <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span></code><a href="../../../../libs/bind/mem_fn.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span></code></a><code class="computeroutput"><span class="special">(</span><span class="identifier">f</span><span class="special">),</span> <span class="identifier">a1</span><span class="special">)</span></code>. + </li></ul></div> +<a name="bind_7"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-7</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">A2</span> <span class="identifier">a2</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> A function object λ such that the + expression λ<code class="computeroutput"><span class="special">(</span><span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">)</span></code> + is equivalent to <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span></code>μ<code class="computeroutput"><span class="special">(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">),</span> </code>μ<code class="computeroutput"><span class="special">(</span><span class="identifier">a2</span><span class="special">,</span> <span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">))</span></code>, + implicitly converted to <code class="computeroutput"><span class="identifier">R</span></code>. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing unless the copy constructors of + <code class="computeroutput"><span class="identifier">F</span></code>, <code class="computeroutput"><span class="identifier">A1</span></code> + or <code class="computeroutput"><span class="identifier">A2</span></code> throw an exception. + </li> +</ul></div> +<a name="bind_7_1"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-7-1</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">A2</span> <span class="identifier">a2</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Effects:</em></span> Equivalent to <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="keyword">typename</span> + <span class="identifier">F</span><span class="special">::</span><span class="identifier">result_type</span><span class="special">,</span> + <span class="identifier">F</span><span class="special">,</span> + <span class="identifier">A1</span><span class="special">,</span> + <span class="identifier">A2</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">)</span></code>. + </li> +<li class="listitem"> + <span class="emphasis"><em>Notes:</em></span> Implementations are allowed to infer the + return type of <code class="computeroutput"><span class="identifier">f</span></code> via + other means as an extension, without relying on the <code class="computeroutput"><span class="identifier">result_type</span></code> + member. + </li> +</ul></div> +<a name="bind_8"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">B1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">B2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-8</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">(</span><span class="identifier">B1</span><span class="special">,</span> <span class="identifier">B2</span><span class="special">),</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">A2</span> <span class="identifier">a2</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> A function object λ such that the + expression λ<code class="computeroutput"><span class="special">(</span><span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">)</span></code> + is equivalent to <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span></code>μ<code class="computeroutput"><span class="special">(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">),</span> </code>μ<code class="computeroutput"><span class="special">(</span><span class="identifier">a2</span><span class="special">,</span> <span class="identifier">v1</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">vm</span><span class="special">))</span></code>. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing unless the copy constructors of + <code class="computeroutput"><span class="identifier">A1</span></code> or <code class="computeroutput"><span class="identifier">A2</span></code> + throw an exception. + </li> +</ul></div> +<a name="bind_9"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">B1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-9</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">(</span><span class="identifier">B1</span><span class="special">),</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">A2</span> <span class="identifier">a2</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <span class="emphasis"><em>Effects:</em></span> Equivalent to <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span></code><a href="../../../../libs/bind/mem_fn.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span></code></a><code class="computeroutput"><span class="special">(</span><span class="identifier">f</span><span class="special">),</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">)</span></code>. + </li></ul></div> +<a name="bind_10"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">B1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-10</em></span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">f</span><span class="special">)</span> <span class="special">(</span><span class="identifier">B1</span><span class="special">)</span> <span class="keyword">const</span><span class="special">,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">A2</span> <span class="identifier">a2</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <span class="emphasis"><em>Effects:</em></span> Equivalent to <code class="computeroutput"><span class="identifier">bind</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span></code><a href="../../../../libs/bind/mem_fn.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span></code></a><code class="computeroutput"><span class="special">(</span><span class="identifier">f</span><span class="special">),</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">)</span></code>. + </li></ul></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.interface.additional_overloads"></a><a class="link" href="bind.html#bind.interface.additional_overloads" title="Additional overloads">Additional overloads</a> +</h3></div></div></div> +<p> + Implementations are allowed to provide additional <code class="computeroutput"><span class="identifier">bind</span></code> + overloads in order to support more arguments or different function pointer + variations. + </p> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="bind.implementation"></a><a class="link" href="bind.html#bind.implementation" title="Implementation">Implementation</a> +</h2></div></div></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.implementation.files"></a><a class="link" href="bind.html#bind.implementation.files" title="Files">Files</a> +</h3></div></div></div> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <a href="../../include/boost/bind.hpp" target="_top">boost/bind.hpp</a> (main + header) + </li> +<li class="listitem"> + <a href="../../include/boost/bind/bind_cc.hpp" target="_top">boost/bind/bind_cc.hpp</a> + (used by <code class="computeroutput"><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span></code>, do not include directly) + </li> +<li class="listitem"> + <a href="../../include/boost/bind/bind_mf_cc.hpp" target="_top">boost/bind/bind_mf_cc.hpp</a> + (used by <code class="computeroutput"><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span></code>, do not include directly) + </li> +<li class="listitem"> + <a href="../../include/boost/bind/bind_template.hpp" target="_top">boost/bind/bind_template.hpp</a> + (used by <code class="computeroutput"><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span></code>, do not include directly) + </li> +<li class="listitem"> + <a href="../../include/boost/bind/arg.hpp" target="_top">boost/bind/arg.hpp</a> + (defines the type of the placeholder arguments) + </li> +<li class="listitem"> + <a href="../../include/boost/bind/placeholders.hpp" target="_top">boost/bind/placeholders.hpp</a> + (defines the <code class="computeroutput"><span class="identifier">_1</span></code>, <code class="computeroutput"><span class="identifier">_2</span></code>, ... <code class="computeroutput"><span class="identifier">_9</span></code> + placeholders) + </li> +<li class="listitem"> + <a href="../../include/boost/bind/apply.hpp" target="_top">boost/bind/apply.hpp</a> + (<code class="computeroutput"><span class="identifier">apply</span></code> helper function + object) + </li> +<li class="listitem"> + <a href="../../include/boost/bind/protect.hpp" target="_top">boost/bind/protect.hpp</a> + (<code class="computeroutput"><span class="identifier">protect</span></code> helper function) + </li> +<li class="listitem"> + <a href="../../include/boost/bind/make_adaptable.hpp" target="_top">boost/bind/make_adaptable.hpp</a> + (<code class="computeroutput"><span class="identifier">make_adaptable</span></code> helper + function) + </li> +<li class="listitem"> + <a href="../../test/bind_test.cpp" target="_top">libs/bind/test/bind_test.cpp</a> + (test) + </li> +<li class="listitem"> + <a href="../../bind_as_compose.cpp" target="_top">libs/bind/bind_as_compose.cpp</a> + (function composition example) + </li> +<li class="listitem"> + <a href="../../bind_visitor.cpp" target="_top">libs/bind/bind_visitor.cpp</a> + (visitor example) + </li> +<li class="listitem"> + <a href="../../test/bind_stdcall_test.cpp" target="_top">libs/bind/test/bind_stdcall_test.cpp</a> + (test with <code class="computeroutput"><span class="identifier">__stdcall</span></code> + functions) + </li> +<li class="listitem"> + <a href="../../test/bind_stdcall_mf_test.cpp" target="_top">libs/bind/test/bind_stdcall_mf_test.cpp</a> + (test with <code class="computeroutput"><span class="identifier">__stdcall</span></code> + member functions) + </li> +<li class="listitem"> + <a href="../../test/bind_fastcall_test.cpp" target="_top">libs/bind/test/bind_fastcall_test.</a> + (test with <code class="computeroutput"><span class="identifier">__fastcall</span></code> + functions) + </li> +<li class="listitem"> + <a href="../../test/bind_fastcall_mf_test.cpp" target="_top">libs/bind/test/bind_fastcall_mf_test.cpp</a> + (test with <code class="computeroutput"><span class="identifier">__fastcall</span></code> + member functions) + </li> +</ul></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.implementation.dependencies"></a><a class="link" href="bind.html#bind.implementation.dependencies" title="Dependencies">Dependencies</a> +</h3></div></div></div> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <a href="../../../../libs/config/config.htm" target="_top">Boost.Config</a> + </li> +<li class="listitem"> + <a href="../../../../libs/core/doc/html/core/ref.html" target="_top">boost/ref.hpp</a> + </li> +<li class="listitem"> + <a href="../../../../libs/bind/mem_fn.html" target="_top">boost/mem_fn.hpp</a> + </li> +<li class="listitem"> + <a href="../../../../boost/type.hpp" target="_top">boost/type.hpp</a> + </li> +</ul></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.implementation.number_of_arguments"></a><a class="link" href="bind.html#bind.implementation.number_of_arguments" title="Number of Arguments">Number of Arguments</a> +</h3></div></div></div> +<p> + This implementation supports function objects with up to nine arguments. + This is an implementation detail, not an inherent limitation of the design. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.implementation.stdcall"></a><a class="link" href="bind.html#bind.implementation.stdcall" title="__stdcall, __cdecl, __fastcall, and pascal Support"><code class="computeroutput"><span class="identifier">__stdcall</span></code>, + <code class="computeroutput"><span class="identifier">__cdecl</span></code>, <code class="computeroutput"><span class="identifier">__fastcall</span></code>, + and <code class="computeroutput"><span class="identifier">pascal</span></code> Support</a> +</h3></div></div></div> +<p> + Some platforms allow several types of (member) functions that differ by their + calling convention (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 <code class="computeroutput"><span class="identifier">__stdcall</span></code>. + Borland VCL components use <code class="computeroutput"><span class="identifier">__fastcall</span></code>. + Mac toolbox functions use a <code class="computeroutput"><span class="identifier">pascal</span></code> + calling convention. + </p> +<p> + To use <code class="computeroutput"><span class="identifier">bind</span></code> with <code class="computeroutput"><span class="identifier">__stdcall</span></code> functions, <code class="computeroutput"><span class="preprocessor">#define</span></code> + the macro <code class="computeroutput"><span class="identifier">BOOST_BIND_ENABLE_STDCALL</span></code> + before including <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>. + </p> +<p> + To use <code class="computeroutput"><span class="identifier">bind</span></code> with <code class="computeroutput"><span class="identifier">__stdcall</span></code> member functions, <code class="computeroutput"><span class="preprocessor">#define</span></code> the macro <code class="computeroutput"><span class="identifier">BOOST_MEM_FN_ENABLE_STDCALL</span></code> + before including <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>. + </p> +<p> + To use <code class="computeroutput"><span class="identifier">bind</span></code> with <code class="computeroutput"><span class="identifier">__fastcall</span></code> functions, <code class="computeroutput"><span class="preprocessor">#define</span></code> + the macro <code class="computeroutput"><span class="identifier">BOOST_BIND_ENABLE_FASTCALL</span></code> + before including <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>. + </p> +<p> + To use <code class="computeroutput"><span class="identifier">bind</span></code> with <code class="computeroutput"><span class="identifier">__fastcall</span></code> member functions, <code class="computeroutput"><span class="preprocessor">#define</span></code> the macro <code class="computeroutput"><span class="identifier">BOOST_MEM_FN_ENABLE_FASTCALL</span></code> + before including <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>. + </p> +<p> + To use <code class="computeroutput"><span class="identifier">bind</span></code> with <code class="computeroutput"><span class="identifier">pascal</span></code> functions, <code class="computeroutput"><span class="preprocessor">#define</span></code> + the macro <code class="computeroutput"><span class="identifier">BOOST_BIND_ENABLE_PASCAL</span></code> + before including <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>. + </p> +<p> + To use <code class="computeroutput"><span class="identifier">bind</span></code> with <code class="computeroutput"><span class="identifier">__cdecl</span></code> member functions, <code class="computeroutput"><span class="preprocessor">#define</span></code> the macro <code class="computeroutput"><span class="identifier">BOOST_MEM_FN_ENABLE_CDECL</span></code> + before including <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>. + </p> +<p> + <span class="bold"><strong>It is best to define these macros in the project options, + via <code class="computeroutput"><span class="special">-</span><span class="identifier">D</span></code> + on the command line, or as the first line in the translation unit (.cpp file) + where <code class="computeroutput"><span class="identifier">bind</span></code> is used.</strong></span> + Not following this rule can lead to obscure errors when a header includes + <code class="computeroutput"><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span></code> before the macro has been defined. + </p> +<p> + <span class="emphasis"><em>[Note:</em></span> this is a non-portable extension. It is not part + of the interface.<span class="emphasis"><em>]</em></span> + </p> +<p> + <span class="emphasis"><em>[Note:</em></span> Some compilers provide only minimal support for + the <code class="computeroutput"><span class="identifier">__stdcall</span></code> keyword.<span class="emphasis"><em>]</em></span> + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bind.implementation.visit_each_support"></a><a class="link" href="bind.html#bind.implementation.visit_each_support" title="visit_each support"><code class="computeroutput"><span class="identifier">visit_each</span></code> support</a> +</h3></div></div></div> +<p> + Function objects returned by <code class="computeroutput"><span class="identifier">bind</span></code> + support the experimental and undocumented, as of yet, <code class="computeroutput"><span class="identifier">visit_each</span></code> + enumeration interface. + </p> +<p> + See <a href="../../bind_visitor.cpp" target="_top">bind_visitor.cpp</a> for an example. + </p> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="bind.acknowledgements"></a><a class="link" href="bind.html#bind.acknowledgements" title="Acknowledgements">Acknowledgements</a> +</h2></div></div></div> +<p> + Earlier efforts that have influenced the library design: + </p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + The <a href="http://staff.cs.utu.fi/BL/" target="_top">Binder Library</a> by Jaakko + Järvi; + </li> +<li class="listitem"> + The <a href="../../../../libs/lambda/index.html" target="_top">Lambda Library</a> (now + part of Boost) by Jaakko Järvi and Gary Powell (the successor to the + Binder Library); + </li> +<li class="listitem"> + <a href="http://more.sourceforge.net/" target="_top">Extensions to the STL</a> + by Petter Urkedal. + </li> +</ul></div> +<p> + Doug Gregor suggested that a visitor mechanism would allow <code class="computeroutput"><span class="identifier">bind</span></code> + to interoperate with a signal/slot library. + </p> +<p> + John Maddock fixed a MSVC-specific conflict between <code class="computeroutput"><span class="identifier">bind</span></code> + and the <a href="../../../../libs/type_traits/index.html" target="_top">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 + Darin Adler. + </p> +<p> + The precise semantics of <code class="computeroutput"><span class="identifier">bind</span></code> + were refined in discussions with Jaakko Järvi. + </p> +<p> + Dave Abrahams fixed a MSVC-specific conflict between <code class="computeroutput"><span class="identifier">bind</span></code> + and the <a href="../../../../libs/utility/iterator_adaptors.htm" target="_top">iterator adaptors + library</a>. + </p> +<p> + Dave Abrahams modified <code class="computeroutput"><span class="identifier">bind</span></code> + and <code class="computeroutput"><span class="identifier">mem_fn</span></code> to support <code class="computeroutput"><span class="keyword">void</span></code> returns on deficient compilers. + </p> +<p> + Mac Murrett contributed the "pascal" support enabled by <code class="computeroutput"><span class="identifier">BOOST_BIND_ENABLE_PASCAL</span></code>. + </p> +<p> + The alternative <code class="computeroutput"><span class="identifier">bind</span><span class="special">(</span><span class="identifier">type</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(),</span> <span class="identifier">f</span><span class="special">,</span> <span class="special">...)</span></code> + syntax was inspired by a discussion with Dave Abrahams and Joel de Guzman. + </p> +<p> + This documentation was ported to Quickbook by Agustín Bergé. + </p> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"><p><small>Last revised: April 07, 2015 at 22:47:13 GMT</small></p></td> +<td align="right"><div class="copyright-footer"></div></td> +</tr></table> +<hr> +<div class="spirit-nav"></div> +</body> +</html> diff --git a/libs/bind/doc/html/mem_fn.html b/libs/bind/doc/html/mem_fn.html new file mode 100644 index 000000000..0f61e7a14 --- /dev/null +++ b/libs/bind/doc/html/mem_fn.html @@ -0,0 +1,552 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Chapter 1. Boost.Member Function</title> +<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="mem_fn.html" title="Chapter 1. Boost.Member Function"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr> +<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td> +<td align="center"><a href="../../../../index.html">Home</a></td> +<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> +<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> +<td align="center"><a href="../../../../more/index.htm">More</a></td> +</tr></table> +<hr> +<div class="spirit-nav"></div> +<div class="chapter"> +<div class="titlepage"><div> +<div><h2 class="title"> +<a name="mem_fn"></a>Chapter 1. Boost.Member Function</h2></div> +<div><p class="copyright">Copyright © 2001, 2002 Peter Dimov and Multi Media Ltd.</p></div> +<div><p class="copyright">Copyright © 2003-2005 Peter Dimov</p></div> +<div><div class="legalnotice"> +<a name="mem_fn.legal"></a><p> + Distributed under the <a href="http://boost.org/LICENSE_1_0.txt" target="_top">Boost + Software License, Version 1.0</a>. + </p> +</div></div> +</div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="mem_fn.html#mem_fn.purpose">Purpose</a></span></dt> +<dt><span class="section"><a href="mem_fn.html#mem_fn.faq">Frequently Asked Questions</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="mem_fn.html#mem_fn.faq.can_mem_fn_be_used_instead_of_th">Can <code class="computeroutput"><span class="identifier">mem_fn</span></code> be used instead of the standard <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">mem_fun</span><span class="special">[</span><span class="identifier">_ref</span><span class="special">]</span></code> + adaptors?</a></span></dt> +<dt><span class="section"><a href="mem_fn.html#mem_fn.faq.should_i_replace_every_occurence">Should I + replace every occurence of <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">mem_fun</span><span class="special">[</span><span class="identifier">_ref</span><span class="special">]</span></code> + with <code class="computeroutput"><span class="identifier">mem_fn</span></code> in my existing + code?</a></span></dt> +<dt><span class="section"><a href="mem_fn.html#mem_fn.faq.does_mem_fn_work_with_com_method">Does <code class="computeroutput"><span class="identifier">mem_fn</span></code> work with COM methods?</a></span></dt> +<dt><span class="section"><a href="mem_fn.html#mem_fn.faq.why_isn_t_boost_mem_fn_enable_st">Why isn't + <code class="computeroutput"><span class="identifier">BOOST_MEM_FN_ENABLE_STDCALL</span></code> + defined automatically?</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="mem_fn.html#mem_fn.interface">Interface</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="mem_fn.html#mem_fn.interface.synopsys">Synopsis</a></span></dt> +<dt><span class="section"><a href="mem_fn.html#mem_fn.interface.common_requirements">Common requirements</a></span></dt> +<dt><span class="section"><a href="mem_fn.html#mem_fn.interface.get_pointer"><code class="computeroutput"><span class="identifier">get_pointer</span></code></a></span></dt> +<dt><span class="section"><a href="mem_fn.html#mem_fn.interface.mem_fn"><code class="computeroutput"><span class="identifier">mem_fn</span></code></a></span></dt> +</dl></dd> +<dt><span class="section"><a href="mem_fn.html#mem_fn.implementation">Implementation</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="mem_fn.html#mem_fn.implementation.files">Files</a></span></dt> +<dt><span class="section"><a href="mem_fn.html#mem_fn.implementation.dependencies">Dependencies</a></span></dt> +<dt><span class="section"><a href="mem_fn.html#mem_fn.implementation.number_of_arguments">Number of + Arguments</a></span></dt> +<dt><span class="section"><a href="mem_fn.html#mem_fn.implementation.stdcall"><code class="computeroutput"><span class="identifier">__stdcall</span></code>, + <code class="computeroutput"><span class="identifier">__cdecl</span></code>, and <code class="computeroutput"><span class="identifier">__fastcall</span></code> Support</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="mem_fn.html#mem_fn.acknowledgements">Acknowledgements</a></span></dt> +</dl> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="mem_fn.purpose"></a><a class="link" href="mem_fn.html#mem_fn.purpose" title="Purpose">Purpose</a> +</h2></div></div></div> +<p> + <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span></code> is a generalization of the standard + functions <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">mem_fun</span></code> and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">mem_fun_ref</span></code>. + It supports member function pointers with more than one argument, and the returned + function object can take a pointer, a reference, or a smart pointer to an object + instance as its first argument. <code class="computeroutput"><span class="identifier">mem_fn</span></code> + also supports pointers to data members by treating them as functions taking + no arguments and returning a (const) reference to the member. + </p> +<p> + The purpose of <code class="computeroutput"><span class="identifier">mem_fn</span></code> is twofold. + First, it allows users to invoke a member function on a container with the + familiar + </p> +<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">v</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span><span class="special">(&</span><span class="identifier">Shape</span><span class="special">::</span><span class="identifier">draw</span><span class="special">));</span> +</pre> +<p> + syntax, even when the container stores smart pointers. + </p> +<p> + Second, it can be used as a building block by library developers that want + to treat a pointer to member function as a function object. A library might + define an enhanced <code class="computeroutput"><span class="identifier">for_each</span></code> + algorithm with an overload of the form: + </p> +<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">It</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">void</span> <span class="identifier">for_each</span><span class="special">(</span><span class="identifier">It</span> <span class="identifier">first</span><span class="special">,</span> <span class="identifier">It</span> <span class="identifier">last</span><span class="special">,</span> <span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">())</span> +<span class="special">{</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span><span class="special">(</span><span class="identifier">pmf</span><span class="special">));</span> +<span class="special">}</span> +</pre> +<p> + that will allow the convenient syntax: + </p> +<pre class="programlisting"><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">v</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="special">&</span><span class="identifier">Shape</span><span class="special">::</span><span class="identifier">draw</span><span class="special">);</span> +</pre> +<p> + When documenting the feature, the library author will simply state: + </p> +<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">It</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">void</span> <span class="identifier">for_each</span><span class="special">(</span><span class="identifier">It</span> <span class="identifier">first</span><span class="special">,</span> <span class="identifier">It</span> <span class="identifier">last</span><span class="special">,</span> <span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">());</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <span class="emphasis"><em>Effects:</em></span> Equivalent to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span><span class="special">(</span><span class="identifier">pmf</span><span class="special">))</span></code>. + </li></ul></div> +<p> + where <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span></code> can be a link to this page. See the + <a href="../../../../libs/bind/bind.html" target="_top">documentation of <code class="computeroutput"><span class="identifier">bind</span></code></a> + for an example. + </p> +<p> + <code class="computeroutput"><span class="identifier">mem_fn</span></code> takes one argument, + a pointer to a member, and returns a function object suitable for use with + standard or user-defined algorithms: + </p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">X</span> +<span class="special">{</span> + <span class="keyword">void</span> <span class="identifier">f</span><span class="special">();</span> +<span class="special">};</span> + +<span class="keyword">void</span> <span class="identifier">g</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="identifier">X</span><span class="special">></span> <span class="special">&</span> <span class="identifier">v</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">v</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">));</span> +<span class="special">};</span> + +<span class="keyword">void</span> <span class="identifier">h</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="identifier">X</span> <span class="special">*></span> <span class="keyword">const</span> <span class="special">&</span> <span class="identifier">v</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">v</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">));</span> +<span class="special">};</span> + +<span class="keyword">void</span> <span class="identifier">k</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special"><</span><span class="identifier">X</span><span class="special">></span> <span class="special">></span> <span class="keyword">const</span> <span class="special">&</span> <span class="identifier">v</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">v</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mem_fn</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">));</span> +<span class="special">};</span> +</pre> +<p> + The returned function object takes the same arguments as the input member function + plus a "flexible" first argument that represents the object instance. + </p> +<p> + When the function object is invoked with a first argument <code class="computeroutput"><span class="identifier">x</span></code> + that is neither a pointer nor a reference to the appropriate class (<code class="computeroutput"><span class="identifier">X</span></code> in the example above), it uses <code class="computeroutput"><span class="identifier">get_pointer</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span></code> to obtain + a pointer from <code class="computeroutput"><span class="identifier">x</span></code>. Library authors + can "register" their smart pointer classes by supplying an appropriate + <code class="computeroutput"><span class="identifier">get_pointer</span></code> overload, allowing + <code class="computeroutput"><span class="identifier">mem_fn</span></code> to recognize and support + them. + </p> +<p> + <span class="emphasis"><em>[Note:</em></span> <code class="computeroutput"><span class="identifier">get_pointer</span></code> + is not restricted to return a pointer. Any object that can be used in a member + function call expression <code class="computeroutput"><span class="special">(</span><span class="identifier">x</span><span class="special">->*</span><span class="identifier">pmf</span><span class="special">)(...)</span></code> will work.<span class="emphasis"><em>]</em></span> + </p> +<p> + <span class="emphasis"><em>[Note:</em></span> the library uses an unqualified call to <code class="computeroutput"><span class="identifier">get_pointer</span></code>. Therefore, it will find, through + argument-dependent lookup, <code class="computeroutput"><span class="identifier">get_pointer</span></code> + overloads that are defined in the same namespace as the corresponding smart + pointer class, in addition to any <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">get_pointer</span></code> + overloads.<span class="emphasis"><em>]</em></span> + </p> +<p> + All function objects returned by <code class="computeroutput"><span class="identifier">mem_fn</span></code> + expose a <code class="computeroutput"><span class="identifier">result_type</span></code> typedef + that represents the return type of the member function. For data members, + <code class="computeroutput"><span class="identifier">result_type</span></code> is defined as the + type of the member. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="mem_fn.faq"></a><a class="link" href="mem_fn.html#mem_fn.faq" title="Frequently Asked Questions">Frequently Asked Questions</a> +</h2></div></div></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mem_fn.faq.can_mem_fn_be_used_instead_of_th"></a><a class="link" href="mem_fn.html#mem_fn.faq.can_mem_fn_be_used_instead_of_th" title="Can mem_fn be used instead of the standard std::mem_fun[_ref] adaptors?">Can <code class="computeroutput"><span class="identifier">mem_fn</span></code> be used instead of the standard <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">mem_fun</span><span class="special">[</span><span class="identifier">_ref</span><span class="special">]</span></code> + adaptors?</a> +</h3></div></div></div> +<p> + Yes. For simple uses, <code class="computeroutput"><span class="identifier">mem_fn</span></code> + provides additional functionality that the standard adaptors do not. Complicated + expressions that use <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bind1st</span></code>, + <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bind2nd</span></code> or <a href="http://www.boost.org/doc/libs/1_31_0/libs/compose/index.htm" target="_top">Boost.Compose</a> + along with the standard adaptors can be rewritten using <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span></code> + that automatically takes advantage of <code class="computeroutput"><span class="identifier">mem_fn</span></code>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mem_fn.faq.should_i_replace_every_occurence"></a><a class="link" href="mem_fn.html#mem_fn.faq.should_i_replace_every_occurence" title="Should I replace every occurence of std::mem_fun[_ref] with mem_fn in my existing code?">Should I + replace every occurence of <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">mem_fun</span><span class="special">[</span><span class="identifier">_ref</span><span class="special">]</span></code> + with <code class="computeroutput"><span class="identifier">mem_fn</span></code> in my existing + code?</a> +</h3></div></div></div> +<p> + No, unless you have good reasons to do so. <code class="computeroutput"><span class="identifier">mem_fn</span></code> + is not 100% compatible with the standard adaptors, although it comes pretty + close. In particular, <code class="computeroutput"><span class="identifier">mem_fn</span></code> + does not return objects of type <code class="computeroutput"><span class="identifier">std</span><span class="special">::[</span><span class="identifier">const_</span><span class="special">]</span><span class="identifier">mem_fun</span><span class="special">[</span><span class="number">1</span><span class="special">][</span><span class="identifier">_ref</span><span class="special">]</span><span class="identifier">_t</span></code>, + as the standard adaptors do, and it is not possible to fully describe the + type of the first argument using the standard <code class="computeroutput"><span class="identifier">argument_type</span></code> + and <code class="computeroutput"><span class="identifier">first_argument_type</span></code> nested + typedefs. Libraries that need adaptable function objects in order to function + might not like <code class="computeroutput"><span class="identifier">mem_fn</span></code>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mem_fn.faq.does_mem_fn_work_with_com_method"></a><a class="link" href="mem_fn.html#mem_fn.faq.does_mem_fn_work_with_com_method" title="Does mem_fn work with COM methods?">Does <code class="computeroutput"><span class="identifier">mem_fn</span></code> work with COM methods?</a> +</h3></div></div></div> +<p> + Yes, if you <a class="link" href="mem_fn.html#mem_fn.implementation.stdcall" title="__stdcall, __cdecl, and __fastcall Support">`#define BOOST_MEM_FN_ENABLE_STDCALL</a>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mem_fn.faq.why_isn_t_boost_mem_fn_enable_st"></a><a class="link" href="mem_fn.html#mem_fn.faq.why_isn_t_boost_mem_fn_enable_st" title="Why isn't BOOST_MEM_FN_ENABLE_STDCALL defined automatically?">Why isn't + <code class="computeroutput"><span class="identifier">BOOST_MEM_FN_ENABLE_STDCALL</span></code> + defined automatically?</a> +</h3></div></div></div> +<p> + Non-portable extensions, in general, should default to off to prevent vendor + lock-in. Had <code class="computeroutput"><span class="identifier">BOOST_MEM_FN_ENABLE_STDCALL</span></code> + been defined automatically, you could have accidentally taken advantage of + it without realizing that your code is, perhaps, no longer portable. In addition, + it is possible for the default calling convention to be <code class="computeroutput"><span class="identifier">__stdcall</span></code>, + in which case enabling <code class="computeroutput"><span class="identifier">__stdcall</span></code> + support will result in duplicate definitions. + </p> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="mem_fn.interface"></a><a class="link" href="mem_fn.html#mem_fn.interface" title="Interface">Interface</a> +</h2></div></div></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mem_fn.interface.synopsys"></a><a class="link" href="mem_fn.html#mem_fn.interface.synopsys" title="Synopsis">Synopsis</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> +<span class="special">{</span> + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="identifier">T</span> <span class="special">*</span> <a class="link" href="mem_fn.html#get_pointer_1"><code class="computeroutput"><span class="identifier">get_pointer</span></code></a><span class="special">(</span><span class="identifier">T</span> <span class="special">*</span> <span class="identifier">p</span><span class="special">);</span> + + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="emphasis"><em>unspecified-1</em></span> <a class="link" href="mem_fn.html#mem_fn_1"><code class="computeroutput"><span class="identifier">mem_fn</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">());</span> + + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="emphasis"><em>unspecified-2</em></span> <a class="link" href="mem_fn.html#mem_fn_2"><code class="computeroutput"><span class="identifier">mem_fn</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">()</span> <span class="keyword">const</span><span class="special">);</span> + + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="emphasis"><em>unspecified-2-1</em></span> <a class="link" href="mem_fn.html#mem_fn_2_1"><code class="computeroutput"><span class="identifier">mem_fn</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="identifier">T</span><span class="special">::*</span><span class="identifier">pm</span><span class="special">);</span> + + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-3</em></span> <a class="link" href="mem_fn.html#mem_fn_3"><code class="computeroutput"><span class="identifier">mem_fn</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">(</span><span class="identifier">A1</span><span class="special">));</span> + + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-4</em></span> <a class="link" href="mem_fn.html#mem_fn_4"><code class="computeroutput"><span class="identifier">mem_fn</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">(</span><span class="identifier">A1</span><span class="special">)</span> <span class="keyword">const</span><span class="special">);</span> + + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-5</em></span> <a class="link" href="mem_fn.html#mem_fn_5"><code class="computeroutput"><span class="identifier">mem_fn</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">(</span><span class="identifier">A1</span><span class="special">,</span> <span class="identifier">A2</span><span class="special">));</span> + + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-6</em></span> <a class="link" href="mem_fn.html#mem_fn_6"><code class="computeroutput"><span class="identifier">mem_fn</span></code></a><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">(</span><span class="identifier">A1</span><span class="special">,</span> <span class="identifier">A2</span><span class="special">)</span> <span class="keyword">const</span><span class="special">);</span> + + <span class="comment">// implementation defined number of additional overloads for more arguments</span> +<span class="special">}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mem_fn.interface.common_requirements"></a><a class="link" href="mem_fn.html#mem_fn.interface.common_requirements" title="Common requirements">Common requirements</a> +</h3></div></div></div> +<p> + All <span class="emphasis"><em>unspecified-N</em></span> types mentioned in the Synopsis are + <span class="emphasis"><em>CopyConstructible</em></span> and <span class="emphasis"><em>Assignable</em></span>. + Their copy constructors and assignment operators do not throw exceptions. + <span class="emphasis"><em>unspecified-N</em></span><code class="computeroutput"><span class="special">::</span><span class="identifier">result_type</span></code> is defined as the return type + of the member function pointer passed as an argument to <code class="computeroutput"><span class="identifier">mem_fn</span></code> + (<code class="computeroutput"><span class="identifier">R</span></code> in the Synopsis.) <span class="emphasis"><em>unspecified-2-1</em></span><code class="computeroutput"><span class="special">::</span><span class="identifier">result_type</span></code> + is defined as <code class="computeroutput"><span class="identifier">R</span></code>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mem_fn.interface.get_pointer"></a><a class="link" href="mem_fn.html#mem_fn.interface.get_pointer" title="get_pointer"><code class="computeroutput"><span class="identifier">get_pointer</span></code></a> +</h3></div></div></div> +<a name="get_pointer_1"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="identifier">T</span> <span class="special">*</span> <span class="identifier">get_pointer</span><span class="special">(</span><span class="identifier">T</span> <span class="special">*</span> <span class="identifier">p</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> <code class="computeroutput"><span class="identifier">p</span></code>. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing. + </li> +</ul></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mem_fn.interface.mem_fn"></a><a class="link" href="mem_fn.html#mem_fn.interface.mem_fn" title="mem_fn"><code class="computeroutput"><span class="identifier">mem_fn</span></code></a> +</h3></div></div></div> +<a name="mem_fn_1"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="emphasis"><em>unspecified-1</em></span> <span class="identifier">mem_fn</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">())</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> a function object ϝ such that the + expression ϝ<code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">)</span></code> is equivalent to <code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">.*</span><span class="identifier">pmf</span><span class="special">)()</span></code> + when <code class="computeroutput"><span class="identifier">t</span></code> is an l-value + of type <code class="computeroutput"><span class="identifier">T</span></code> or derived, + <code class="computeroutput"><span class="special">(</span><span class="identifier">get_pointer</span><span class="special">(</span><span class="identifier">t</span><span class="special">)->*</span><span class="identifier">pmf</span><span class="special">)()</span></code> otherwise. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing. + </li> +</ul></div> +<a name="mem_fn_2"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="emphasis"><em>unspecified-2</em></span> <span class="identifier">mem_fn</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">()</span> <span class="keyword">const</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> a function object ϝ such that the + expression ϝ<code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">)</span></code> is equivalent to <code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">.*</span><span class="identifier">pmf</span><span class="special">)()</span></code> + when <code class="computeroutput"><span class="identifier">t</span></code> is of type <code class="computeroutput"><span class="identifier">T</span></code> <span class="emphasis"><em>[</em></span><code class="computeroutput"><span class="keyword">const</span></code><span class="emphasis"><em>]</em></span> or derived, + <code class="computeroutput"><span class="special">(</span><span class="identifier">get_pointer</span><span class="special">(</span><span class="identifier">t</span><span class="special">)->*</span><span class="identifier">pmf</span><span class="special">)()</span></code> otherwise. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing. + </li> +</ul></div> +<a name="mem_fn_2_1"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="emphasis"><em>unspecified-2-1</em></span> <span class="identifier">mem_fn</span><span class="special">(</span><span class="identifier">R</span> <span class="identifier">T</span><span class="special">::*</span><span class="identifier">pm</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> a function object ϝ such that the + expression ϝ<code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">)</span></code> is equivalent to <code class="computeroutput"><span class="identifier">t</span><span class="special">.*</span><span class="identifier">pm</span></code> + when <code class="computeroutput"><span class="identifier">t</span></code> is of type <code class="computeroutput"><span class="identifier">T</span></code> <span class="emphasis"><em>[</em></span><code class="computeroutput"><span class="keyword">const</span></code><span class="emphasis"><em>]</em></span> or derived, + <code class="computeroutput"><span class="identifier">get_pointer</span><span class="special">(</span><span class="identifier">t</span><span class="special">)->*</span><span class="identifier">pm</span></code> otherwise. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing. + </li> +</ul></div> +<a name="mem_fn_3"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-3</em></span> <span class="identifier">mem_fn</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">(</span><span class="identifier">A1</span><span class="special">))</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> a function object ϝ such that the + expression ϝ<code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">,</span> <span class="identifier">a1</span><span class="special">)</span></code> is equivalent to <code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">.*</span><span class="identifier">pmf</span><span class="special">)(</span><span class="identifier">a1</span><span class="special">)</span></code> + when <code class="computeroutput"><span class="identifier">t</span></code> is an l-value + of type <code class="computeroutput"><span class="identifier">T</span></code> or derived, + <code class="computeroutput"><span class="special">(</span><span class="identifier">get_pointer</span><span class="special">(</span><span class="identifier">t</span><span class="special">)->*</span><span class="identifier">pmf</span><span class="special">)(</span><span class="identifier">a1</span><span class="special">)</span></code> otherwise. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing. + </li> +</ul></div> +<a name="mem_fn_4"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> <span class="emphasis"><em>unspecified-4</em></span> <span class="identifier">mem_fn</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">(</span><span class="identifier">A1</span><span class="special">)</span> <span class="keyword">const</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> a function object ϝ such that the + expression ϝ<code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">,</span> <span class="identifier">a1</span><span class="special">)</span></code> is equivalent to <code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">.*</span><span class="identifier">pmf</span><span class="special">)(</span><span class="identifier">a1</span><span class="special">)</span></code> + when <code class="computeroutput"><span class="identifier">t</span></code> is of type <code class="computeroutput"><span class="identifier">T</span></code> <span class="emphasis"><em>[</em></span><code class="computeroutput"><span class="keyword">const</span></code><span class="emphasis"><em>]</em></span> or derived, + <code class="computeroutput"><span class="special">(</span><span class="identifier">get_pointer</span><span class="special">(</span><span class="identifier">t</span><span class="special">)->*</span><span class="identifier">pmf</span><span class="special">)(</span><span class="identifier">a1</span><span class="special">)</span></code> otherwise. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing. + </li> +</ul></div> +<a name="mem_fn_5"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-5</em></span> <span class="identifier">mem_fn</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">(</span><span class="identifier">A1</span><span class="special">,</span> <span class="identifier">A2</span><span class="special">))</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> a function object ϝ such that the + expression ϝ<code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">,</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">)</span></code> is equivalent to <code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">.*</span><span class="identifier">pmf</span><span class="special">)(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">)</span></code> + when <code class="computeroutput"><span class="identifier">t</span></code> is an l-value + of type <code class="computeroutput"><span class="identifier">T</span></code> or derived, + <code class="computeroutput"><span class="special">(</span><span class="identifier">get_pointer</span><span class="special">(</span><span class="identifier">t</span><span class="special">)->*</span><span class="identifier">pmf</span><span class="special">)(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">)</span></code> otherwise. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing. + </li> +</ul></div> +<a name="mem_fn_6"></a><pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> <span class="emphasis"><em>unspecified-6</em></span> <span class="identifier">mem_fn</span><span class="special">(</span><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*</span><span class="identifier">pmf</span><span class="special">)</span> <span class="special">(</span><span class="identifier">A1</span><span class="special">,</span> <span class="identifier">A2</span><span class="special">)</span> <span class="keyword">const</span><span class="special">)</span> +</pre> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <span class="emphasis"><em>Returns:</em></span> a function object ϝ such that the + expression ϝ<code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">,</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">)</span></code> is equivalent to <code class="computeroutput"><span class="special">(</span><span class="identifier">t</span><span class="special">.*</span><span class="identifier">pmf</span><span class="special">)(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">)</span></code> + when <code class="computeroutput"><span class="identifier">t</span></code> is of type <code class="computeroutput"><span class="identifier">T</span></code> <span class="emphasis"><em>[</em></span><code class="computeroutput"><span class="keyword">const</span></code><span class="emphasis"><em>]</em></span> or derived, + <code class="computeroutput"><span class="special">(</span><span class="identifier">get_pointer</span><span class="special">(</span><span class="identifier">t</span><span class="special">)->*</span><span class="identifier">pmf</span><span class="special">)(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">)</span></code> otherwise. + </li> +<li class="listitem"> + <span class="emphasis"><em>Throws:</em></span> Nothing. + </li> +</ul></div> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="mem_fn.implementation"></a><a class="link" href="mem_fn.html#mem_fn.implementation" title="Implementation">Implementation</a> +</h2></div></div></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mem_fn.implementation.files"></a><a class="link" href="mem_fn.html#mem_fn.implementation.files" title="Files">Files</a> +</h3></div></div></div> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <a href="../../include/boost/mem_fn.hpp" target="_top">boost/mem_fn.hpp</a> + (main header) + </li> +<li class="listitem"> + <a href="../../include/boost/bind/mem_fn_cc.hpp" target="_top">boost/bind/mem_fn_cc.hpp</a> + (used by <code class="computeroutput"><span class="identifier">mem_fn</span><span class="special">.</span><span class="identifier">hpp</span></code>, do not include directly) + </li> +<li class="listitem"> + <a href="../../include/boost/bind/mem_fn_vw.hpp" target="_top">boost/bind/mem_fn_vw.hpp</a> + (used by <code class="computeroutput"><span class="identifier">mem_fn</span><span class="special">.</span><span class="identifier">hpp</span></code>, do not include directly) + </li> +<li class="listitem"> + <a href="../../include/boost/bind/mem_fn_template.hpp" target="_top">boost/bind/mem_fn_template.hpp</a> + (used by <code class="computeroutput"><span class="identifier">mem_fn</span><span class="special">.</span><span class="identifier">hpp</span></code>, do not include directly) + </li> +<li class="listitem"> + <a href="../../test/mem_fn_test.cpp" target="_top">libs/bind/test/mem_fn_test.cpp</a> + (test) + </li> +<li class="listitem"> + <a href="../../test/mem_fn_derived_test.cpp" target="_top">libs/bind/test/mem_fn_derived_test.cpp</a> + (test with derived objects) + </li> +<li class="listitem"> + <a href="../../test/mem_fn_fastcall_test.cpp" target="_top">libs/bind/test/mem_fn_fastcall_test.cpp</a> + (test for <code class="computeroutput"><span class="identifier">__fastcall</span></code>) + </li> +<li class="listitem"> + <a href="../../test/mem_fn_stdcall_test.cpp" target="_top">libs/bind/test/mem_fn_stdcall_test.cpp</a> + (test for <code class="computeroutput"><span class="identifier">__stdcall</span></code>) + </li> +<li class="listitem"> + <a href="../../test/mem_fn_void_test.cpp" target="_top">libs/bind/test/mem_fn_void_test.cpp</a> + (test for <code class="computeroutput"><span class="keyword">void</span></code> returns) + </li> +</ul></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mem_fn.implementation.dependencies"></a><a class="link" href="mem_fn.html#mem_fn.implementation.dependencies" title="Dependencies">Dependencies</a> +</h3></div></div></div> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <a href="../../../../libs/config/config.htm" target="_top">Boost.Config</a> + </li></ul></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mem_fn.implementation.number_of_arguments"></a><a class="link" href="mem_fn.html#mem_fn.implementation.number_of_arguments" title="Number of Arguments">Number of + Arguments</a> +</h3></div></div></div> +<p> + This implementation supports member functions with up to eight arguments. + This is not an inherent limitation of the design, but an implementation detail. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mem_fn.implementation.stdcall"></a><a class="link" href="mem_fn.html#mem_fn.implementation.stdcall" title="__stdcall, __cdecl, and __fastcall Support"><code class="computeroutput"><span class="identifier">__stdcall</span></code>, + <code class="computeroutput"><span class="identifier">__cdecl</span></code>, and <code class="computeroutput"><span class="identifier">__fastcall</span></code> Support</a> +</h3></div></div></div> +<p> + Some platforms allow several types of member functions that differ by their + calling convention (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 <code class="computeroutput"><span class="identifier">__stdcall</span></code>. + Borland VCL components use <code class="computeroutput"><span class="identifier">__fastcall</span></code>. + UDK, the component model of OpenOffice.org, uses <code class="computeroutput"><span class="identifier">__cdecl</span></code>. + </p> +<p> + To use <code class="computeroutput"><span class="identifier">mem_fn</span></code> with <code class="computeroutput"><span class="identifier">__stdcall</span></code> member functions, <code class="computeroutput"><span class="preprocessor">#define</span></code> the macro <code class="computeroutput"><span class="identifier">BOOST_MEM_FN_ENABLE_STDCALL</span></code> + before including <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">mem_fn</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>. + </p> +<p> + To use <code class="computeroutput"><span class="identifier">mem_fn</span></code> with <code class="computeroutput"><span class="identifier">__fastcall</span></code> member functions, <code class="computeroutput"><span class="preprocessor">#define</span></code> the macro <code class="computeroutput"><span class="identifier">BOOST_MEM_FN_ENABLE_FASTCALL</span></code> + before including <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">mem_fn</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>. + </p> +<p> + To use <code class="computeroutput"><span class="identifier">mem_fn</span></code> with <code class="computeroutput"><span class="identifier">__cdecl</span></code> member functions, <code class="computeroutput"><span class="preprocessor">#define</span></code> the macro <code class="computeroutput"><span class="identifier">BOOST_MEM_FN_ENABLE_CDECL</span></code> + before including <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">mem_fn</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>. + </p> +<p> + <span class="bold"><strong>It is best to define these macros in the project options, + via <code class="computeroutput"><span class="special">-</span><span class="identifier">D</span></code> + on the command line, or as the first line in the translation unit (.cpp file) + where <code class="computeroutput"><span class="identifier">mem_fn</span></code> is used.</strong></span> + Not following this rule can lead to obscure errors when a header includes + <code class="computeroutput"><span class="identifier">mem_fn</span><span class="special">.</span><span class="identifier">hpp</span></code> before the macro has been defined. + </p> +<p> + <span class="emphasis"><em>[Note:</em></span> this is a non-portable extension. It is not part + of the interface.<span class="emphasis"><em>]</em></span> + </p> +<p> + <span class="emphasis"><em>[Note:</em></span> Some compilers provide only minimal support for + the <code class="computeroutput"><span class="identifier">__stdcall</span></code> keyword.<span class="emphasis"><em>]</em></span> + </p> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="mem_fn.acknowledgements"></a><a class="link" href="mem_fn.html#mem_fn.acknowledgements" title="Acknowledgements">Acknowledgements</a> +</h2></div></div></div> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + Rene Jager's initial suggestion of using traits classes to make <code class="computeroutput"><span class="identifier">mem_fn</span></code> adapt to user-defined smart pointers + inspired the <code class="computeroutput"><span class="identifier">get_pointer</span></code>-based + design. + </li> +<li class="listitem"> + Numerous improvements were suggested during the formal review period by + Richard Crossley, Jens Maurer, Ed Brey, and others. Review manager was + Darin Adler. + </li> +<li class="listitem"> + Steve Anichini pointed out that COM interfaces use <code class="computeroutput"><span class="identifier">__stdcall</span></code>. + </li> +<li class="listitem"> + Dave Abrahams modified <code class="computeroutput"><span class="identifier">bind</span></code> + and <code class="computeroutput"><span class="identifier">mem_fn</span></code> to support + <code class="computeroutput"><span class="keyword">void</span></code> returns on deficient + compilers. + </li> +<li class="listitem"> + Daniel Boelzle pointed out that UDK uses <code class="computeroutput"><span class="identifier">__cdecl</span></code>. + </li> +</ul></div> +<p> + This documentation was ported to Quickbook by Agustín Bergé. + </p> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"><p><small>Last revised: April 07, 2015 at 22:47:15 GMT</small></p></td> +<td align="right"><div class="copyright-footer"></div></td> +</tr></table> +<hr> +<div class="spirit-nav"></div> +</body> +</html> diff --git a/libs/bind/doc/html/standalone_bind_HTML.manifest b/libs/bind/doc/html/standalone_bind_HTML.manifest new file mode 100644 index 000000000..de245279a --- /dev/null +++ b/libs/bind/doc/html/standalone_bind_HTML.manifest @@ -0,0 +1 @@ +bind.html diff --git a/libs/bind/doc/html/standalone_mem_fn_HTML.manifest b/libs/bind/doc/html/standalone_mem_fn_HTML.manifest new file mode 100644 index 000000000..5e71f4675 --- /dev/null +++ b/libs/bind/doc/html/standalone_mem_fn_HTML.manifest @@ -0,0 +1 @@ +mem_fn.html diff --git a/libs/bind/doc/mem_fn.qbk b/libs/bind/doc/mem_fn.qbk new file mode 100644 index 000000000..9fe88d35d --- /dev/null +++ b/libs/bind/doc/mem_fn.qbk @@ -0,0 +1,32 @@ +[/ + / Copyright (c) 2001, 2002 Peter Dimov and Multi Media Ltd. + / Copyright (c) 2003-2005 Peter Dimov + / + / Distributed under 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) + /] + +[library Boost.Member Function + [quickbook 1.6] + [id mem_fn] + [copyright 2001, 2002 Peter Dimov and Multi Media Ltd.] + [copyright 2003-2005 Peter Dimov] + [dirname bind] + [license Distributed under the + [@http://boost.org/LICENSE_1_0.txt Boost Software License, + Version 1.0]. + ] +] + +[template simplesect[title] +[block '''<simplesect><title>'''[title]'''</title>''']] + +[template endsimplesect[] +[block '''</simplesect>''']] + +[include mem_fn/purpose.qbk] +[include mem_fn/faq.qbk] +[include mem_fn/interface.qbk] +[include mem_fn/implementation.qbk] +[include mem_fn/acknowledgements.qbk] diff --git a/libs/bind/doc/mem_fn/acknowledgements.qbk b/libs/bind/doc/mem_fn/acknowledgements.qbk new file mode 100644 index 000000000..46d2b82fa --- /dev/null +++ b/libs/bind/doc/mem_fn/acknowledgements.qbk @@ -0,0 +1,28 @@ +[/ + / Copyright (c) 2001, 2002 Peter Dimov and Multi Media Ltd. + / Copyright (c) 2003-2005 Peter Dimov + / + / Distributed under 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) + /] + +[section:acknowledgements Acknowledgements] + +* Rene Jager's initial suggestion of using traits classes to make `mem_fn` +adapt to user-defined smart pointers inspired the `get_pointer`-based design. + +* Numerous improvements were suggested during the formal review period by +Richard Crossley, Jens Maurer, Ed Brey, and others. Review manager was Darin +Adler. + +* Steve Anichini pointed out that COM interfaces use `__stdcall`. + +* Dave Abrahams modified `bind` and `mem_fn` to support `void` returns on +deficient compilers. + +* Daniel Boelzle pointed out that UDK uses `__cdecl`. + +This documentation was ported to Quickbook by AgustÃn Bergé. + +[endsect] diff --git a/libs/bind/doc/mem_fn/faq.qbk b/libs/bind/doc/mem_fn/faq.qbk new file mode 100644 index 000000000..169c8f14f --- /dev/null +++ b/libs/bind/doc/mem_fn/faq.qbk @@ -0,0 +1,53 @@ +[/ + / Copyright (c) 2001, 2002 Peter Dimov and Multi Media Ltd. + / Copyright (c) 2003-2005 Peter Dimov + / + / Distributed under 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) + /] + +[section:faq Frequently Asked Questions] + +[section Can `mem_fn` be used instead of the standard `std::mem_fun[_ref]` +adaptors?] + +Yes. For simple uses, `mem_fn` provides additional functionality that the +standard adaptors do not. Complicated expressions that use `std::bind1st`, +`std::bind2nd` or [@http://www.boost.org/doc/libs/1_31_0/libs/compose/index.htm Boost.Compose] +along with the standard adaptors can be rewritten using `boost::bind` that +automatically takes advantage of `mem_fn`. + +[endsect] + +[section Should I replace every occurence of `std::mem_fun[_ref]` with +`mem_fn` in my existing code?] + +No, unless you have good reasons to do so. `mem_fn` is not 100% compatible +with the standard adaptors, although it comes pretty close. In particular, +`mem_fn` does not return objects of type `std::[const_]mem_fun[1][_ref]_t`, as +the standard adaptors do, and it is not possible to fully describe the type of +the first argument using the standard `argument_type` and `first_argument_type` +nested typedefs. Libraries that need adaptable function objects in order to +function might not like `mem_fn`. + +[endsect] + +[section Does `mem_fn` work with COM methods?] + +Yes, if you [link mem_fn.implementation.stdcall `#define BOOST_MEM_FN_ENABLE_STDCALL]. + +[endsect] + +[section Why isn't `BOOST_MEM_FN_ENABLE_STDCALL` defined automatically?] + +Non-portable extensions, in general, should default to off to prevent vendor +lock-in. Had `BOOST_MEM_FN_ENABLE_STDCALL` been defined automatically, you +could have accidentally taken advantage of it without realizing that your code +is, perhaps, no longer portable. In addition, it is possible for the default +calling convention to be `__stdcall`, in which case enabling `__stdcall` +support will result in duplicate definitions. + +[endsect] + +[endsect] diff --git a/libs/bind/doc/mem_fn/implementation.qbk b/libs/bind/doc/mem_fn/implementation.qbk new file mode 100644 index 000000000..f7314ad48 --- /dev/null +++ b/libs/bind/doc/mem_fn/implementation.qbk @@ -0,0 +1,70 @@ +[/ + / Copyright (c) 2001, 2002 Peter Dimov and Multi Media Ltd. + / Copyright (c) 2003-2005 Peter Dimov + / + / Distributed under 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) + /] + +[section:implementation Implementation] + +[section Files] + +* [@../../include/boost/mem_fn.hpp boost/mem_fn.hpp] (main header) +* [@../../include/boost/bind/mem_fn_cc.hpp boost/bind/mem_fn_cc.hpp] (used by `mem_fn.hpp`, do not include directly) +* [@../../include/boost/bind/mem_fn_vw.hpp boost/bind/mem_fn_vw.hpp] (used by `mem_fn.hpp`, do not include directly) +* [@../../include/boost/bind/mem_fn_template.hpp boost/bind/mem_fn_template.hpp] (used by `mem_fn.hpp`, do not include directly) +* [@../../test/mem_fn_test.cpp libs/bind/test/mem_fn_test.cpp] (test) +* [@../../test/mem_fn_derived_test.cpp libs/bind/test/mem_fn_derived_test.cpp] (test with derived objects) +* [@../../test/mem_fn_fastcall_test.cpp libs/bind/test/mem_fn_fastcall_test.cpp] (test for `__fastcall`) +* [@../../test/mem_fn_stdcall_test.cpp libs/bind/test/mem_fn_stdcall_test.cpp] (test for `__stdcall`) +* [@../../test/mem_fn_void_test.cpp libs/bind/test/mem_fn_void_test.cpp] (test for `void` returns) + +[endsect] + +[section Dependencies] + +* [@boost:/libs/config/config.htm Boost.Config] + +[endsect] + +[section Number of Arguments] + +This implementation supports member functions with up to eight arguments. This +is not an inherent limitation of the design, but an implementation detail. + +[endsect] + +[section:stdcall `__stdcall`, `__cdecl`, and `__fastcall` Support] + +Some platforms allow several types of member functions that differ by their +calling convention (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.) + +For example, Windows API functions and COM interface member functions use a +calling convention known as `__stdcall`. Borland VCL components use +`__fastcall`. UDK, the component model of OpenOffice.org, uses `__cdecl`. + +To use `mem_fn` with `__stdcall` member functions, `#define` the macro +`BOOST_MEM_FN_ENABLE_STDCALL` before including `<boost/mem_fn.hpp>`. + +To use `mem_fn` with `__fastcall` member functions, `#define` the macro +`BOOST_MEM_FN_ENABLE_FASTCALL` before including `<boost/mem_fn.hpp>`. + +To use `mem_fn` with `__cdecl` member functions, `#define` the macro +`BOOST_MEM_FN_ENABLE_CDECL` before including `<boost/mem_fn.hpp>`. + +[*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 +`mem_fn` is used.] Not following this rule can lead to obscure errors when a +header includes `mem_fn.hpp` before the macro has been defined. + +/[Note:/ this is a non-portable extension. It is not part of the interface./]/ + +/[Note:/ Some compilers provide only minimal support for the `__stdcall` keyword./]/ + +[endsect] + +[endsect] diff --git a/libs/bind/doc/mem_fn/interface.qbk b/libs/bind/doc/mem_fn/interface.qbk new file mode 100644 index 000000000..c0528a535 --- /dev/null +++ b/libs/bind/doc/mem_fn/interface.qbk @@ -0,0 +1,133 @@ +[/ + / Copyright (c) 2001, 2002 Peter Dimov and Multi Media Ltd. + / Copyright (c) 2003-2005 Peter Dimov + / + / Distributed under 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) + /] + +[section:interface Interface] + +[section:synopsys Synopsis] + + namespace boost + { + template<class T> T * ``[link get_pointer_1 `get_pointer`]``(T * p); + + template<class R, class T> ``/unspecified-1/`` ``[link mem_fn_1 `mem_fn`]``(R (T::*pmf) ()); + + template<class R, class T> ``/unspecified-2/`` ``[link mem_fn_2 `mem_fn`]``(R (T::*pmf) () const); + + template<class R, class T> ``/unspecified-2-1/`` ``[link mem_fn_2_1 `mem_fn`]``(R T::*pm); + + template<class R, class T, class A1> ``/unspecified-3/`` ``[link mem_fn_3 `mem_fn`]``(R (T::*pmf) (A1)); + + template<class R, class T, class A1> ``/unspecified-4/`` ``[link mem_fn_4 `mem_fn`]``(R (T::*pmf) (A1) const); + + template<class R, class T, class A1, class A2> ``/unspecified-5/`` ``[link mem_fn_5 `mem_fn`]``(R (T::*pmf) (A1, A2)); + + template<class R, class T, class A1, class A2> ``/unspecified-6/`` ``[link mem_fn_6 `mem_fn`]``(R (T::*pmf) (A1, A2) const); + + // implementation defined number of additional overloads for more arguments + } + +[endsect] + +[section Common requirements] + +All /unspecified-N/ types mentioned in the Synopsis are /CopyConstructible/ +and /Assignable/. Their copy constructors and assignment operators do not +throw exceptions. /unspecified-N/`::result_type` is defined as the return type +of the member function pointer passed as an argument to `mem_fn` (`R` in the +Synopsis.) /unspecified-2-1/`::result_type` is defined as `R`. + +[endsect] + +[section `get_pointer`] + +[#get_pointer_1] + + template<class T> T * get_pointer(T * p) + +* /Returns:/ `p`. + +* /Throws:/ Nothing. + +[endsect] + +[section `mem_fn`] + +[#mem_fn_1] + + template<class R, class T> ``/unspecified-1/`` mem_fn(R (T::*pmf) ()) + +* /Returns:/ a function object \u03DD such that the expression \u03DD`(t)` is +equivalent to `(t.*pmf)()` when `t` is an l-value of type `T` or derived, +`(get_pointer(t)->*pmf)()` otherwise. + +* /Throws:/ Nothing. + +[#mem_fn_2] + + template<class R, class T> ``/unspecified-2/`` mem_fn(R (T::*pmf) () const) + +* /Returns:/ a function object \u03DD such that the expression \u03DD`(t)` is +equivalent to `(t.*pmf)()` when `t` is of type `T` /[/`const`/]/ or derived, +`(get_pointer(t)->*pmf)()` otherwise. + +* /Throws:/ Nothing. + +[#mem_fn_2_1] + + template<class R, class T> ``/unspecified-2-1/`` mem_fn(R T::*pm) + +* /Returns:/ a function object \u03DD such that the expression \u03DD`(t)` is +equivalent to `t.*pm` when `t` is of type `T` /[/`const`/]/ or derived, +`get_pointer(t)->*pm` otherwise. + +* /Throws:/ Nothing. + +[#mem_fn_3] + + template<class R, class T, class A1> ``/unspecified-3/`` mem_fn(R (T::*pmf) (A1)) + +* /Returns:/ a function object \u03DD such that the expression \u03DD`(t, a1)` +is equivalent to `(t.*pmf)(a1)` when `t` is an l-value of type `T` or derived, +`(get_pointer(t)->*pmf)(a1)` otherwise. + +* /Throws:/ Nothing. + +[#mem_fn_4] + + template<class R, class T, class A1> ``/unspecified-4/`` mem_fn(R (T::*pmf) (A1) const) + +* /Returns:/ a function object \u03DD such that the expression \u03DD`(t, a1)` +is equivalent to `(t.*pmf)(a1)` when `t` is of type `T` /[/`const`/]/ or derived, +`(get_pointer(t)->*pmf)(a1)` otherwise. + +* /Throws:/ Nothing. + +[#mem_fn_5] + + template<class R, class T, class A1, class A2> ``/unspecified-5/`` mem_fn(R (T::*pmf) (A1, A2)) + +* /Returns:/ a function object \u03DD such that the expression \u03DD`(t, a1, a2)` +is equivalent to `(t.*pmf)(a1, a2)` when `t` is an l-value of type `T` or derived, +`(get_pointer(t)->*pmf)(a1, a2)` otherwise. + +* /Throws:/ Nothing. + +[#mem_fn_6] + + template<class R, class T, class A1, class A2> ``/unspecified-6/`` mem_fn(R (T::*pmf) (A1, A2) const) + +* /Returns:/ a function object \u03DD such that the expression \u03DD`(t, a1, a2)` +is equivalent to `(t.*pmf)(a1, a2)` when `t` is of type `T` /[/`const`/]/ or derived, +`(get_pointer(t)->*pmf)(a1, a2)` otherwise. + +* /Throws:/ Nothing. + +[endsect] + +[endsect] diff --git a/libs/bind/doc/mem_fn/purpose.qbk b/libs/bind/doc/mem_fn/purpose.qbk new file mode 100644 index 000000000..5fc649919 --- /dev/null +++ b/libs/bind/doc/mem_fn/purpose.qbk @@ -0,0 +1,93 @@ +[/ + / Copyright (c) 2001, 2002 Peter Dimov and Multi Media Ltd. + / Copyright (c) 2003-2005 Peter Dimov + / + / Distributed under 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) + /] + +[section:purpose Purpose] + +`boost::mem_fn` is a generalization of the standard functions `std::mem_fun` +and `std::mem_fun_ref`. It supports member function pointers with more than +one argument, and the returned function object can take a pointer, a +reference, or a smart pointer to an object instance as its first argument. +`mem_fn` also supports pointers to data members by treating them as functions +taking no arguments and returning a (const) reference to the member. + +The purpose of `mem_fn` is twofold. First, it allows users to invoke a member +function on a container with the familiar + + std::for_each(v.begin(), v.end(), boost::mem_fn(&Shape::draw)); + +syntax, even when the container stores smart pointers. + +Second, it can be used as a building block by library developers that want to +treat a pointer to member function as a function object. A library might +define an enhanced `for_each` algorithm with an overload of the form: + + template<class It, class R, class T> void for_each(It first, It last, R (T::*pmf) ()) + { + std::for_each(first, last, boost::mem_fn(pmf)); + } + +that will allow the convenient syntax: + + for_each(v.begin(), v.end(), &Shape::draw); + +When documenting the feature, the library author will simply state: + + template<class It, class R, class T> void for_each(It first, It last, R (T::*pmf) ()); + +* /Effects:/ Equivalent to `std::for_each(first, last, boost::mem_fn(pmf))`. + +where `boost::mem_fn` can be a link to this page. See the +[@boost:/libs/bind/bind.html documentation of `bind`] for an example. + +`mem_fn` takes one argument, a pointer to a member, and returns a function +object suitable for use with standard or user-defined algorithms: + + struct X + { + void f(); + }; + + void g(std::vector<X> & v) + { + std::for_each(v.begin(), v.end(), boost::mem_fn(&X::f)); + }; + + void h(std::vector<X *> const & v) + { + std::for_each(v.begin(), v.end(), boost::mem_fn(&X::f)); + }; + + void k(std::vector<boost::shared_ptr<X> > const & v) + { + std::for_each(v.begin(), v.end(), boost::mem_fn(&X::f)); + }; + +The returned function object takes the same arguments as the input member +function plus a "flexible" first argument that represents the object instance. + +When the function object is invoked with a first argument `x` that is neither +a pointer nor a reference to the appropriate class (`X` in the example above), +it uses `get_pointer(x)` to obtain a pointer from `x`. Library authors can +"register" their smart pointer classes by supplying an appropriate +`get_pointer` overload, allowing `mem_fn` to recognize and support them. + + +/[Note:/ `get_pointer` is not restricted to return a pointer. Any object that +can be used in a member function call expression `(x->*pmf)(...)` will work./]/ + +/[Note:/ the library uses an unqualified call to `get_pointer`. Therefore, it +will find, through argument-dependent lookup, `get_pointer` overloads that are +defined in the same namespace as the corresponding smart pointer class, in +addition to any `boost::get_pointer` overloads./]/ + +All function objects returned by `mem_fn` expose a `result_type` typedef that +represents the return type of the member function. For data members, +`result_type` is defined as the type of the member. + +[endsect] diff --git a/libs/bind/index.html b/libs/bind/index.html index b3f0d25e5..3f5edf312 100644 --- a/libs/bind/index.html +++ b/libs/bind/index.html @@ -1,11 +1,11 @@ <html> <head> -<meta http-equiv="refresh" content="0; URL=bind.html"> +<meta http-equiv="refresh" content="0; URL=doc/html/bind.html"> </head> <body> Automatic redirection failed, please go to -<a href="bind.html">bind.html</a> or -<a href="mem_fn.html">mem_fn.html</a>. +<a href="doc/html/bind.html">doc/html/bind.html</a> or +<a href="doc/html/mem_fn.html">doc/html/mem_fn.html</a>. </body> </html> <!-- diff --git a/libs/bind/mem_fn.html b/libs/bind/mem_fn.html index 0e9eb12f1..820d2ccc2 100644 --- a/libs/bind/mem_fn.html +++ b/libs/bind/mem_fn.html @@ -1,405 +1,28 @@ +<!DOCTYPE html> <html> - <head> - <title>Boost: mem_fn.hpp documentation</title> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - </head> - <body bgcolor="white" style="MARGIN-LEFT: 5%; MARGIN-RIGHT: 5%"> - <table border="0" width="100%"> - <tr> - <td width="277"><A href="../../index.htm"> <img src="../../boost.png" alt="boost.png (6897 bytes)" width="277" height="86" border="0"></A> - </td> - <td align="center"> - <h1>mem_fn.hpp</h1> - </td> - </tr> - <tr> - <td colspan="2" height="64"> </td> - </tr> - </table> - <h2>Contents</h2> - <h3 style="MARGIN-LEFT: 20pt"><a href="#Purpose">Purpose</a></h3> - <h3 style="MARGIN-LEFT: 20pt"><a href="#FAQ">Frequently Asked Questions</a></h3> - <h4 style="MARGIN-LEFT: 40pt"><a href="#Q1">Can <b>mem_fn</b> be used instead of the - standard <b>std::mem_fun[_ref]</b> adaptors?</a></h4> - <h4 style="MARGIN-LEFT: 40pt"><a href="#Q2">Should I replace every occurence of <b>std::mem_fun[_ref]</b> - with <b>mem_fn</b> in my existing code?</a></h4> - <h4 style="MARGIN-LEFT: 40pt"><a href="#Q3">Does <b>mem_fn</b> work with COM methods?</a></h4> - <h4 style="MARGIN-LEFT: 40pt"><a href="#Q4">Why isn't BOOST_MEM_FN_ENABLE_STDCALL - defined automatically?</a></h4> - <h3 style="MARGIN-LEFT: 20pt"><a href="#Interface">Interface</a></h3> - <h4 style="MARGIN-LEFT: 40pt"><a href="#Synopsis">Synopsis</a></h4> - <h4 style="MARGIN-LEFT: 40pt"><a href="#CommonRequirements">Common requirements</a></h4> - <h4 style="MARGIN-LEFT: 40pt"><a href="#get_pointer">get_pointer</a></h4> - <h4 style="MARGIN-LEFT: 40pt"><a href="#mem_fn">mem_fn</a></h4> - <h3 style="MARGIN-LEFT: 20pt"><a href="#Implementation">Implementation</a></h3> - <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" and - "__fastcall" Support</a></h4> - <h3 style="MARGIN-LEFT: 20pt"><a href="#Acknowledgements">Acknowledgements</a></h3> - <h2><a name="Purpose">Purpose</a></h2> - <p> - <b>boost::mem_fn</b> is a generalization of the standard functions <b>std::mem_fun</b> - and <b>std::mem_fun_ref</b>. It supports member function pointers with more - than one argument, and the returned function object can take a pointer, a - reference, or a smart pointer to an object instance as its first argument. <STRONG>mem_fn</STRONG> - also supports pointers to data members by treating them as functions taking no - arguments and returning a (const) reference to the member. - </p> - <p> - The purpose of <b>mem_fn</b> is twofold. First, it allows users to invoke a - member function on a container with the familiar - </p> - <pre> - std::for_each(v.begin(), v.end(), boost::mem_fn(&Shape::draw)); -</pre> - <p> - syntax, even when the container stores smart pointers. - </p> - <p> - Second, it can be used as a building block by library developers that want to - treat a pointer to member function as a function object. A library might define - an enhanced <b>for_each</b> algorithm with an overload of the form: - </p> - <pre> -template<class It, class R, class T> void for_each(It first, It last, R (T::*pmf) ()) -{ - std::for_each(first, last, boost::mem_fn(pmf)); -} -</pre> - <p> - that will allow the convenient syntax: - </p> - <pre> - for_each(v.begin(), v.end(), &Shape::draw); -</pre> - <p> - When documenting the feature, the library author will simply state: - </p> - <h4 style="MARGIN-LEFT: 20pt">template<class It, class R, class T> void - for_each(It first, It last, R (T::*pmf) ());</h4> - <p style="MARGIN-LEFT: 20pt"> - <b>Effects:</b> equivalent to std::for_each(first, last, boost::mem_fn(pmf)); - </p> - <p> - where <b>boost::mem_fn</b> can be a link to this page. See <a href="bind.html">the - documentation of <b>bind</b></a> for an example. - </p> - <p> - <b>mem_fn</b> takes one argument, a pointer to a member, and returns a function - object suitable for use with standard or user-defined algorithms: - </p> - <pre> -struct X -{ - void f(); -}; - -void g(std::vector<X> & v) -{ - std::for_each(v.begin(), v.end(), boost::mem_fn(&X::f)); -}; - -void h(std::vector<X *> const & v) -{ - std::for_each(v.begin(), v.end(), boost::mem_fn(&X::f)); -}; - -void k(std::vector<boost::shared_ptr<X> > const & v) -{ - std::for_each(v.begin(), v.end(), boost::mem_fn(&X::f)); -}; -</pre> - <p> - The returned function object takes the same arguments as the input member - function plus a "flexible" first argument that represents the object instance. - </p> - <p> - When the function object is invoked with a first argument <b>x</b> that is - neither a pointer nor a reference to the appropriate class (<b>X</b> in the - example above), it uses <tt>get_pointer(x)</tt> to obtain a pointer from <b>x</b>. - Library authors can "register" their smart pointer classes by supplying an - appropriate <b>get_pointer</b> overload, allowing <b>mem_fn</b> to recognize - and support them. - </p> - <p> - [Note: <b>get_pointer</b> is not restricted to return a pointer. Any object - that can be used in a member function call expression <tt>(x->*pmf)(...)</tt> - will work.] - </p> - <p> - [Note: the library uses an unqualified call to <b>get_pointer</b>. Therefore, - it will find, through argument-dependent lookup, <b>get_pointer</b> overloads - that are defined in the same namespace as the corresponding smart pointer - class, in addition to any <b>boost::get_pointer</b> overloads.] - </p> - <p> - All function objects returned by <b>mem_fn</b> expose a <b>result_type</b> typedef - that represents the return type of the member function. For data members, <STRONG>result_type</STRONG> - is defined as the type of the member. - </p> - <h2><a name="FAQ">Frequently Asked Questions</a></h2> - <h3><a name="Q1">Can <b>mem_fn</b> be used instead of the standard <b>std::mem_fun[_ref]</b> - adaptors?</a></h3> - <p> - Yes. For simple uses, <b>mem_fn</b> provides additional functionality that the - standard adaptors do not. Complicated expressions that use <b>std::bind1st</b>, <b>std::bind2nd</b> - or <a href="http://www.boost.org/doc/libs/1_31_0/libs/compose/index.htm"><b>Boost.Compose</b></a> along with the - standard adaptors can be rewritten using <a href="bind.html"><b>boost::bind</b></a> - that automatically takes advantage of <b>mem_fn</b>. - </p> - <h3><a name="Q2">Should I replace every occurence of <b>std::mem_fun[_ref]</b> with <b>mem_fn</b> - in my existing code?</a></h3> - <p> - No, unless you have good reasons to do so. <b>mem_fn</b> is not 100% compatible - with the standard adaptors, although it comes pretty close. In particular, <b>mem_fn</b> - does not return objects of type <b>std::[const_]mem_fun[1][_ref]_t</b>, as the - standard adaptors do, and it is not possible to fully describe the type of the - first argument using the standard <b>argument_type</b> and <b>first_argument_type</b> - nested typedefs. Libraries that need adaptable function objects in order to - function might not like <b>mem_fn</b>. - </p> - <h3><a name="Q3">Does <b>mem_fn</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="Q4">Why isn't BOOST_MEM_FN_ENABLE_STDCALL defined automatically?</a></h3> - <p> - Non-portable extensions, in general, should default to off to prevent vendor - lock-in. Had BOOST_MEM_FN_ENABLE_STDCALL been defined automatically, you could - have accidentally taken advantage of it without realizing that your code is, - perhaps, no longer portable. In addition, it is possible for the default - calling convention to be __stdcall, in which case enabling __stdcall support - will result in duplicate definitions. - </p> - <h2><a name="Interface">Interface</a></h2> - <h3><a name="Synopsis">Synopsis</a></h3> - <pre> -namespace boost -{ - -template<class T> T * <a href="#get_pointer_1">get_pointer</a>(T * p); - -template<class R, class T> <i>unspecified-1</i> <a href="#mem_fn_1">mem_fn</a>(R (T::*pmf) ()); - -template<class R, class T> <i>unspecified-2</i> <a href="#mem_fn_2">mem_fn</a>(R (T::*pmf) () const); - -template<class R, class T> <i>unspecified-2-1</i> <a href="#mem_fn_2_1">mem_fn</a>(R T::*pm); - -template<class R, class T, class A1> <i>unspecified-3</i> <a href="#mem_fn_3">mem_fn</a>(R (T::*pmf) (A1)); - -template<class R, class T, class A1> <i>unspecified-4</i> <a href="#mem_fn_4">mem_fn</a>(R (T::*pmf) (A1) const); - -template<class R, class T, class A1, class A2> <i>unspecified-5</i> <a href="#mem_fn_5">mem_fn</a>(R (T::*pmf) (A1, A2)); - -template<class R, class T, class A1, class A2> <i>unspecified-6</i> <a href="#mem_fn_6">mem_fn</a>(R (T::*pmf) (A1, A2) const); - -// implementation defined number of additional overloads for more arguments - -} -</pre> - <h3><a name="CommonRequirements">Common requirements</a></h3> - <p> - All <tt><i>unspecified-N</i></tt> types mentioned in the Synopsis are <b>CopyConstructible</b> - and <b>Assignable</b>. Their copy constructors and assignment operators do not - throw exceptions. <tt><i>unspecified-N</i>::result_type</tt> is defined as the - return type of the member function pointer passed as an argument to <b>mem_fn</b> - (<b>R</b> in the Synopsis.) <tt><i>unspecified-2-1</i>::result_type</tt> is - defined as <tt>R</tt>. - </p> - <h3><a name="get_pointer">get_pointer</a></h3> - <h4><a name="get_pointer_1">template<class T> T * get_pointer(T * p)</a></h4> - <blockquote> - <p> - <b>Returns:</b> <tt>p</tt>. - </p> - <p> - <b>Throws:</b> Nothing. - </p> - </blockquote> - <h3><a name="mem_fn">mem_fn</a></h3> - <h4><a name="mem_fn_1">template<class R, class T> <i>unspecified-1</i> mem_fn(R - (T::*pmf) ())</a></h4> - <blockquote> - <p> - <b>Returns:</b> a function object <i>f</i> such that the expression <tt><i>f(t)</i></tt> - is equivalent to <tt>(t.*pmf)()</tt> when <i>t</i> is an l-value of type <STRONG>T </STRONG> - or derived, <tt>(get_pointer(t)->*pmf)()</tt> otherwise. - </p> - <p> - <b>Throws:</b> Nothing. - </p> - </blockquote> - <h4><a name="mem_fn_2">template<class R, class T> <i>unspecified-2</i> mem_fn(R - (T::*pmf) () const)</a></h4> - <blockquote> - <p> - <b>Returns:</b> a function object <i>f</i> such that the expression <tt><i>f(t)</i></tt> - is equivalent to <tt>(t.*pmf)()</tt> when <i>t</i> is of type <STRONG>T</STRONG> - <EM>[const]<STRONG> </STRONG></EM>or derived, <tt>(get_pointer(t)->*pmf)()</tt> - otherwise. - </p> - <p> - <b>Throws:</b> Nothing. - </p> - </blockquote> - <h4><a name="mem_fn_2_1">template<class R, class T> <i>unspecified-2-1</i> mem_fn(R - T::*pm)</a></h4> - <blockquote> - <p> - <b>Returns:</b> a function object <i>f</i> such that the expression <tt><i>f(t)</i></tt> - is equivalent to <tt>t.*pm</tt> when <i>t</i> is of type <STRONG>T</STRONG> <EM>[const]<STRONG> - </STRONG></EM>or derived, <tt>get_pointer(t)->*pm</tt> otherwise. - </p> - <p> - <b>Throws:</b> Nothing. - </p> - </blockquote> - <h4><a name="mem_fn_3">template<class R, class T, class A1> <i>unspecified-3</i> mem_fn(R - (T::*pmf) (A1))</a></h4> - <blockquote> - <p> - <b>Returns:</b> a function object <i>f</i> such that the expression <tt><i>f(t, a1)</i></tt> - is equivalent to <tt>(t.*pmf)(a1)</tt> when <i>t</i> is an l-value of type <STRONG>T - </STRONG>or derived, <tt>(get_pointer(t)->*pmf)(a1)</tt> otherwise. - </p> - <p> - <b>Throws:</b> Nothing. - </p> - </blockquote> - <h4><a name="mem_fn_4">template<class R, class T, class A1> <i>unspecified-4</i> mem_fn(R - (T::*pmf) (A1) const)</a></h4> - <blockquote> - <p> - <b>Returns:</b> a function object <i>f</i> such that the expression <tt><i>f(t, a1)</i></tt> - is equivalent to <tt>(t.*pmf)(a1)</tt> when <i>t</i> is of type <STRONG>T</STRONG> - <EM>[const]<STRONG> </STRONG></EM>or derived, <tt>(get_pointer(t)->*pmf)(a1)</tt> - otherwise. - </p> - <p> - <b>Throws:</b> Nothing. - </p> - </blockquote> - <h4><a name="mem_fn_5">template<class R, class T, class A1, class A2> <i>unspecified-5</i> - mem_fn(R (T::*pmf) (A1, A2))</a></h4> - <blockquote> - <p> - <b>Returns:</b> a function object <i>f</i> such that the expression <tt><i>f(t, a1, a2)</i></tt> - is equivalent to <tt>(t.*pmf)(a1, a2)</tt> when <i>t</i> is an l-value of type <STRONG> - T</STRONG> or derived, <tt>(get_pointer(t)->*pmf)(a1, a2)</tt> otherwise. - </p> - <p> - <b>Throws:</b> Nothing. - </p> - </blockquote> - <h4><a name="mem_fn_6">template<class R, class T, class A1, class A2> <i>unspecified-6</i> - mem_fn(R (T::*pmf) (A1, A2) const)</a></h4> - <blockquote> - <p> - <b>Returns:</b> a function object <i>f</i> such that the expression <tt><i>f(t, a1, a2)</i></tt> - is equivalent to <tt>(t.*pmf)(a1, a2)</tt> when <i>t</i> is of type <STRONG>T</STRONG> - <EM>[const]</EM> or derived, <tt>(get_pointer(t)->*pmf)(a1, a2)</tt> otherwise. - </p> - <p> - <b>Throws:</b> Nothing. - </p> - </blockquote> - <h2><a name="Implementation">Implementation</a></h2> - <h3><a name="Files">Files</a></h3> - <ul> - <li> - <a href="../../boost/mem_fn.hpp">boost/mem_fn.hpp</a> - (main header) - <li> - <a href="../../boost/bind/mem_fn_cc.hpp">boost/bind/mem_fn_cc.hpp</a> - (used by mem_fn.hpp, do not include directly) - <li> - <a href="../../boost/bind/mem_fn_vw.hpp">boost/bind/mem_fn_vw.hpp</a> - (used by mem_fn.hpp, do not include directly) - <li> - <a href="../../boost/bind/mem_fn_template.hpp">boost/bind/mem_fn_template.hpp</a> - (used by mem_fn.hpp, do not include directly) - <li> - <a href="test/mem_fn_test.cpp">libs/bind/test/mem_fn_test.cpp</a> - (test) - <li> - <a href="test/mem_fn_derived_test.cpp">libs/bind/test/mem_fn_derived_test.cpp</a> - (test with derived objects) - <li> - <a href="test/mem_fn_fastcall_test.cpp">libs/bind/test/mem_fn_fastcall_test.cpp</a> - (test for __fastcall) - <li> - <a href="test/mem_fn_stdcall_test.cpp">libs/bind/test/mem_fn_stdcall_test.cpp</a> - (test for __stdcall) - <li> - <a href="test/mem_fn_void_test.cpp">libs/bind/test/mem_fn_void_test.cpp</a> (test - for void returns)</li> - </ul> - <h3><a name="Dependencies">Dependencies</a></h3> - <ul> - <li> - <a href="../config/config.htm">Boost.Config</a></li> - </ul> - <h3><a name="NumberOfArguments">Number of Arguments</a></h3> - <p> - This implementation supports member functions with up to eight arguments. This - is not an inherent limitation of the design, but an implementation detail. - </p> - <h3><a name="stdcall">"__stdcall", "__cdecl" and "__fastcall" 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 - - 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>. - UDK, the component model of OpenOffice.org, uses <STRONG>__cdecl</STRONG>. - </p> - <p> - To use <b>mem_fn</b> with <b>__stdcall</b> member functions, <b>#define</b> the - macro <b>BOOST_MEM_FN_ENABLE_STDCALL</b> before including, directly or - indirectly, <b><boost/mem_fn.hpp></b>. - </p> - <P>To use <B>mem_fn</B> with <B>__fastcall</B> member functions, <B>#define</B> the - macro <B>BOOST_MEM_FN_ENABLE_FASTCALL</B> before including <B><boost/mem_fn.hpp></B>. - </P> - <P>To use <B>mem_fn</B> with <B>__cdecl</B> member functions, <B>#define</B> the - macro <B>BOOST_MEM_FN_ENABLE_CDECL</B> before including <B><boost/mem_fn.hpp></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 - mem_fn is used.</STRONG> Not following this rule can lead to obscure errors - when a header includes mem_fn.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> - <h2><a name="Acknowledgements">Acknowledgements</a></h2> - <p> - Rene Jager's initial suggestion of using traits classes to make <b>mem_fn</b> adapt - to user-defined smart pointers inspired the <b>get_pointer</b>-based design. - </p> - <p> - Numerous improvements were suggested during the formal review period by Richard - Crossley, Jens Maurer, Ed Brey, and others. Review manager was Darin Adler. - </p> - <p> - Steve Anichini pointed out that COM interfaces use <b>__stdcall</b>. - </p> - <p> - Dave Abrahams modified <b>bind</b> and <b>mem_fn</b> to support void returns on - deficient compilers. - </p> - <p>Daniel Boelzle pointed out that UDK uses <STRONG>__cdecl</STRONG>.<br> - <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 - 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> +<head> +<title>Boost.MemberFunction</title> +<meta charset="utf-8"> +<meta http-equiv="refresh" content="0; url=doc/html/mem_fn.html"> +<style> + body { + background: #fff; + color: #000; + } + a { + color: #00f; + text-decoration: none; + } +</style> +</head> +<body> + <p> + Automatic redirection failed, please go to + <a href="doc/html/mem_fn.html">doc/html/mem_fn.html</a> + </p> + <p> + © 2001, 2002 Peter Dimov and Multi Media Ltd.<br> + © 2003-2005 Peter Dimov + </p> +</body> </html> diff --git a/libs/bind/test/Jamfile.v2 b/libs/bind/test/Jamfile.v2 index 68dc83ddf..52e57cdb2 100644 --- a/libs/bind/test/Jamfile.v2 +++ b/libs/bind/test/Jamfile.v2 @@ -28,6 +28,9 @@ test-suite "bind" [ run bind_placeholder_test.cpp ] [ run bind_rvalue_test.cpp ] [ run bind_and_or_test.cpp ] + [ run bind_void_test.cpp ] + [ run bind_void_dm_test.cpp ] + [ run bind_void_mf_test.cpp ] [ run mem_fn_test.cpp ] [ run mem_fn_void_test.cpp ] [ run mem_fn_derived_test.cpp ] @@ -44,4 +47,7 @@ test-suite "bind" [ run bind_eq3_test.cpp ] [ run protect_test.cpp ] [ run mem_fn_unary_addr_test.cpp ] + [ run bind_function2_test.cpp ] + [ run bind_fwd_test.cpp ] + [ run bind_fwd2_test.cpp ] ; diff --git a/libs/bind/test/bind_function2_test.cpp b/libs/bind/test/bind_function2_test.cpp new file mode 100644 index 000000000..f991248a2 --- /dev/null +++ b/libs/bind/test/bind_function2_test.cpp @@ -0,0 +1,118 @@ +#include <boost/config.hpp> + +// +// bind_function2_test.cpp - regression test +// +// Copyright (c) 2015 Peter Dimov +// +// Distributed under 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 +// + +#include <boost/bind.hpp> +#include <boost/function.hpp> +#include <boost/detail/lightweight_test.hpp> + +// + +void fv1( int & a ) +{ + a = 17041; +} + +void fv2( int & a, int b ) +{ + a = b; +} + +void fv3( int & a, int b, int c ) +{ + a = b + c; +} + +void fv4( int & a, int b, int c, int d ) +{ + a = b + c + d; +} + +void fv5( int & a, int b, int c, int d, int e ) +{ + a = b + c + d + e; +} + +void fv6( int & a, int b, int c, int d, int e, int f ) +{ + a = b + c + d + e + f; +} + +void fv7( int & a, int b, int c, int d, int e, int f, int g ) +{ + a = b + c + d + e + f + g; +} + +void fv8( int & a, int b, int c, int d, int e, int f, int g, int h ) +{ + a = b + c + d + e + f + g + h; +} + +void fv9( int & a, int b, int c, int d, int e, int f, int g, int h, int i ) +{ + a = b + c + d + e + f + g + h + i; +} + +void function_test() +{ + int x = 0; + + { + boost::function<void(int&)> fw1 = boost::bind( fv1, _1 ); + fw1( x ); BOOST_TEST( x == 17041 ); + } + + { + boost::function<void(int&, int)> fw2 = boost::bind( fv2, _1, _2 ); + fw2( x, 1 ); BOOST_TEST( x == 1 ); + } + + { + boost::function<void(int&, int, int)> fw3 = boost::bind( fv3, _1, _2, _3 ); + fw3( x, 1, 2 ); BOOST_TEST( x == 1+2 ); + } + + { + boost::function<void(int&, int, int, int)> fw4 = boost::bind( fv4, _1, _2, _3, _4 ); + fw4( x, 1, 2, 3 ); BOOST_TEST( x == 1+2+3 ); + } + + { + boost::function<void(int&, int, int, int, int)> fw5 = boost::bind( fv5, _1, _2, _3, _4, _5 ); + fw5( x, 1, 2, 3, 4 ); BOOST_TEST( x == 1+2+3+4 ); + } + + { + boost::function<void(int&, int, int, int, int, int)> fw6 = boost::bind( fv6, _1, _2, _3, _4, _5, _6 ); + fw6( x, 1, 2, 3, 4, 5 ); BOOST_TEST( x == 1+2+3+4+5 ); + } + + { + boost::function<void(int&, int, int, int, int, int, int)> fw7 = boost::bind( fv7, _1, _2, _3, _4, _5, _6, _7 ); + fw7( x, 1, 2, 3, 4, 5, 6 ); BOOST_TEST( x == 1+2+3+4+5+6 ); + } + + { + boost::function<void(int&, int, int, int, int, int, int, int)> fw8 = boost::bind( fv8, _1, _2, _3, _4, _5, _6, _7, _8 ); + fw8( x, 1, 2, 3, 4, 5, 6, 7 ); BOOST_TEST( x == 1+2+3+4+5+6+7 ); + } + + { + boost::function<void(int&, int, int, int, int, int, int, int, int)> fw9 = boost::bind( fv9, _1, _2, _3, _4, _5, _6, _7, _8, _9 ); + fw9( x, 1, 2, 3, 4, 5, 6, 7, 8 ); BOOST_TEST( x == 1+2+3+4+5+6+7+8 ); + } +} + +int main() +{ + function_test(); + return boost::report_errors(); +} diff --git a/libs/bind/test/bind_fwd2_test.cpp b/libs/bind/test/bind_fwd2_test.cpp new file mode 100644 index 000000000..5b7bf9cdc --- /dev/null +++ b/libs/bind/test/bind_fwd2_test.cpp @@ -0,0 +1,121 @@ +#include <boost/config.hpp> + +// +// bind_fwd2_test.cpp - forwarding test for 2 arguments +// +// Copyright (c) 2015 Peter Dimov +// +// Distributed under 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 +// + +#include <boost/bind.hpp> +#include <boost/detail/lightweight_test.hpp> + +// + +int fv1( int const & a ) +{ + return a; +} + +void fv2_1( int & a, int const & b ) +{ + a = b; +} + +void fv2_2( int const & a, int & b ) +{ + b = a; +} + +int fv2_3( int const & a, int const & b ) +{ + return a+b; +} + +void test() +{ + { + int const a = 1; + int r = boost::bind( fv1, _1 )( a ); + BOOST_TEST( r == 1 ); + } + + { + int r = boost::bind( fv1, _1 )( 1 ); + BOOST_TEST( r == 1 ); + } + + { + int a = 1; + int const b = 2; + + boost::bind( fv2_1, _1, _2 )( a, b ); + + BOOST_TEST( a == 2 ); + } + + { + int a = 1; + + boost::bind( fv2_1, _1, _2 )( a, 2 ); + + BOOST_TEST( a == 2 ); + } + + { + int const a = 1; + int b = 2; + + boost::bind( fv2_2, _1, _2 )( a, b ); + + BOOST_TEST( b == 1 ); + } + + { + int b = 2; + + boost::bind( fv2_2, _1, _2 )( 1, b ); + + BOOST_TEST( b == 1 ); + } + + { + int const a = 1; + int const b = 2; + + int r = boost::bind( fv2_3, _1, _2 )( a, b ); + + BOOST_TEST( r == 3 ); + } + + { + int const a = 1; + + int r = boost::bind( fv2_3, _1, _2 )( a, 2 ); + + BOOST_TEST( r == 3 ); + } + + { + int const b = 2; + + int r = boost::bind( fv2_3, _1, _2 )( 1, b ); + + BOOST_TEST( r == 3 ); + } + + { + int r = boost::bind( fv2_3, _1, _2 )( 1, 2 ); + + BOOST_TEST( r == 3 ); + } +} + +int main() +{ + test(); + return boost::report_errors(); +} diff --git a/libs/bind/test/bind_fwd_test.cpp b/libs/bind/test/bind_fwd_test.cpp new file mode 100644 index 000000000..92bd3b184 --- /dev/null +++ b/libs/bind/test/bind_fwd_test.cpp @@ -0,0 +1,250 @@ +#include <boost/config.hpp> + +// +// bind_fwd_test.cpp - forwarding test +// +// Copyright (c) 2015 Peter Dimov +// +// Distributed under 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 +// + +#include <boost/bind.hpp> +#include <boost/detail/lightweight_test.hpp> + +// + +void fv1( int & a ) +{ + a = 1; +} + +void fv2( int & a, int & b ) +{ + a = 1; + b = 2; +} + +void fv3( int & a, int & b, int & c ) +{ + a = 1; + b = 2; + c = 3; +} + +void fv4( int & a, int & b, int & c, int & d ) +{ + a = 1; + b = 2; + c = 3; + d = 4; +} + +void fv5( int & a, int & b, int & c, int & d, int & e ) +{ + a = 1; + b = 2; + c = 3; + d = 4; + e = 5; +} + +void fv6( int & a, int & b, int & c, int & d, int & e, int & f ) +{ + a = 1; + b = 2; + c = 3; + d = 4; + e = 5; + f = 6; +} + +void fv7( int & a, int & b, int & c, int & d, int & e, int & f, int & g ) +{ + a = 1; + b = 2; + c = 3; + d = 4; + e = 5; + f = 6; + g = 7; +} + +void fv8( int & a, int & b, int & c, int & d, int & e, int & f, int & g, int & h ) +{ + a = 1; + b = 2; + c = 3; + d = 4; + e = 5; + f = 6; + g = 7; + h = 8; +} + +void fv9( int & a, int & b, int & c, int & d, int & e, int & f, int & g, int & h, int & i ) +{ + a = 1; + b = 2; + c = 3; + d = 4; + e = 5; + f = 6; + g = 7; + h = 8; + i = 9; +} + +void test() +{ + { + int a = 0; + + boost::bind( fv1, _1 )( a ); + + BOOST_TEST( a == 1 ); + } + + { + int a = 0; + int b = 0; + + boost::bind( fv2, _1, _2 )( a, b ); + + BOOST_TEST( a == 1 ); + BOOST_TEST( b == 2 ); + } + + { + int a = 0; + int b = 0; + int c = 0; + + boost::bind( fv3, _1, _2, _3 )( a, b, c ); + + BOOST_TEST( a == 1 ); + BOOST_TEST( b == 2 ); + BOOST_TEST( c == 3 ); + } + + { + int a = 0; + int b = 0; + int c = 0; + int d = 0; + + boost::bind( fv4, _1, _2, _3, _4 )( a, b, c, d ); + + BOOST_TEST( a == 1 ); + BOOST_TEST( b == 2 ); + BOOST_TEST( c == 3 ); + BOOST_TEST( d == 4 ); + } + + { + int a = 0; + int b = 0; + int c = 0; + int d = 0; + int e = 0; + + boost::bind( fv5, _1, _2, _3, _4, _5 )( a, b, c, d, e ); + + BOOST_TEST( a == 1 ); + BOOST_TEST( b == 2 ); + BOOST_TEST( c == 3 ); + BOOST_TEST( d == 4 ); + BOOST_TEST( e == 5 ); + } + + { + int a = 0; + int b = 0; + int c = 0; + int d = 0; + int e = 0; + int f = 0; + + boost::bind( fv6, _1, _2, _3, _4, _5, _6 )( a, b, c, d, e, f ); + + BOOST_TEST( a == 1 ); + BOOST_TEST( b == 2 ); + BOOST_TEST( c == 3 ); + BOOST_TEST( d == 4 ); + BOOST_TEST( e == 5 ); + BOOST_TEST( f == 6 ); + } + + { + int a = 0; + int b = 0; + int c = 0; + int d = 0; + int e = 0; + int f = 0; + int g = 0; + + boost::bind( fv7, _1, _2, _3, _4, _5, _6, _7 )( a, b, c, d, e, f, g ); + + BOOST_TEST( a == 1 ); + BOOST_TEST( b == 2 ); + BOOST_TEST( c == 3 ); + BOOST_TEST( d == 4 ); + BOOST_TEST( e == 5 ); + BOOST_TEST( f == 6 ); + BOOST_TEST( g == 7 ); + } + + { + int a = 0; + int b = 0; + int c = 0; + int d = 0; + int e = 0; + int f = 0; + int g = 0; + int h = 0; + + boost::bind( fv8, _1, _2, _3, _4, _5, _6, _7, _8 )( a, b, c, d, e, f, g, h ); + + BOOST_TEST( a == 1 ); + BOOST_TEST( b == 2 ); + BOOST_TEST( c == 3 ); + BOOST_TEST( d == 4 ); + BOOST_TEST( e == 5 ); + BOOST_TEST( f == 6 ); + BOOST_TEST( g == 7 ); + BOOST_TEST( h == 8 ); + } + + { + int a = 0; + int b = 0; + int c = 0; + int d = 0; + int e = 0; + int f = 0; + int g = 0; + int h = 0; + int i = 0; + + boost::bind( fv9, _1, _2, _3, _4, _5, _6, _7, _8, _9 )( a, b, c, d, e, f, g, h, i ); + + BOOST_TEST( a == 1 ); + BOOST_TEST( b == 2 ); + BOOST_TEST( c == 3 ); + BOOST_TEST( d == 4 ); + BOOST_TEST( e == 5 ); + BOOST_TEST( f == 6 ); + BOOST_TEST( g == 7 ); + BOOST_TEST( h == 8 ); + BOOST_TEST( i == 9 ); + } +} + +int main() +{ + test(); + return boost::report_errors(); +} diff --git a/libs/bind/test/bind_void_dm_test.cpp b/libs/bind/test/bind_void_dm_test.cpp new file mode 100644 index 000000000..ffa60f9ae --- /dev/null +++ b/libs/bind/test/bind_void_dm_test.cpp @@ -0,0 +1,72 @@ +#include <boost/config.hpp> + +#if defined(BOOST_MSVC) +#pragma warning(disable: 4786) // identifier truncated in debug info +#pragma warning(disable: 4710) // function not inlined +#pragma warning(disable: 4711) // function selected for automatic inline expansion +#pragma warning(disable: 4514) // unreferenced inline removed +#endif + +// +// bind_void_mf_test.cpp - test for bind<void> with member functions +// +// Copyright (c) 2008 Peter Dimov +// Copyright (c) 2014 Agustin Berge +// +// Distributed under 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) +// + +#include <boost/bind.hpp> +#include <boost/ref.hpp> + +#if defined(BOOST_MSVC) && (BOOST_MSVC < 1300) +#pragma warning(push, 3) +#endif + +#include <iostream> + +#if defined(BOOST_MSVC) && (BOOST_MSVC < 1300) +#pragma warning(pop) +#endif + +#include <boost/detail/lightweight_test.hpp> + +// + +struct Z +{ + int m; +}; + +void member_data_test() +{ + Z z = { 17041 }; + Z * pz = &z; + + boost::bind<void>( &Z::m, _1 )( z ); + boost::bind<void>( &Z::m, _1 )( pz ); + + boost::bind<void>( &Z::m, z )(); + boost::bind<void>( &Z::m, pz )(); + boost::bind<void>( &Z::m, boost::ref(z) )(); + + + Z const cz = z; + Z const * pcz = &cz; + + boost::bind<void>( &Z::m, _1 )( cz ); + boost::bind<void>( &Z::m, _1 )( pcz ); + + boost::bind<void>( &Z::m, cz )(); + boost::bind<void>( &Z::m, pcz )(); + boost::bind<void>( &Z::m, boost::ref(cz) )(); +} + +int main() +{ + member_data_test(); + + return boost::report_errors(); +} diff --git a/libs/bind/test/bind_void_mf_test.cpp b/libs/bind/test/bind_void_mf_test.cpp new file mode 100644 index 000000000..62c2dcda7 --- /dev/null +++ b/libs/bind/test/bind_void_mf_test.cpp @@ -0,0 +1,171 @@ +#include <boost/config.hpp> + +#if defined(BOOST_MSVC) +#pragma warning(disable: 4786) // identifier truncated in debug info +#pragma warning(disable: 4710) // function not inlined +#pragma warning(disable: 4711) // function selected for automatic inline expansion +#pragma warning(disable: 4514) // unreferenced inline removed +#endif + +// +// bind_void_mf_test.cpp - test for bind<void> with member functions +// +// Copyright (c) 2008 Peter Dimov +// Copyright (c) 2014 Agustin Berge +// +// Distributed under 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) +// + +#include <boost/bind.hpp> +#include <boost/ref.hpp> + +#if defined(BOOST_MSVC) && (BOOST_MSVC < 1300) +#pragma warning(push, 3) +#endif + +#include <iostream> + +#if defined(BOOST_MSVC) && (BOOST_MSVC < 1300) +#pragma warning(pop) +#endif + +#include <boost/detail/lightweight_test.hpp> + +// + +long global_result; + +// + +struct X +{ + mutable unsigned int hash; + + X(): hash(0) {} + + int f0() { f1(17); return 0; } + int g0() const { g1(17); return 0; } + + int f1(int a1) { hash = (hash * 17041 + a1) % 32768; return 0; } + int g1(int a1) const { hash = (hash * 17041 + a1 * 2) % 32768; return 0; } + + int f2(int a1, int a2) { f1(a1); f1(a2); return 0; } + int g2(int a1, int a2) const { g1(a1); g1(a2); return 0; } + + int f3(int a1, int a2, int a3) { f2(a1, a2); f1(a3); return 0; } + int g3(int a1, int a2, int a3) const { g2(a1, a2); g1(a3); return 0; } + + int f4(int a1, int a2, int a3, int a4) { f3(a1, a2, a3); f1(a4); return 0; } + int g4(int a1, int a2, int a3, int a4) const { g3(a1, a2, a3); g1(a4); return 0; } + + int f5(int a1, int a2, int a3, int a4, int a5) { f4(a1, a2, a3, a4); f1(a5); return 0; } + int g5(int a1, int a2, int a3, int a4, int a5) const { g4(a1, a2, a3, a4); g1(a5); return 0; } + + int f6(int a1, int a2, int a3, int a4, int a5, int a6) { f5(a1, a2, a3, a4, a5); f1(a6); return 0; } + int g6(int a1, int a2, int a3, int a4, int a5, int a6) const { g5(a1, a2, a3, a4, a5); g1(a6); return 0; } + + int f7(int a1, int a2, int a3, int a4, int a5, int a6, int a7) { f6(a1, a2, a3, a4, a5, a6); f1(a7); return 0; } + int g7(int a1, int a2, int a3, int a4, int a5, int a6, int a7) const { g6(a1, a2, a3, a4, a5, a6); g1(a7); return 0; } + + int f8(int a1, int a2, int a3, int a4, int a5, int a6, int a7, int a8) { f7(a1, a2, a3, a4, a5, a6, a7); f1(a8); return 0; } + int g8(int a1, int a2, int a3, int a4, int a5, int a6, int a7, int a8) const { g7(a1, a2, a3, a4, a5, a6, a7); g1(a8); return 0; } +}; + +void member_function_test() +{ + using namespace boost; + + X x; + + // 0 + + bind<void>(&X::f0, &x)(); + bind<void>(&X::f0, ref(x))(); + + bind<void>(&X::g0, &x)(); + bind<void>(&X::g0, x)(); + bind<void>(&X::g0, ref(x))(); + + // 1 + + bind<void>(&X::f1, &x, 1)(); + bind<void>(&X::f1, ref(x), 1)(); + + bind<void>(&X::g1, &x, 1)(); + bind<void>(&X::g1, x, 1)(); + bind<void>(&X::g1, ref(x), 1)(); + + // 2 + + bind<void>(&X::f2, &x, 1, 2)(); + bind<void>(&X::f2, ref(x), 1, 2)(); + + bind<void>(&X::g2, &x, 1, 2)(); + bind<void>(&X::g2, x, 1, 2)(); + bind<void>(&X::g2, ref(x), 1, 2)(); + + // 3 + + bind<void>(&X::f3, &x, 1, 2, 3)(); + bind<void>(&X::f3, ref(x), 1, 2, 3)(); + + bind<void>(&X::g3, &x, 1, 2, 3)(); + bind<void>(&X::g3, x, 1, 2, 3)(); + bind<void>(&X::g3, ref(x), 1, 2, 3)(); + + // 4 + + bind<void>(&X::f4, &x, 1, 2, 3, 4)(); + bind<void>(&X::f4, ref(x), 1, 2, 3, 4)(); + + bind<void>(&X::g4, &x, 1, 2, 3, 4)(); + bind<void>(&X::g4, x, 1, 2, 3, 4)(); + bind<void>(&X::g4, ref(x), 1, 2, 3, 4)(); + + // 5 + + bind<void>(&X::f5, &x, 1, 2, 3, 4, 5)(); + bind<void>(&X::f5, ref(x), 1, 2, 3, 4, 5)(); + + bind<void>(&X::g5, &x, 1, 2, 3, 4, 5)(); + bind<void>(&X::g5, x, 1, 2, 3, 4, 5)(); + bind<void>(&X::g5, ref(x), 1, 2, 3, 4, 5)(); + + // 6 + + bind<void>(&X::f6, &x, 1, 2, 3, 4, 5, 6)(); + bind<void>(&X::f6, ref(x), 1, 2, 3, 4, 5, 6)(); + + bind<void>(&X::g6, &x, 1, 2, 3, 4, 5, 6)(); + bind<void>(&X::g6, x, 1, 2, 3, 4, 5, 6)(); + bind<void>(&X::g6, ref(x), 1, 2, 3, 4, 5, 6)(); + + // 7 + + bind<void>(&X::f7, &x, 1, 2, 3, 4, 5, 6, 7)(); + bind<void>(&X::f7, ref(x), 1, 2, 3, 4, 5, 6, 7)(); + + bind<void>(&X::g7, &x, 1, 2, 3, 4, 5, 6, 7)(); + bind<void>(&X::g7, x, 1, 2, 3, 4, 5, 6, 7)(); + bind<void>(&X::g7, ref(x), 1, 2, 3, 4, 5, 6, 7)(); + + // 8 + + bind<void>(&X::f8, &x, 1, 2, 3, 4, 5, 6, 7, 8)(); + bind<void>(&X::f8, ref(x), 1, 2, 3, 4, 5, 6, 7, 8)(); + + bind<void>(&X::g8, &x, 1, 2, 3, 4, 5, 6, 7, 8)(); + bind<void>(&X::g8, x, 1, 2, 3, 4, 5, 6, 7, 8)(); + bind<void>(&X::g8, ref(x), 1, 2, 3, 4, 5, 6, 7, 8)(); + + BOOST_TEST( x.hash == 23558 ); +} + +int main() +{ + member_function_test(); + + return boost::report_errors(); +} diff --git a/libs/bind/test/bind_void_test.cpp b/libs/bind/test/bind_void_test.cpp new file mode 100644 index 000000000..bb1e80dae --- /dev/null +++ b/libs/bind/test/bind_void_test.cpp @@ -0,0 +1,139 @@ +#include <boost/config.hpp> + +#if defined(BOOST_MSVC) +#pragma warning(disable: 4786) // identifier truncated in debug info +#pragma warning(disable: 4710) // function not inlined +#pragma warning(disable: 4711) // function selected for automatic inline expansion +#pragma warning(disable: 4514) // unreferenced inline removed +#endif + +// +// bind_void_test.cpp - test for bind<void> +// +// Copyright (c) 2008 Peter Dimov +// Copyright (c) 2014 Agustin Berge +// +// Distributed under 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) +// + +#include <boost/bind.hpp> +#include <boost/ref.hpp> + +#if defined(BOOST_MSVC) && (BOOST_MSVC < 1300) +#pragma warning(push, 3) +#endif + +#include <iostream> + +#if defined(BOOST_MSVC) && (BOOST_MSVC < 1300) +#pragma warning(pop) +#endif + +#include <boost/detail/lightweight_test.hpp> + +// + +long global_result; + +long f_0() +{ + return global_result = 17041L; +} + +long f_1(long a) +{ + return global_result = a; +} + +long f_2(long a, long b) +{ + return global_result = a + 10 * b; +} + +long f_3(long a, long b, long c) +{ + return global_result = a + 10 * b + 100 * c; +} + +long f_4(long a, long b, long c, long d) +{ + return global_result = a + 10 * b + 100 * c + 1000 * d; +} + +long f_5(long a, long b, long c, long d, long e) +{ + return global_result = a + 10 * b + 100 * c + 1000 * d + 10000 * e; +} + +long f_6(long a, long b, long c, long d, long e, long f) +{ + return global_result = a + 10 * b + 100 * c + 1000 * d + 10000 * e + 100000 * f; +} + +long f_7(long a, long b, long c, long d, long e, long f, long g) +{ + return global_result = a + 10 * b + 100 * c + 1000 * d + 10000 * e + 100000 * f + 1000000 * g; +} + +long f_8(long a, long b, long c, long d, long e, long f, long g, long h) +{ + return global_result = a + 10 * b + 100 * c + 1000 * d + 10000 * e + 100000 * f + 1000000 * g + 10000000 * h; +} + +long f_9(long a, long b, long c, long d, long e, long f, long g, long h, long i) +{ + return global_result = a + 10 * b + 100 * c + 1000 * d + 10000 * e + 100000 * f + 1000000 * g + 10000000 * h + 100000000 * i; +} + +void function_test() +{ + using namespace boost; + + int const i = 1; + + BOOST_TEST( (bind<void>(f_0)(i), (global_result == 17041L)) ); + BOOST_TEST( (bind<void>(f_1, _1)(i), (global_result == 1L)) ); + BOOST_TEST( (bind<void>(f_2, _1, 2)(i), (global_result == 21L)) ); + BOOST_TEST( (bind<void>(f_3, _1, 2, 3)(i), (global_result == 321L)) ); + BOOST_TEST( (bind<void>(f_4, _1, 2, 3, 4)(i), (global_result == 4321L)) ); + BOOST_TEST( (bind<void>(f_5, _1, 2, 3, 4, 5)(i), (global_result == 54321L)) ); + BOOST_TEST( (bind<void>(f_6, _1, 2, 3, 4, 5, 6)(i), (global_result == 654321L)) ); + BOOST_TEST( (bind<void>(f_7, _1, 2, 3, 4, 5, 6, 7)(i), (global_result == 7654321L)) ); + BOOST_TEST( (bind<void>(f_8, _1, 2, 3, 4, 5, 6, 7, 8)(i), (global_result == 87654321L)) ); + BOOST_TEST( (bind<void>(f_9, _1, 2, 3, 4, 5, 6, 7, 8, 9)(i), (global_result == 987654321L)) ); +} + +// + +struct Y +{ + short operator()(short & r) const { return global_result = ++r; } + int operator()(int a, int b) const { return global_result = a + 10 * b; } + long operator() (long a, long b, long c) const { return global_result = a + 10 * b + 100 * c; } + void operator() (long a, long b, long c, long d) const { global_result = a + 10 * b + 100 * c + 1000 * d; } +}; + +void function_object_test() +{ + using namespace boost; + + short i(6); + + int const k = 3; + + BOOST_TEST( (bind<void>(Y(), ref(i))(), (global_result == 7)) ); + BOOST_TEST( (bind<void>(Y(), ref(i))(), (global_result == 8)) ); + BOOST_TEST( (bind<void>(Y(), i, _1)(k), (global_result == 38)) ); + BOOST_TEST( (bind<void>(Y(), i, _1, 9)(k), (global_result == 938)) ); + BOOST_TEST( (bind<void>(Y(), i, _1, 9, 4)(k), (global_result == 4938)) ); +} + +int main() +{ + function_test(); + function_object_test(); + + return boost::report_errors(); +} |