Planet

navi

home

PPS

about

screenshots

download

development

forum

Context Navigation

source: downloads/boost_1_33_1/libs/bind/mem_fn.html @ 13

Last change on this file since 13 was 12, checked in by landauf, 17 years ago
added boost
File size: 17.3 KB

Line
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2	<html>
3	<head>
4	<title>Boost: mem_fn.hpp documentation</title>
5	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
6	</head>
7	<body bgcolor="white" style="MARGIN-LEFT: 5%; MARGIN-RIGHT: 5%">
8	<table border="0" width="100%">
9	<tr>
10	<td width="277">
11	<img src="../../boost.png" alt="boost.png (6897 bytes)" width="277" height="86">
12	</td>
13	<td align="center">
14	<h1>mem_fn.hpp</h1>
15	</td>
16	</tr>
17	<tr>
18	<td colspan="2" height="64"> </td>
19	</tr>
20	</table>
21	<h2>Contents</h2>
22	<h3 style="MARGIN-LEFT: 20pt"><a href="#Purpose">Purpose</a></h3>
23	<h3 style="MARGIN-LEFT: 20pt"><a href="#FAQ">Frequently Asked Questions</a></h3>
24	<h4 style="MARGIN-LEFT: 40pt"><a href="#Q1">Can <b>mem_fn</b> be used instead of the
25	standard <b>std::mem_fun[_ref]</b> adaptors?</a></h4>
26	<h4 style="MARGIN-LEFT: 40pt"><a href="#Q2">Should I replace every occurence of <b>std::mem_fun[_ref]</b>
27	with <b>mem_fn</b> in my existing code?</a></h4>
28	<h4 style="MARGIN-LEFT: 40pt"><a href="#Q3">Does <b>mem_fn</b> work with COM methods?</a></h4>
29	<h4 style="MARGIN-LEFT: 40pt"><a href="#Q4">Why isn't BOOST_MEM_FN_ENABLE_STDCALL
30	defined automatically?</a></h4>
31	<h3 style="MARGIN-LEFT: 20pt"><a href="#Interface">Interface</a></h3>
32	<h4 style="MARGIN-LEFT: 40pt"><a href="#Synopsis">Synopsis</a></h4>
33	<h4 style="MARGIN-LEFT: 40pt"><a href="#CommonRequirements">Common requirements</a></h4>
34	<h4 style="MARGIN-LEFT: 40pt"><a href="#get_pointer">get_pointer</a></h4>
35	<h4 style="MARGIN-LEFT: 40pt"><a href="#mem_fn">mem_fn</a></h4>
36	<h3 style="MARGIN-LEFT: 20pt"><a href="#Implementation">Implementation</a></h3>
37	<h4 style="MARGIN-LEFT: 40pt"><a href="#Files">Files</a></h4>
38	<h4 style="MARGIN-LEFT: 40pt"><a href="#Dependencies">Dependencies</a></h4>
39	<h4 style="MARGIN-LEFT: 40pt"><a href="#NumberOfArguments">Number of Arguments</a></h4>
40	<h4 style="MARGIN-LEFT: 40pt"><a href="#stdcall">"__stdcall", "__cdecl" and
41	"__fastcall" Support</a></h4>
42	<h3 style="MARGIN-LEFT: 20pt"><a href="#Acknowledgements">Acknowledgements</a></h3>
43	<h2><a name="Purpose">Purpose</a></h2>
44	<p>
45	<b>boost::mem_fn</b> is a generalization of the standard functions <b>std::mem_fun</b>
46	and <b>std::mem_fun_ref</b>. It supports member function pointers with more
47	than one argument, and the returned function object can take a pointer, a
48	reference, or a smart pointer to an object instance as its first argument. <STRONG>mem_fn</STRONG>
49	also supports pointers to data members by treating them as functions taking no
50	arguments and returning a (const) reference to the member.
51	</p>
52	<p>
53	The purpose of <b>mem_fn</b> is twofold. First, it allows users to invoke a
54	member function on a container with the familiar
55	</p>
56	<pre>
57	std::for_each(v.begin(), v.end(), boost::mem_fn(&Shape::draw));
58	</pre>
59	<p>
60	syntax, even when the container stores smart pointers.
61	</p>
62	<p>
63	Second, it can be used as a building block by library developers that want to
64	treat a pointer to member function as a function object. A library might define
65	an enhanced <b>for_each</b> algorithm with an overload of the form:
66	</p>
67	<pre>
68	template<class It, class R, class T> void for_each(It first, It last, R (T::*pmf) ())
69	{
70	std::for_each(first, last, boost::mem_fn(pmf));
71	}
72	</pre>
73	<p>
74	that will allow the convenient syntax:
75	</p>
76	<pre>
77	for_each(v.begin(), v.end(), &Shape::draw);
78	</pre>
79	<p>
80	When documenting the feature, the library author will simply state:
81	</p>
82	<h4 style="MARGIN-LEFT: 20pt">template<class It, class R, class T> void
83	for_each(It first, It last, R (T::*pmf) ());</h4>
84	<p style="MARGIN-LEFT: 20pt">
85	<b>Effects:</b> equivalent to std::for_each(first, last, boost::mem_fn(pmf));
86	</p>
87	<p>
88	where <b>boost::mem_fn</b> can be a link to this page. See <a href="bind.html">the
89	documentation of <b>bind</b></a> for an example.
90	</p>
91	<p>
92	<b>mem_fn</b> takes one argument, a pointer to a member, and returns a function
93	object suitable for use with standard or user-defined algorithms:
94	</p>
95	<pre>
96	struct X
97	{
98	void f();
99	};
100
101	void g(std::vector<X> & v)
102	{
103	std::for_each(v.begin(), v.end(), boost::mem_fn(&X::f));
104	};
105
106	void h(std::vector<X *> const & v)
107	{
108	std::for_each(v.begin(), v.end(), boost::mem_fn(&X::f));
109	};
110
111	void k(std::vector<boost::shared_ptr<X> > const & v)
112	{
113	std::for_each(v.begin(), v.end(), boost::mem_fn(&X::f));
114	};
115	</pre>
116	<p>
117	The returned function object takes the same arguments as the input member
118	function plus a "flexible" first argument that represents the object instance.
119	</p>
120	<p>
121	When the function object is invoked with a first argument <b>x</b> that is
122	neither a pointer nor a reference to the appropriate class (<b>X</b> in the
123	example above), it uses <tt>get_pointer(x)</tt> to obtain a pointer from <b>x</b>.
124	Library authors can "register" their smart pointer classes by supplying an
125	appropriate <b>get_pointer</b> overload, allowing <b>mem_fn</b> to recognize
126	and support them.
127	</p>
128	<p>
129	[Note: <b>get_pointer</b> is not restricted to return a pointer. Any object
130	that can be used in a member function call expression <tt>(x->*pmf)(...)</tt>
131	will work.]
132	</p>
133	<p>
134	[Note: the library uses an unqualified call to <b>get_pointer</b>. Therefore,
135	it will find, through argument-dependent lookup, <b>get_pointer</b> overloads
136	that are defined in the same namespace as the corresponding smart pointer
137	class, in addition to any <b>boost::get_pointer</b> overloads.]
138	</p>
139	<p>
140	All function objects returned by <b>mem_fn</b> expose a <b>result_type</b> typedef
141	that represents the return type of the member function. For data members, <STRONG>result_type</STRONG>
142	is defined as the type of the member.
143	</p>
144	<h2><a name="FAQ">Frequently Asked Questions</a></h2>
145	<h3><a name="Q1">Can <b>mem_fn</b> be used instead of the standard <b>std::mem_fun[_ref]</b>
146	adaptors?</a></h3>
147	<p>
148	Yes. For simple uses, <b>mem_fn</b> provides additional functionality that the
149	standard adaptors do not. Complicated expressions that use <b>std::bind1st</b>, <b>std::bind2nd</b>
150	or <a href="../compose/index.htm"><b>Boost.Compose</b></a> along with the
151	standard adaptors can be rewritten using <a href="bind.html"><b>boost::bind</b></a>
152	that automatically takes advantage of <b>mem_fn</b>.
153	</p>
154	<h3><a name="Q2">Should I replace every occurence of <b>std::mem_fun[_ref]</b> with <b>mem_fn</b>
155	in my existing code?</a></h3>
156	<p>
157	No, unless you have good reasons to do so. <b>mem_fn</b> is not 100% compatible
158	with the standard adaptors, although it comes pretty close. In particular, <b>mem_fn</b>
159	does not return objects of type <b>std::[const_]mem_fun[1][_ref]_t</b>, as the
160	standard adaptors do, and it is not possible to fully describe the type of the
161	first argument using the standard <b>argument_type</b> and <b>first_argument_type</b>
162	nested typedefs. Libraries that need adaptable function objects in order to
163	function might not like <b>mem_fn</b>.
164	</p>
165	<h3><a name="Q3">Does <b>mem_fn</b> work with COM methods?</a></h3>
166	<p>
167	Yes, if you <a href="#stdcall">#define BOOST_MEM_FN_ENABLE_STDCALL</a>.
168	</p>
169	<h3><a name="Q4">Why isn't BOOST_MEM_FN_ENABLE_STDCALL defined automatically?</a></h3>
170	<p>
171	Non-portable extensions, in general, should default to
172	off to prevent vendor lock-in. Had BOOST_MEM_FN_ENABLE_STDCALL been defined
173	automatically, you could have accidentally taken advantage of
174	it without realizing that your code is, perhaps, no longer portable.
175	In addition, it is possible for the default
176	calling convention to be __stdcall, in which case enabling __stdcall support will
177	result in duplicate definitions.
178	</p>
179	<h2><a name="Interface">Interface</a></h2>
180	<h3><a name="Synopsis">Synopsis</a></h3>
181	<pre>
182	namespace boost
183	{
184
185	template<class T> T * <a href="#get_pointer_1">get_pointer</a>(T * p);
186
187	template<class R, class T> <i>unspecified-1</i> <a href="#mem_fn_1">mem_fn</a>(R (T::*pmf) ());
188
189	template<class R, class T> <i>unspecified-2</i> <a href="#mem_fn_2">mem_fn</a>(R (T::*pmf) () const);
190
191	template<class R, class T> <i>unspecified-2-1</i> <a href="#mem_fn_2_1">mem_fn</a>(R T::*pm);
192
193	template<class R, class T, class A1> <i>unspecified-3</i> <a href="#mem_fn_3">mem_fn</a>(R (T::*pmf) (A1));
194
195	template<class R, class T, class A1> <i>unspecified-4</i> <a href="#mem_fn_4">mem_fn</a>(R (T::*pmf) (A1) const);
196
197	template<class R, class T, class A1, class A2> <i>unspecified-5</i> <a href="#mem_fn_5">mem_fn</a>(R (T::*pmf) (A1, A2));
198
199	template<class R, class T, class A1, class A2> <i>unspecified-6</i> <a href="#mem_fn_6">mem_fn</a>(R (T::*pmf) (A1, A2) const);
200
201	// implementation defined number of additional overloads for more arguments
202
203	}
204	</pre>
205	<h3><a name="CommonRequirements">Common requirements</a></h3>
206	<p>
207	All <tt><i>unspecified-N</i></tt> types mentioned in the Synopsis are <b>CopyConstructible</b>
208	and <b>Assignable</b>. Their copy constructors and assignment operators do not
209	throw exceptions. <tt><i>unspecified-N</i>::result_type</tt> is defined as the
210	return type of the member function pointer passed as an argument to <b>mem_fn</b>
211	(<b>R</b> in the Synopsis.) <tt><i>unspecified-2-1</i>::result_type</tt> is
212	defined as <tt>R</tt>.
213	</p>
214	<h3><a name="get_pointer">get_pointer</a></h3>
215	<h4><a name="get_pointer_1">template<class T> T * get_pointer(T * p)</a></h4>
216	<blockquote>
217	<p>
218	<b>Returns:</b> <tt>p</tt>.
219	</p>
220	<p>
221	<b>Throws:</b> Nothing.
222	</p>
223	</blockquote>
224	<h3><a name="mem_fn">mem_fn</a></h3>
225	<h4><a name="mem_fn_1">template<class R, class T> <i>unspecified-1</i> mem_fn(R
226	(T::*pmf) ())</a></h4>
227	<blockquote>
228	<p>
229	<b>Returns:</b> a function object <i>f</i> such that the expression <tt><i>f(t)</i></tt>
230	is equivalent to <tt>(t.*pmf)()</tt> when <i>t</i> is an l-value of type <STRONG>T </STRONG>
231	or derived, <tt>(get_pointer(t)->*pmf)()</tt> otherwise.
232	</p>
233	<p>
234	<b>Throws:</b> Nothing.
235	</p>
236	</blockquote>
237	<h4><a name="mem_fn_2">template<class R, class T> <i>unspecified-2</i> mem_fn(R
238	(T::*pmf) () const)</a></h4>
239	<blockquote>
240	<p>
241	<b>Returns:</b> a function object <i>f</i> such that the expression <tt><i>f(t)</i></tt>
242	is equivalent to <tt>(t.*pmf)()</tt> when <i>t</i> is of type <STRONG>T</STRONG>
243	<EM>[const]<STRONG> </STRONG></EM>or derived, <tt>(get_pointer(t)->*pmf)()</tt>
244	otherwise.
245	</p>
246	<p>
247	<b>Throws:</b> Nothing.
248	</p>
249	</blockquote>
250	<h4><a name="mem_fn_2_1">template<class R, class T> <i>unspecified-2-1</i> mem_fn(R
251	T::*pm)</a></h4>
252	<blockquote>
253	<p>
254	<b>Returns:</b> a function object <i>f</i> such that the expression <tt><i>f(t)</i></tt>
255	is equivalent to <tt>t.*pm</tt> when <i>t</i> is of type <STRONG>T</STRONG> <EM>[const]<STRONG>
256	</STRONG></EM>or derived, <tt>get_pointer(t)->*pm</tt> otherwise.
257	</p>
258	<p>
259	<b>Throws:</b> Nothing.
260	</p>
261	</blockquote>
262	<h4><a name="mem_fn_3">template<class R, class T, class A1> <i>unspecified-3</i> mem_fn(R
263	(T::*pmf) (A1))</a></h4>
264	<blockquote>
265	<p>
266	<b>Returns:</b> a function object <i>f</i> such that the expression <tt><i>f(t, a1)</i></tt>
267	is equivalent to <tt>(t.*pmf)(a1)</tt> when <i>t</i> is an l-value of type <STRONG>T
268	</STRONG>or derived, <tt>(get_pointer(t)->*pmf)(a1)</tt> otherwise.
269	</p>
270	<p>
271	<b>Throws:</b> Nothing.
272	</p>
273	</blockquote>
274	<h4><a name="mem_fn_4">template<class R, class T, class A1> <i>unspecified-4</i> mem_fn(R
275	(T::*pmf) (A1) const)</a></h4>
276	<blockquote>
277	<p>
278	<b>Returns:</b> a function object <i>f</i> such that the expression <tt><i>f(t, a1)</i></tt>
279	is equivalent to <tt>(t.*pmf)(a1)</tt> when <i>t</i> is of type <STRONG>T</STRONG>
280	<EM>[const]<STRONG> </STRONG></EM>or derived, <tt>(get_pointer(t)->*pmf)(a1)</tt>
281	otherwise.
282	</p>
283	<p>
284	<b>Throws:</b> Nothing.
285	</p>
286	</blockquote>
287	<h4><a name="mem_fn_5">template<class R, class T, class A1, class A2> <i>unspecified-5</i>
288	mem_fn(R (T::*pmf) (A1, A2))</a></h4>
289	<blockquote>
290	<p>
291	<b>Returns:</b> a function object <i>f</i> such that the expression <tt><i>f(t, a1, a2)</i></tt>
292	is equivalent to <tt>(t.*pmf)(a1, a2)</tt> when <i>t</i> is an l-value of type <STRONG>
293	T</STRONG> or derived, <tt>(get_pointer(t)->*pmf)(a1, a2)</tt> otherwise.
294	</p>
295	<p>
296	<b>Throws:</b> Nothing.
297	</p>
298	</blockquote>
299	<h4><a name="mem_fn_6">template<class R, class T, class A1, class A2> <i>unspecified-6</i>
300	mem_fn(R (T::*pmf) (A1, A2) const)</a></h4>
301	<blockquote>
302	<p>
303	<b>Returns:</b> a function object <i>f</i> such that the expression <tt><i>f(t, a1, a2)</i></tt>
304	is equivalent to <tt>(t.*pmf)(a1, a2)</tt> when <i>t</i> is of type <STRONG>T</STRONG>
305	<EM>[const]</EM> or derived, <tt>(get_pointer(t)->*pmf)(a1, a2)</tt> otherwise.
306	</p>
307	<p>
308	<b>Throws:</b> Nothing.
309	</p>
310	</blockquote>
311	<h2><a name="Implementation">Implementation</a></h2>
312	<h3><a name="Files">Files</a></h3>
313	<ul>
314	<li>
315	<a href="../../boost/mem_fn.hpp">boost/mem_fn.hpp</a>
316	(main header)
317	<li>
318	<a href="../../boost/bind/mem_fn_cc.hpp">boost/bind/mem_fn_cc.hpp</a>
319	(used by mem_fn.hpp, do not include directly)
320	<li>
321	<a href="../../boost/bind/mem_fn_vw.hpp">boost/bind/mem_fn_vw.hpp</a>
322	(used by mem_fn.hpp, do not include directly)
323	<li>
324	<a href="../../boost/bind/mem_fn_template.hpp">boost/bind/mem_fn_template.hpp</a>
325	(used by mem_fn.hpp, do not include directly)
326	<li>
327	<a href="test/mem_fn_test.cpp">libs/bind/test/mem_fn_test.cpp</a>
328	(test)
329	<li>
330	<a href="test/mem_fn_derived_test.cpp">libs/bind/test/mem_fn_derived_test.cpp</a>
331	(test with derived objects)
332	<li>
333	<a href="test/mem_fn_fastcall_test.cpp">libs/bind/test/mem_fn_fastcall_test.cpp</a>
334	(test for __fastcall)
335	<li>
336	<a href="test/mem_fn_stdcall_test.cpp">libs/bind/test/mem_fn_stdcall_test.cpp</a>
337	(test for __stdcall)
338	<li>
339	<a href="test/mem_fn_void_test.cpp">libs/bind/test/mem_fn_void_test.cpp</a> (test
340	for void returns)</li>
341	</ul>
342	<h3><a name="Dependencies">Dependencies</a></h3>
343	<ul>
344	<li>
345	<a href="../config/config.htm">Boost.Config</a></li>
346	</ul>
347	<h3><a name="NumberOfArguments">Number of Arguments</a></h3>
348	<p>
349	This implementation supports member functions with up to eight arguments. This
350	is not an inherent limitation of the design, but an implementation detail.
351	</p>
352	<h3><a name="stdcall">"__stdcall", "__cdecl" and "__fastcall" Support</a></h3>
353	<p>
354	Some platforms allow several types of member functions that differ by their <b>calling
355	convention</b> (the rules by which the function is invoked: how are
356	arguments passed, how is the return value handled, and who cleans up the stack
357	- if any.)
358	</p>
359	<p>
360	For example, Windows API functions and COM interface member functions use a
361	calling convention known as <b>__stdcall</b>. Borland VCL components use <STRONG>__fastcall</STRONG>. UDK, the component model of
362	OpenOffice.org, uses <STRONG>__cdecl</STRONG>.
363	</p>
364	<p>
365	To use <b>mem_fn</b> with <b>__stdcall</b> member functions, <b>#define</b> the
366	macro <b>BOOST_MEM_FN_ENABLE_STDCALL</b> before including, directly or
367	indirectly, <b><boost/mem_fn.hpp></b>.
368	</p>
369	<P>To use <B>mem_fn</B> with <B>__fastcall</B> member functions, <B>#define</B> the
370	macro <B>BOOST_MEM_FN_ENABLE_FASTCALL</B> before
371	including <B><boost/mem_fn.hpp></B>.
372	</P>
373	<P>To use <B>mem_fn</B> with <B>__cdecl</B> member functions, <B>#define</B> the
374	macro <B>BOOST_MEM_FN_ENABLE_CDECL</B> before including
375	<B><boost/mem_fn.hpp></B>. </P>
376	<P><STRONG>It is best to define these macros in the project options, via -D
377	on the command line, or as the first line in the translation unit (.cpp file)
378	where mem_fn is used.</STRONG> Not following this rule can lead to obscure
379	errors when a header includes mem_fn.hpp before the macro has been defined.</P>
380	<P>[Note: this is a non-portable extension. It is not part of the interface.]
381	</P>
382	<p>
383	[Note: Some compilers provide only minimal support for the <b>__stdcall</b> keyword.]
384	</p>
385	<h2><a name="Acknowledgements">Acknowledgements</a></h2>
386	<p>
387	Rene Jager's initial suggestion of using traits classes to make <b>mem_fn</b> adapt
388	to user-defined smart pointers inspired the <b>get_pointer</b>-based design.
389	</p>
390	<p>
391	Numerous improvements were suggested during the formal review period by Richard
392	Crossley, Jens Maurer, Ed Brey, and others. Review manager was Darin Adler.
393	</p>
394	<p>
395	Steve Anichini pointed out that COM interfaces use <b>__stdcall</b>.
396	</p>
397	<p>
398	Dave Abrahams modified <b>bind</b> and <b>mem_fn</b> to support void returns on
399	deficient compilers.
400	</p>
401	<p>Daniel Boelzle pointed out that UDK uses <STRONG>__cdecl</STRONG>.<br>
402	<br>
403	<br>
404	<small>Copyright © 2001, 2002 by Peter Dimov and Multi Media Ltd. Copyright 2003-2005 Peter Dimov. Permission
405	to copy, use, modify, sell and distribute this document is granted provided
406	this copyright notice appears in all copies. This document is provided "as is"
407	without express or implied warranty, and with no claim as to its suitability
408	for any purpose.</small></p>
409	</body>
410	</html>

Note: See TracBrowser for help on using the repository browser.

Download in other formats: