- |
-
- |
-
- bind.hpp- |
-
| - | |
-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. -
- --Given these definitions: -
- -+ +Boost: bind.hpp documentation + + + +
|
+
+ |
+
+ bind.hpp+ |
+
| + | |
+ 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. +
++ Given these definitions: +
+
int f(int a, int b)
{
return a + b;
@@ -103,42 +103,35 @@ 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: -
- -++ 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: -
- -++ 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 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) @@ -147,49 +140,40 @@ 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: -
- -++ 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::ref and boost::cref -can be used to make the function object store a reference to an object, -rather than a copy: -
- -++ 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 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): -
- -+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; } @@ -200,61 +184,49 @@ F f; int x = 104; -bind<int>(f, _1, _1)(x); // f(x, x), i.e. zero +bind<int>(f, _1, _1)(x); // f(x, x), i.e. zero- --When the function object exposes a nested type named result_type, -the explicit return type can be omitted: -
- -++ 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 +bind(std::less<int>(), _1, 9)(x); // x < 9- --[Note: the ability to omit the return type is not available on all compilers.] -
- -Using bind with member function pointers
- --Pointers 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 -
- -++ [Note: the ability to omit the return type is not available on all compilers.] +
+Using bind with member function pointers
++ Pointers 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 -
- -++ 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: -
- -++ 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); @@ -266,75 +238,79 @@ 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) +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 composition
- --Some of the arguments passed to bind may be nested bind expressions -themselves: -
- -++ 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 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 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 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); --The nested subexpressions are evaluated when the function object is called. This -feature of bind can be used to perform function composition. -
+std::vector<pf> v; --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) -} +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 boost/bind/apply.hpp header file. Here is + how the modified version of the previous example looks like: +
++typedef void (*pf)(int); -Examples
+std::vector<pf> v; -Using bind with standard algorithms
- -+std::for_each(v.begin(), v.end(), bind(apply<void>(), _1, 5)); ++Sometimes it is necessary not to evaluate the first argument, but not + to evaluate some of the other arguments, 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 boost/bind/protect.hpp contains an + implementation of protect. To protect a bind + function object from evaluation, use protect(bind(f, ...)).
+Examples
+Using bind with standard algorithms
+class image; class animation @@ -364,10 +340,8 @@ void render(image & target) std::for_each(anims.begin(), anims.end(), boost::bind(&animation::render, _1, boost::ref(target))); }- -Using bind with Boost.Function
- -+Using bind with Boost.Function
+class button { public: @@ -392,143 +366,110 @@ void connect() stopButton.onClick = boost::bind(&player::stop, &thePlayer); }- -Limitations
- --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, known as the -"forwarding function problem." -
- --The library uses signatures of the form -
- -+Limitations
++ 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, 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: -
- -++ 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.] -
- -Frequently Asked Questions
- -Why doesn't this compile?
- --See the dedicated Troubleshooting 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. -
- -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, ...). -
- --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. -
- -Does bind work with Windows API functions?
- --Yes, if you #define BOOST_BIND_ENABLE_STDCALL. -An alternative is to treat the function as a -generic function object and use the -bind<R>(f, ...) syntax. -
- -Does bind work with COM methods?
- --Yes, if you #define BOOST_MEM_FN_ENABLE_STDCALL. -
- -Does bind work with Mac toolbox functions?
- --Yes, if you #define BOOST_BIND_ENABLE_PASCAL. -An alternative is to treat the function as a -generic function object and use the -bind<R>(f, ...) syntax. -
- -Why doesn't bind automatically recognize nonstandard functions?
- --Non-portable extensions, in general, should default to off to prevent vendor -lock-in. Had the 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 their default calling convention, in which case no -separate support would be necessary. -
- -Troubleshooting
- -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: -
- -++ 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.] +
+Frequently Asked Questions
+Why doesn't this compile?
++ See the dedicated Troubleshooting 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. +
+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, ...). +
++ 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. +
+Does bind work with Windows API functions?
++ Yes, if you #define BOOST_BIND_ENABLE_STDCALL. An + alternative is to treat the function as a generic + function object and use the bind<R>(f, ...) syntax. +
+Does bind work with COM methods?
++ Yes, if you #define BOOST_MEM_FN_ENABLE_STDCALL. +
+Does bind work with Mac toolbox functions?
++ Yes, if you #define BOOST_BIND_ENABLE_PASCAL. An + alternative is to treat the function as a generic + function object and use the bind<R>(f, ...) syntax. +
+Why doesn't bind automatically recognize + nonstandard functions?
++ Non-portable extensions, in general, should default to off to prevent vendor + lock-in. Had the 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 their default calling + convention, in which case no separate support would be necessary. +
+Troubleshooting
+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() @@ -537,13 +478,11 @@ int main() boost::bind(f, 1, 2); // OK }- --A common variation of this error is to forget that member functions have an -implicit "this" argument: -
- -++ A common variation of this error is to forget that member functions have an + implicit "this" argument: +
+struct X { int f(int); @@ -555,45 +494,38 @@ int main() boost::bind(&X::f, _1, 1); // OK }- -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: -
- -+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: -
- -++ 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, "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 + boost::bind(f, _1)("incompatible"); // error, "incompatible" is not an int }- -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: -
- -+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() @@ -602,63 +534,55 @@ int main() boost::bind(f, _1)(); // error, there is no argument number 1 }- --The error is usually reported in bind.hpp, at a line similar to: -
- -++ 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). -
- -Inappropriate use of bind(f, ...)
- --The bind(f, a1, a2, ..., aN) 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. -
- -Inappropriate use of bind<R>(f, ...)
- --The bind<R>(f, a1, a2, ..., aN) 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. -
- -Binding a nonstandard function
- --(to be written) -
- -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: -
- -++ 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). +
+Inappropriate use of bind(f, ...)
++ The bind(f, a1, a2, ..., aN) 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. +
+Inappropriate use of bind<R>(f, ...)
++ The bind<R>(f, a1, a2, ..., aN) 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. +
+Binding a nonstandard function
++ By default, the bind(f, a1, a2, ..., aN) form recognizes + "ordinary" C++ functions and function pointers. 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) form works with nonstandard functions. +
++ See also "__stdcall" and "pascal" Support.
+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() @@ -666,68 +590,52 @@ int main() boost::bind(f, 1); // error }- --Workaround: remove the const qualifier from the argument. -
- -MSVC specific: using boost::bind;
- --On MSVC (up to version 7.0), when boost::bind is brought into scope -with an using declaration: -
- -++ Workaround: remove the const qualifier from the argument. +
+MSVC specific: using boost::bind;
++ On MSVC (up to version 7.0), when boost::bind is brought into scope with + an using declaration: +
+using boost::bind;- --the syntax bind<R>(...) does not work. Workaround: either use the -qualified name, boost::bind, or use an using directive instead: -
- -++ the syntax bind<R>(...) does not work. Workaround: either use the + qualified name, boost::bind, or use an using directive instead: +
+using namespace boost;- -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>(...) syntax. Unfortunately, some libraries contain nested -class templates named bind (ironically, such code is often an MSVC -specific workaround.) You may try to patch the library in question or contact -its author/maintainer. The other option is use the -BOOST_BIND macro to rename bind. -
- -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); +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>(...) + syntax. Unfortunately, some libraries contain nested class templates named bind + (ironically, such code is often an MSVC specific workaround.) You may try to + patch the library in question or contact its author/maintainer. The other + option is use the BOOST_BIND macro to rename bind. +
+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); ++ and will reject the correct version: +
++ bind<int>(printf, "%s\n", _1);- -Interface
- -Synopsis
- -+Interface
+Synopsis
+namespace boost { @@ -780,299 +688,331 @@ namespace }- -Common requirements
- --All 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 definitions
- --The function µ(x, v1, v2, ..., vm), where m is a nonnegative integer, is defined as: -
- -
-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. -
- --Effects: equivalent to bind<typename F::result_type, F>(f); -
- --Returns: a function object λ such that the expression -λ(v1, v2, ..., vm) is equivalent to f(). -
--Throws: Nothing. -
- --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 or A1 throw an exception. -
- --Effects: equivalent to bind<typename F::result_type, F, A1>(f, 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. -
- --Effects: equivalent to bind<R>(boost::mem_fn(f), a1); -
- --Effects: equivalent to bind<R>(boost::mem_fn(f), a1); -
- --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 or A2 throw an exception. -
- --Effects: equivalent to bind<typename F::result_type, F, A1, A2>(f, a1, 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 or A2 throw an exception. -
- --Effects: equivalent to bind<R>(boost::mem_fn(f), a1, a2); -
- --Effects: equivalent to bind<R>(boost::mem_fn(f), a1, a2); -
- --This implementation supports function objects with up to nine arguments. -This is an implementation detail, not an inherent limitation of the -design. -
- --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. 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 pascal functions, #define the macro -BOOST_BIND_ENABLE_PASCAL before including <boost/bind.hpp>. -
- --[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.] -
- --A bug in MSVC (up to version 7.0) -causes boost::bind to be incompatible -with libraries that contain nested class templates named bind. To work -around this problem, #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.] -
- --Function objects returned by bind support the experimental and -undocumented, as of yet, visit_each enumeration interface. -
- --See bind_visitor.cpp for an example. -
- --Earlier 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. -
- --Dave Abrahams fixed a MSVC-specific conflict between bind and the -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. -
- -
Copyright © 2001 by Peter Dimov and Multi Media
-Ltd. Permission to copy, use, modify, sell and distribute this document is
-granted provided this copyright notice appears in all copies. This document
-is provided "as is" without express or implied warranty, and with
-no claim as to its suitability for any purpose.
+ All 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. +
++ The function µ(x, v1, v2, ..., vm), where m is + a nonnegative integer, is defined as: +
++++ 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. +
+
+++ Effects: equivalent to bind<typename F::result_type, F>(f); +
+
+++ Returns: a function object λ such that the expression λ(v1, + v2, ..., vm) is equivalent to f(). +
++ Throws: Nothing. +
+
+++ 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 or A1 throw + an exception. +
+
+++ Effects: equivalent to bind<typename F::result_type, F, A1>(f, + 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. +
+
+++ Effects: equivalent to bind<R>(boost::mem_fn(f), + a1); +
+
+++ Effects: equivalent to bind<R>(boost::mem_fn(f), + a1); +
+
+++ 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 or A2 + throw an exception. +
+
+++ Effects: equivalent to bind<typename F::result_type, F, A1, A2>(f, + a1, 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 or A2 throw + an exception. +
+
+++ Effects: equivalent to bind<R>(boost::mem_fn(f), + a1, a2); +
+
+++ Effects: equivalent to bind<R>(boost::mem_fn(f), + a1, a2); +
+
+ This implementation supports function objects with up to nine arguments. This + is an implementation detail, not an inherent limitation of the design. +
++ 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. 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 pascal functions, #define the macro BOOST_BIND_ENABLE_PASCAL + before including <boost/bind.hpp>. +
++ [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.] +
++ A bug in MSVC (up to version 7.0) causes boost::bind + to be incompatible with libraries that contain nested class templates named bind. + To work around this problem, #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.] +
++ Function objects returned by bind support the experimental and + undocumented, as of yet, visit_each enumeration interface. +
++ See bind_visitor.cpp for an example. +
++ Earlier 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. +
++ Dave Abrahams fixed a MSVC-specific conflict between bind and the + 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. +
+
+
+
+ Copyright © 2001, 2002 by Peter Dimov and Multi Media Ltd. Permission
+ to copy, use, modify, sell and distribute this document is granted provided
+ this copyright notice appears in all copies. This document is provided "as is"
+ without express or implied warranty, and with no claim as to its suitability
+ for any purpose.
|
-
- |
-
- mem_fn.hpp- |
-
| - | |
-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. -
- --The purpose of mem_fn is twofold. First, it allows users to invoke a -member function on a container with the familiar -
- -+ +Boost: mem_fn.hpp documentation + + + +
|
+
+ |
+
+ mem_fn.hpp+ |
+
| + | |
+ 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. +
++ 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: -
- -++ 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: -
- -++ 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 documentation of bind for an example. -
- --mem_fn takes one argument, a pointer to a member function, and -returns a function object suitable for use with standard or user-defined -algorithms: -
- -++ 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 + documentation of bind for an example. +
++ mem_fn takes one argument, a pointer to a member function, and returns a + function object suitable for use with standard or user-defined algorithms: +
+struct X { void f(); @@ -131,97 +110,72 @@ 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. -
- --A get_pointer overload for boost::shared_ptr is supplied. -
- --[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. -
- -Frequently Asked Questions
- -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 Boost.Compose -along with the standard adaptors can be rewritten using -boost::bind that automatically takes advantage of -mem_fn. -
- -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. -
- -Does mem_fn work with COM methods?
- --Yes, if you #define BOOST_MEM_FN_ENABLE_STDCALL. -
- -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. -
- -Interface
- -Synopsis
- -++ 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. +
+Frequently Asked Questions
+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 Boost.Compose along with the + standard adaptors can be rewritten using boost::bind + that automatically takes advantage of mem_fn. +
+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. +
+Does mem_fn work with COM methods?
++ Yes, if you #define BOOST_MEM_FN_ENABLE_STDCALL. +
+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. +
+Interface
+Synopsis
+namespace boost { -template<class T> T * get_pointer(T * p); - -template<class T> T * get_pointer(shared_ptr<T> const & p); +template<class T> T * get_pointer (T * p); template<class R, class T> implementation-defined-1 mem_fn(R (T::*pmf) ()); @@ -239,189 +193,179 @@ template<class R, class T, class A1, class A2> implementation-defined-6 }- -Common requirements
- --All implementation-defined-N types mentioned in the Synopsis are -CopyConstructible and Assignable. -Their copy constructors and assignment operators do not throw exceptions. -implementation-defined-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.) -
- -get_pointer
- -template<class T> T * get_pointer(T * p)
- --Returns: p. -
--Throws: Nothing. -
- -template<class T> T * get_pointer(shared_ptr<T> const & p)
- --Returns: p.get(). -
--Throws: Nothing. -
- -mem_fn
- -template<class R, class T> implementation-defined-1 mem_fn(R (T::*pmf) ())
- --Returns: a function object f such that the expression -f(t) is equivalent to (t.*pmf)() when t -is an l-value of type T, (get_pointer(t)->*pmf)() otherwise. -
--Throws: Nothing. -
- -template<class R, class T> implementation-defined-2 mem_fn(R (T::*pmf) () const)
- --Returns: a function object f such that the expression -f(t) is equivalent to (t.*pmf)() when t -is of type T [const], (get_pointer(t)->*pmf)() otherwise. -
--Throws: Nothing. -
- -template<class R, class T, class A1> implementation-defined-3 mem_fn(R (T::*pmf) (A1))
- --Returns: a function object f such that the expression -f(t, a1) is equivalent to (t.*pmf)(a1) when t -is an l-value of type T, (get_pointer(t)->*pmf)(a1) otherwise. -
--Throws: Nothing. -
- -template<class R, class T, class A1> implementation-defined-4 mem_fn(R (T::*pmf) (A1) const)
- --Returns: a function object f such that the expression -f(t, a1) is equivalent to (t.*pmf)(a1) when t -is of type T [const], (get_pointer(t)->*pmf)(a1) otherwise. -
--Throws: Nothing. -
- -template<class R, class T, class A1, class A2> implementation-defined-5 mem_fn(R (T::*pmf) (A1, A2))
- --Returns: a function object f such that the expression -f(t, a1, a2) is equivalent to (t.*pmf)(a1, a2) when t -is an l-value of type T, (get_pointer(t)->*pmf)(a1, a2) otherwise. -
--Throws: Nothing. -
- -template<class R, class T, class A1, class A2> implementation-defined-6 mem_fn(R (T::*pmf) (A1, A2) const)
- --Returns: a function object f such that the expression -f(t, a1, a2) is equivalent to (t.*pmf)(a1, a2) when t -is of type T [const], (get_pointer(t)->*pmf)(a1, a2) otherwise. -
--Throws: Nothing. -
- -Implementation
- -Files
-
-This implementation supports member functions with up to eight arguments. -This is not an inherent limitation of the design, but an implementation -detail. -
- --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. -
- --To use mem_fn with __stdcall member functions, #define -the macro BOOST_MEM_FN_ENABLE_STDCALL before including, directly or -indirectly, <boost/mem_fn.hpp>. -
- --[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.] -
- - --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. -
- -
Copyright © 2001 by Peter Dimov and Multi Media
-Ltd. Permission to copy, use, modify, sell and distribute this document is
-granted provided this copyright notice appears in all copies. This document
-is provided "as is" without express or implied warranty, and with
-no claim as to its suitability for any purpose.
+ All implementation-defined-N types mentioned in the Synopsis + are CopyConstructible and Assignable. Their copy constructors and + assignment operators do not throw exceptions. implementation-defined-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.) +
++++ Returns: p. +
++ Throws: Nothing. +
+
+++ Returns: a function object f such that the expression f(t) + is equivalent to (t.*pmf)() when t is an l-value of type T + or derived, (get_pointer(t)->*pmf)() otherwise. +
++ Throws: Nothing. +
+
+++ Returns: a function object f such that the expression f(t) + is equivalent to (t.*pmf)() when t is of type T + [const] or derived, (get_pointer(t)->*pmf)() + otherwise. +
++ Throws: Nothing. +
+
+++ Returns: a function object f such that the expression f(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. +
+
+++ Returns: a function object f such that the expression f(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. +
+
+++ Returns: a function object f such that the expression f(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. +
+
+++ Returns: a function object f such that the expression f(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. +
+
+ This implementation supports member functions with up to eight arguments. This + is not an inherent limitation of the design, but an implementation detail. +
++ 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. +
++ To use mem_fn with __stdcall member functions, #define the + macro BOOST_MEM_FN_ENABLE_STDCALL before including, directly or + indirectly, <boost/mem_fn.hpp>. +
++ [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.] +
++ 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. +
+
+
+
+ Copyright © 2001, 2002 by Peter Dimov and Multi Media Ltd. Permission
+ to copy, use, modify, sell and distribute this document is granted provided
+ this copyright notice appears in all copies. This document is provided "as is"
+ without express or implied warranty, and with no claim as to its suitability
+ for any purpose.
|
-
- |
-
-
|
-Files-
Purpose- --The header boost/ref.hpp defines the class template -boost::reference_wrapper<T>, the two functions boost::ref and -boost::cref that return instances of -boost::reference_wrapper<T>, and the two traits classes boost::is_reference_wrapper<T> and boost::unwrap_reference<T>. - - --The purpose of boost::reference_wrapper<T> is to contain a reference to -an object of type T. It is primarily used to "feed" references to -function templates (algorithms) that take their parameter by value. - - --To support this usage, boost::reference_wrapper<T> provides an implicit -conversion to T &. This usually allows the function templates to -work on references unmodified. - - --boost::reference_wrapper<T> is both CopyConstructible and -Assignable (ordinary references are not Assignable). - - --The expression boost::ref(x) returns a boost::reference_wrapper<X>(x) -where X is the type of x. Similarly, boost::cref(x) -returns a boost::reference_wrapper<X const>(x). - - -The expression boost::is_reference_wrapper<T>::value is -true if T is a -reference_wrapper, and false otherwise. - - The type-expression boost::unwrap_reference<T>::type -is T::type if T is a -reference_wrapper, T otherwise. - - Interface- -Synopsis- -+
Purpose++ The header boost/ref.hpp defines the class + template boost::reference_wrapper<T>, the two functions boost::ref + and boost::cref that return instances of boost::reference_wrapper<T>, + and the two traits classes boost::is_reference_wrapper<T> and boost::unwrap_reference<T>. + ++ The purpose of boost::reference_wrapper<T> is to contain a + reference to an object of type T. It is primarily used to "feed" + references to function templates (algorithms) that take their parameter by + value. + ++ To support this usage, boost::reference_wrapper<T> provides an + implicit conversion to T &. This usually allows the function + templates to work on references unmodified. + ++ boost::reference_wrapper<T> is both CopyConstructible and Assignable + (ordinary references are not Assignable). + ++ The expression boost::ref(x) returns a boost::reference_wrapper<X>(x) + where X is the type of x. Similarly, boost::cref(x) returns + a boost::reference_wrapper<X const>(x). + ++ The expression boost::is_reference_wrapper<T>::value is true + if T is a reference_wrapper, and false + otherwise. + ++ The type-expression boost::unwrap_reference<T>::type is T::type + if T is a reference_wrapper, T otherwise. + +Interface+Synopsis+
namespace boost
{
template<class T> class reference_wrapper;
@@ -85,10 +79,8 @@ namespace boost
template<class T> class unwrap_reference<T const>;
}
-
-reference_wrapper- -+ | |||||||||