|
|
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. 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:
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, 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.
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.
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.
Yes, if you #define BOOST_MEM_FN_ENABLE_STDCALL.
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. In addition, it is possible for the default calling convention to be __stdcall, in which case enabling __stdcall support will result in duplicate definitions.
namespace boost
{
template<class T> T * get_pointer(T * p);
template<class R, class T> unspecified-1 mem_fn(R (T::*pmf) ());
template<class R, class T> unspecified-2 mem_fn(R (T::*pmf) () const);
template<class R, class T> unspecified-2-1 mem_fn(R T::*pm);
template<class R, class T, class A1> unspecified-3 mem_fn(R (T::*pmf) (A1));
template<class R, class T, class A1> unspecified-4 mem_fn(R (T::*pmf) (A1) const);
template<class R, class T, class A1, class A2> unspecified-5 mem_fn(R (T::*pmf) (A1, A2));
template<class R, class T, class A1, class A2> unspecified-6 mem_fn(R (T::*pmf) (A1, A2) const);
// implementation defined number of additional overloads for more arguments
}
All unspecified-N types mentioned in the Synopsis are CopyConstructible and Assignable. Their copy constructors and assignment operators do not throw exceptions. unspecified-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.) unspecified-2-1::result_type is defined as R.
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) is equivalent to t.*pm when t is of type T [const] or derived, get_pointer(t)->*pm 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. Borland VCL components use __fastcall. UDK, the component model of OpenOffice.org, uses __cdecl.
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>.
To use mem_fn with __fastcall member functions, #define the macro BOOST_MEM_FN_ENABLE_FASTCALL before including <boost/mem_fn.hpp>.
To use mem_fn with __cdecl member functions, #define the macro BOOST_MEM_FN_ENABLE_CDECL before including <boost/mem_fn.hpp>.
It is best to define these macros in the project options, via -D on the command line, or as the first line in the translation unit (.cpp file) where mem_fn is used. Not following this rule can lead to obscure errors when a header includes mem_fn.hpp before the macro has been defined.
[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.
Daniel Boelzle pointed out that UDK uses __cdecl.
Copyright © 2001, 2002 by Peter Dimov and Multi Media Ltd. Copyright
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.