Gitiles
Code Review Sign In
gerrit.named-data.net / ndn-cxx / 7aec02511f549132613b80473a4d38906bf8b74b / . / libs / functional / ptr_fun.html
blob: 0dc62b46342e14f5cc48adf5c45ad4ab74ceb6dc [file] [log] [blame]
Jeff Thompsona28eed82013-08-22 16:21:10 -0700[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
3<html>
4<head>
5 <meta http-equiv="Content-Language" content="en-us">
6 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
7
8 <title>Boost Function Object Adapter Library</title>
9</head>
10
11<body bgcolor="#FFFFFF" text="#000000">
12 <table border="1" bgcolor="#007F7F" cellpadding="2" summary="">
13 <tr>
14 <td bgcolor="#FFFFFF"><img src="../../boost.png" alt=
15 "boost.png (6897 bytes)" width="277" height="86"></td>
16
17 <td><a href="../../index.htm"><font face="Arial" color=
18 "#FFFFFF"><big>Home</big></font></a></td>
19
20 <td><a href="../libraries.htm"><font face="Arial" color=
21 "#FFFFFF"><big>Libraries</big></font></a></td>
22
23 <td><a href="http://www.boost.org/people/people.htm"><font face="Arial" color=
24 "#FFFFFF"><big>People</big></font></a></td>
25
26 <td><a href="http://www.boost.org/more/faq.htm"><font face="Arial" color=
27 "#FFFFFF"><big>FAQ</big></font></a></td>
28
29 <td><a href="../../more/index.htm"><font face="Arial" color=
30 "#FFFFFF"><big>More</big></font></a></td>
31 </tr>
32 </table>
33
34 <h1>Function Pointer Adapters</h1>
35
36 <p>The header <a href="../../boost/functional.hpp">functional.hpp</a>
37 provides enhanced versions of both the function pointer adapters from the
38 C++ Standard Library (&sect;20.3.7):</p>
39
40 <ul>
41 <li><tt>pointer_to_unary_function</tt></li>
42
43 <li><tt>pointer_to_binary_function</tt></li>
44 </ul>
45
46 <p>As well as the corresponding helper function template:</p>
47
48 <ul>
49 <li><tt>ptr_fun</tt></li>
50 </ul>
51
52 <p>However, you should not need to use the adapters in conjunction with the
53 adapters in this library due to our use of <a href=
54 "function_traits.html">function object traits</a>. You will however need to
55 use them if your implementation fails to work properly with our traits
56 classes (due to lack if partial specialisation), or if you wish to use a
57 function object adapter from a third party.</p>
58
59 <h3>Usage</h3>
60
61 <p>If you need to use these adapters, usage is identical to the standard
62 function pointer adapters. For example,</p>
63
64 <blockquote>
65 <pre>
66bool bad(std::string foo) { ... }
67...
68std::vector&lt;std::string&gt; c;
69...
70std::vector&lt;std::string&gt;::iterator it
71 = std::find_if(c.begin(), c.end(), std::not1(boost::ptr_fun(bad)));
72</pre>
73 </blockquote>
74
75 <p>Note however that this library contains enhanced <a href=
76 "negators.html">negators</a> that support function object traits, so the
77 line above could equally be written</p>
78
79 <blockquote>
80 <pre>
81std::vector&lt;std::string&gt;::iterator it
82 = std::find_if(c.begin(), c.end(), boost::not1(bad));
83</pre>
84 </blockquote>
85
86 <h3>Argument Types</h3>
87
88 <p>The standard defines <tt>pointer_to_unary_function</tt> like this
89 (&sect;20.3.8&nbsp;&para;2):</p>
90
91 <blockquote>
92 <pre>
93template &lt;class Arg, class Result&gt;
94class pointer_to_unary_function : public unary_function&lt;Arg, Result&gt; {
95public:
96 explicit pointer_to_unary_function(Result (* f)(<strong>Arg</strong>));
97 Result operator()(<strong>Arg</strong> x) const;
98};
99</pre>
100 </blockquote>
101
102 <p>Note that the argument to <tt>operator()</tt> is exactly the same type
103 as the argument to the wrapped function. If this is a value type, the
104 argument will be passed by value and copied twice.
105 <tt>pointer_to_binary_function</tt> has a similar problem.</p>
106
107 <p>However, if we were to try and eliminate this inefficiency by instead
108 declaring the argument as <tt>const&nbsp;Arg&amp;</tt>, then if Arg were a
109 reference type, we would have a reference to a reference, which is
110 currently illegal (but see <a href=
111 "http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/cwg_active.html#106">C++ core
112 language issue number 106)</a></p>
113
114 <p>So the way in which we want to declare the argument for
115 <tt>operator()</tt> depends on whether or not the wrapped function's
116 argument is a reference. If it is a reference, we want to declare it simply
117 as <tt>Arg</tt>; if it is a value we want to declare it as
118 <tt>const&nbsp;Arg&amp;</tt>.</p>
119
120 <p>The Boost <a href="../utility/call_traits.htm">call_traits</a> class
121 template contains a <tt>param_type</tt> typedef, which uses partial
122 specialisation to make precisely this decision. By declaring the
123 <tt>operator()</tt> as</p>
124
125 <blockquote>
126 <pre>
127Result operator()(typename call_traits&lt;Arg&gt;::param_type x) const
128</pre>
129 </blockquote>
130
131 <p>we achieve the desired result - we improve efficiency without generating
132 references to references.</p>
133
134 <h3>Limitations</h3>
135
136 <p>The call traits template used to realise this improvement relies on
137 partial specialisation, so this improvement is only available on compilers
138 that support that feature. With other compilers, the argument passed to the
139 function will always be passed by reference, thus generating the
140 possibility of references to references.</p>
141 <hr>
142
143 <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
144 "../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
145 height="31" width="88"></a></p>
146
147 <p>Revised
148 <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->02
149 December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38510" --></p>
150
151 <p><i>Copyright &copy; 2000 Cadenza New Zealand Ltd.</i></p>
152
153 <p><i>Distributed under the Boost Software License, Version 1.0. (See
154 accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
155 copy at <a href=
156 "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
157</body>
158</html>