| [/ |
| / 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] |