1 [/==============================================================================
2 Copyright (C) 2001-2010 Joel de Guzman
3 Copyright (C) 2001-2005 Dan Marsden
4 Copyright (C) 2001-2010 Thomas Heller
5 Copyright (C) 2015 John Fletcher
7 Distributed under the Boost Software License, Version 1.0. (See accompanying
8 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
9 ===============================================================================/]
13 ['Binding] is the act of tying together a function to some arguments for
14 deferred (lazy) evaluation. Named [link phoenix.modules.function lazy functions]
15 require a bit of typing. Unlike (unnamed) lambda expressions, we need to write a
16 functor somewhere offline, detached from the call site. If you wish to transform a
17 plain function, member function or member variable to a lambda expression, `bind`
20 [note Take note that binding functions, member functions or member variables is
21 monomorphic. Rather than binding functions, the preferred way is to write true
22 generic and polymorphic [link phoenix.modules.function lazy functions].]
24 There is a set of overloaded `bind` template functions. Each `bind(x)`
25 function generates a suitable binder object.
27 [section Binding Function Objects]
29 #include <boost/phoenix/bind/bind_function_object.hpp>
31 Binding function objects serves two purposes:
32 * Partial function application
33 * Quick adaption of already existing function objects
35 In order to deduce the return type of the function object, it has to implement
36 the __boost_result_of__ protocol. If the bound function object is polymorphic,
37 the resulting binding object is polymorphic.
41 [section Binding Functions]
43 #include <boost/phoenix/bind/bind_function.hpp>
45 Example, given a function `foo`:
49 std::cout << n << std::endl;
52 Here's how the function `foo` may be bound:
56 This is now a full-fledged expression that can finally
57 be evaluated by another function call invocation. A second function call will
58 invoke the actual `foo` function. Example:
65 [section Binding Member Functions]
67 #include <boost/phoenix/bind/bind_member_function.hpp>
69 Binding member functions can be done similarly. A bound member function takes in
70 a pointer or reference to an object as the first argument. For instance, given:
77 `xyz`'s `foo` member function can be bound as:
79 bind(&xyz::foo, obj, arg1) // obj is an xyz object
81 Take note that a lazy-member functions expects the first argument to be a
82 pointer or reference to an object. Both the object (reference or pointer) and
83 the arguments can be lazily bound. Examples:
86 bind(&xyz::foo, arg1, arg2) // arg1.foo(arg2)
87 bind(&xyz::foo, obj, arg1) // obj.foo(arg1)
88 bind(&xyz::foo, obj, 100) // obj.foo(100)
91 [section Binding Member Variables]
93 #include <boost/phoenix/bind/bind_member_variable.hpp>
95 Member variables can also be bound much like member functions. Member variables
96 are not functions. Yet, like the [link phoenix.modules.core.references `ref(x)`] that
97 acts like a nullary function returning a reference to the data, member variables,
98 when bound, act like a unary function, taking in a pointer or reference to an
99 object as its argument and returning a reference to the bound member variable.
107 `xyz::v` can be bound as:
109 bind(&xyz::v, obj) // obj is an xyz object
111 As noted, just like the bound member function, a bound member variable also
112 expects the first (and only) argument to be a pointer or reference to an object.
113 The object (reference or pointer) can be lazily bound. Examples:
116 bind(&xyz::v, arg1) // arg1.v
117 bind(&xyz::v, obj) // obj.v
118 bind(&xyz::v, arg1)(obj) = 4 // obj.v = 4
122 [section Compatibility with Boost.Bind]
124 `phoenix::bind` passes the older testcases of the Boost.Bind library. For those cases it is completely compatible and interchangeable. Some newer cases have been added to Boost.Bind in 2015 and compatibility in those cases is not guaranteed.
126 Further tests are needed to check compatibility with std::tr1::bind and std::bind from the C++11 standard.