|
|
||
Files
Purposeboost::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. Using bind with functions and function pointersGiven 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::bind1st(std::ptr_fun(f), 5)(x); bind covers the functionality of std::bind2nd as well: std::bind2nd(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) 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::ref and 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); Using bind with function objectsAny function object can be passed as a first argument to bind, but the syntax is a bit different. 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 in the general case):
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
[Note: when, hopefully, function template default arguments become part of C++, bind will no longer require the explicit specification of the return type when the function object defines result_type.] Using bind with member function pointersPointers to member functions are not function objects, because they do not support operator(). For convenience, bind accepts member function pointers as its first argument, and the behavior is as if boost::mem_fn has been used to convert the member function pointer into a function object. In other words, the expression bind(&X::f, args) is equivalent to bind<R>(mem_fn(&X::f), args) where R is the return type of X::f. [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 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::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(). Using nested binds for function compositionSome of the arguments passed to bind may be nested bind expressions themselves: bind(f, bind(g, _1))(x); // f(g(x)) The nested subexpressions are evaluated when the function object is called. This feature of bind can be used to perform function composition. See bind_as_compose.cpp for an example that demonstrates how to use bind to achieve similar functionality to Boost.Compose. Note that the first argument - the bound function object - is an exception to the nesting rules. A nested bind expression passed to bind as a first argument is not treated differently from any other function object:
int x = 4;
template<class F> void test(F f)
{
bind(f, 5)(x);
}
int g(int, int);
int main()
{
test(bind(g, _1, 8)); // g(5, 8) and not g(x, 8)(5)
}
Example: 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)));
}
Example: using bind with Boost.Function
class button
{
public:
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);
}
LimitationsThe 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, known as the "forwarding function problem." 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. An oft-proposed "solution" to this problem is to add an overload: template<class T> void f(T & t); template<class T> void f(T const & t); Unfortunately, this (a) requires providing 512 overloads for nine arguments and (b) does not actually work for const arguments, both l- and r-values, since the two templates produce the exact same signature and cannot be partially ordered. [Note: this is a dark corner of the language, and the corresponding issue has not been resolved yet.] InterfaceSynopsis
namespace boost
{
// no arguments
template<class R, class F> implementation-defined-1 bind(F f);
template<class R> implementation-defined-2 bind(R (*f) ());
// one argument
template<class R, class F, class A1> implementation-defined-3 bind(F f, A1 a1);
template<class R, class B1, class A1> implementation-defined-4 bind(R (*f) (B1), A1 a1);
template<class R, class T, class A1> implementation-defined-5 bind(R (T::*f) (), A1 a1);
template<class R, class T, class A1> implementation-defined-6 bind(R (T::*f) () const, A1 a1);
// two arguments
template<class R, class F, class A1, class A2> implementation-defined-7 bind(F f, A1 a1, A2 a2);
template<class R, class B1, class B2, class A1, class A2> implementation-defined-8 bind(R (*f) (B1, B2), A1 a1, A2 a2);
template<class R, class T, class B1, class A1, class A2> implementation-defined-9 bind(R (T::*f) (B1), A1 a1, A2 a2);
template<class R, class T, class B1, class A1, class A2> implementation-defined-10 bind(R (T::*f) (B1) const, A1 a1, A2 a2);
// implementation defined number of additional overloads for more arguments
}
namespace
{
implementation-defined-placeholder-type-1 _1;
implementation-defined-placeholder-type-2 _2;
implementation-defined-placeholder-type-3 _3;
// implementation defined number of additional placeholder definitions
}
Common requirementsAll implementation-defined-N types returned by bind are CopyConstructible. implementation-defined-N::result_type is defined as the return type of implementation-defined-N::operator(). All implementation-defined-placeholder-N types are CopyConstructible. Their copy constructors do not throw exceptions. Common definitionsThe function µ(x, v1, v2, ..., vm), where m is a nonnegative integer, is defined as:
bindtemplate<class R, class F> implementation-defined-1 bind(F f)Returns: a function object λ such that the expression λ(v1, v2, ..., vm) is equivalent to f(), implicitly converted to R. Throws: Nothing unless the copy constructor of F throws an exception. template<class R> implementation-defined-2 bind(R (*f) ())Returns: a function object λ such that the expression λ(v1, v2, ..., vm) is equivalent to f(). Throws: Nothing. template<class R, class F, class A1> implementation-defined-3 bind(F f, A1 a1)Returns: a function object λ such that the expression λ(v1, v2, ..., vm) is equivalent to f(µ(a1, v1, v2, ..., vm)), implicitly converted to R. Throws: Nothing unless the copy constructors of F and A1 throw an exception. template<class R, class B1, class A1> implementation-defined-4 bind(R (*f) (B1), A1 a1)Returns: a function object λ such that the expression λ(v1, v2, ..., vm) is equivalent to f(µ(a1, v1, v2, ..., vm)). Throws: Nothing unless the copy constructor of A1 throws an exception. template<class R, class T, class A1> implementation-defined-5 bind(R (T::*f) (), A1 a1)Effects: equivalent to bind<R>(boost::mem_fn(f), a1); template<class R, class T, class A1> implementation-defined-6 bind(R (T::*f) () const, A1 a1)Effects: equivalent to bind<R>(boost::mem_fn(f), a1); template<class R, class F, class A1, class A2> implementation-defined-7 bind(F f, A1 a1, A2 a2)Returns: a function object λ such that the expression λ(v1, v2, ..., vm) is equivalent to f(µ(a1, v1, v2, ..., vm), µ(a2, v1, v2, ..., vm)), implicitly converted to R. Throws: Nothing unless the copy constructors of F, A1 and A2 throw an exception. template<class R, class B1, class B2, class A1, class A2> implementation-defined-8 bind(R (*f) (B1, B2), A1 a1, A2 a2)Returns: a function object λ such that the expression λ(v1, v2, ..., vm) is equivalent to f(µ(a1, v1, v2, ..., vm), µ(a2, v1, v2, ..., vm)). Throws: Nothing unless the copy constructors of A1 and A2 throw an exception. template<class R, class T, class B1, class A1, class A2> implementation-defined-9 bind(R (T::*f) (B1), A1 a1, A2 a2)Effects: equivalent to bind<R>(boost::mem_fn(f), a1, a2); template<class R, class T, class B1, class A1, class A2> implementation-defined-10 bind(R (T::*f) (B1) const, A1 a1, A2 a2)Effects: equivalent to bind<R>(boost::mem_fn(f), a1, a2); ImplementationThis implementation supports function objects with up to nine arguments. This is an implementation detail, not an inherent limitation of the design. Void returnsThe following C++ code:
void f();
void g()
{
return f();
}
is legal; in fact it was deliberately made legal in order to support forwarding functions that return void. Unfortunately, some compilers have not caught up with the C++ Standard yet and do not allow void returns. This implementation of bind will not work for function pointers, member function pointers or function objects that return void if the compiler does not support the feature. A possible workaround is to change the return type of the function object in question from void to int and return a dummy value of 0. MSVC specific problems and workaroundsMicrosoft Visual C++ (up to version 7.0) does not fully support the bind<R>(...) syntax required by the library when arbitrary function objects are bound. The first problem is that when boost::bind is brought into scope with an using declaration: using boost::bind; the syntax above does not work. Workaround: either use the qualified name, boost::bind, or use an using directive instead: using namespace boost; The second problem is that some libraries contain nested class templates named bind (ironically, such code is often an MSVC specific workaround.) Due to some quirks with the parser, such a class template breaks the bind<R>(...) syntax, even when the name bind is fully qualified. You may try to patch the library in question or contact its author/maintainer. The other option is to define the macro BOOST_BIND to something other than bind (before the inclusion of <boost/bind.hpp>) and use this identifier throughout your code wherever you'd normally use bind. [Note: BOOST_BIND is not a general renaming mechanism. It is not part of the interface, and is not guaranteed to work on other compilers, or persist between library versions. In short, don't use it unless you absolutely have to.] Visitor support[Note: this is an experimental feature. It may evolve over time when other libraries start to exploit it; or it may be removed altogether if no other library needs it. It is not part of the interface.] For better integration with other libraries, the function objects returned by bind define a member function template<class Visitor> void accept(Visitor & v); that applies v, as a function object, to its internal state. Using accept is implementation-specific and not intended for end users. See bind_test_4.cpp for an example. AcknowledgementsEarlier efforts that have influenced the library design:
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 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ärvi.
|