]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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` | |
13 | and `std::mem_fun_ref`. It supports member function pointers with more than | |
14 | one argument, and the returned function object can take a pointer, a | |
15 | reference, 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 | |
17 | taking no arguments and returning a (const) reference to the member. | |
18 | ||
19 | The purpose of `mem_fn` is twofold. First, it allows users to invoke a member | |
20 | function on a container with the familiar | |
21 | ||
22 | std::for_each(v.begin(), v.end(), boost::mem_fn(&Shape::draw)); | |
23 | ||
24 | syntax, even when the container stores smart pointers. | |
25 | ||
26 | Second, it can be used as a building block by library developers that want to | |
27 | treat a pointer to member function as a function object. A library might | |
28 | define 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 | ||
35 | that will allow the convenient syntax: | |
36 | ||
37 | for_each(v.begin(), v.end(), &Shape::draw); | |
38 | ||
39 | When 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 | ||
45 | where `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 | |
49 | object 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 | ||
71 | The returned function object takes the same arguments as the input member | |
72 | function plus a "flexible" first argument that represents the object instance. | |
73 | ||
74 | When the function object is invoked with a first argument `x` that is neither | |
75 | a pointer nor a reference to the appropriate class (`X` in the example above), | |
76 | it 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 | |
82 | can 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 | |
85 | will find, through argument-dependent lookup, `get_pointer` overloads that are | |
86 | defined in the same namespace as the corresponding smart pointer class, in | |
87 | addition to any `boost::get_pointer` overloads./]/ | |
88 | ||
89 | All function objects returned by `mem_fn` expose a `result_type` typedef that | |
90 | represents the return type of the member function. For data members, | |
91 | `result_type` is defined as the type of the member. | |
92 | ||
93 | [endsect] |