1[/ 2 / Copyright (c) 2001, 2002 Peter Dimov and Multi Media Ltd. 3 / Copyright (c) 2003-2005 Peter Dimov 4 / 5 / Distributed under the Boost Software License, Version 1.0. (See 6 / accompanying file LICENSE_1_0.txt or copy at 7 / http://www.boost.org/LICENSE_1_0.txt) 8 /] 9 10[section:purpose Purpose] 11 12`boost::mem_fn` is a generalization of the standard functions `std::mem_fun` 13and `std::mem_fun_ref`. It supports member function pointers with more than 14one argument, and the returned function object can take a pointer, a 15reference, or a smart pointer to an object instance as its first argument. 16`mem_fn` also supports pointers to data members by treating them as functions 17taking no arguments and returning a (const) reference to the member. 18 19The purpose of `mem_fn` is twofold. First, it allows users to invoke a member 20function on a container with the familiar 21 22 std::for_each(v.begin(), v.end(), boost::mem_fn(&Shape::draw)); 23 24syntax, even when the container stores smart pointers. 25 26Second, it can be used as a building block by library developers that want to 27treat a pointer to member function as a function object. A library might 28define an enhanced `for_each` algorithm with an overload of the form: 29 30 template<class It, class R, class T> void for_each(It first, It last, R (T::*pmf) ()) 31 { 32 std::for_each(first, last, boost::mem_fn(pmf)); 33 } 34 35that will allow the convenient syntax: 36 37 for_each(v.begin(), v.end(), &Shape::draw); 38 39When documenting the feature, the library author will simply state: 40 41 template<class It, class R, class T> void for_each(It first, It last, R (T::*pmf) ()); 42 43* /Effects:/ Equivalent to `std::for_each(first, last, boost::mem_fn(pmf))`. 44 45where `boost::mem_fn` can be a link to this page. See the 46[@boost:/libs/bind/bind.html documentation of `bind`] for an example. 47 48`mem_fn` takes one argument, a pointer to a member, and returns a function 49object suitable for use with standard or user-defined algorithms: 50 51 struct X 52 { 53 void f(); 54 }; 55 56 void g(std::vector<X> & v) 57 { 58 std::for_each(v.begin(), v.end(), boost::mem_fn(&X::f)); 59 }; 60 61 void h(std::vector<X *> const & v) 62 { 63 std::for_each(v.begin(), v.end(), boost::mem_fn(&X::f)); 64 }; 65 66 void k(std::vector<boost::shared_ptr<X> > const & v) 67 { 68 std::for_each(v.begin(), v.end(), boost::mem_fn(&X::f)); 69 }; 70 71The returned function object takes the same arguments as the input member 72function plus a "flexible" first argument that represents the object instance. 73 74When the function object is invoked with a first argument `x` that is neither 75a pointer nor a reference to the appropriate class (`X` in the example above), 76it uses `get_pointer(x)` to obtain a pointer from `x`. Library authors can 77"register" their smart pointer classes by supplying an appropriate 78`get_pointer` overload, allowing `mem_fn` to recognize and support them. 79 80 81/[Note:/ `get_pointer` is not restricted to return a pointer. Any object that 82can be used in a member function call expression `(x->*pmf)(...)` will work./]/ 83 84/[Note:/ the library uses an unqualified call to `get_pointer`. Therefore, it 85will find, through argument-dependent lookup, `get_pointer` overloads that are 86defined in the same namespace as the corresponding smart pointer class, in 87addition to any `boost::get_pointer` overloads./]/ 88 89All function objects returned by `mem_fn` expose a `result_type` typedef that 90represents the return type of the member function. For data members, 91`result_type` is defined as the type of the member. 92 93[endsect] 94