+ © Copyright Beman Dawes, 2001
-Distributed under the Boost Software License, Version 1.0. (See accompanying -file LICENSE_1_0.txt or copy -at www.boost.org/LICENSE_1_0.txt)
-- - \ No newline at end of file + +
|
+ |
+
+ 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.