Gitiles
Code Review Sign In
gerrit.named-data.net / ndn-cxx / a28eed8ca42271ce9b4cbab94abd2bbe84f022f1 / . / libs / functional / negators.html
blob: 9d3175093bb2c91daab67543ca4b2cbe28beda5e [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>Negators</h1>
35
36 <p>The header <a href="../../boost/functional.hpp">functional.hpp</a>
37 provides enhanced versions of both the negator adapters from the C++
38 Standard Library (&sect;20.3.5):</p>
39
40 <ul>
41 <li><tt>unary_negate</tt></li>
42
43 <li><tt>binary_negate</tt></li>
44 </ul>
45
46 <p>As well as the corresponding helper functions</p>
47
48 <ul>
49 <li><tt>not1</tt></li>
50
51 <li><tt>not2</tt></li>
52 </ul>
53
54 <p>However, the negators in this library improve on the standard versions
55 in two ways:</p>
56
57 <ul>
58 <li>They use <a href="function_traits.html">function object traits</a> to
59 avoid the need for <tt>ptr_fun</tt> when negating a function rather than
60 an adaptable function object.</li>
61
62 <li>They use Boost <a href=
63 "../utility/call_traits.htm">call&nbsp;traits</a> to determine the best
64 way to declare their arguments and pass them through to the adapted
65 function (see <a href="#arguments">below</a>).</li>
66 </ul>
67
68 <h3>Usage</h3>
69
70 <p>Usage is identical to the standard negators. For example,</p>
71
72 <blockquote>
73 <pre>
74bool bad(const Foo &amp;foo) { ... }
75...
76std::vector&lt;Foo&gt; c;
77...
78std::find_if(c.begin(), c.end(), boost::not1(bad));
79</pre>
80 </blockquote>
81
82 <h3 id="arguments">Argument Types</h3>
83
84 <p>The C++ Standard (&sect;20.3.5) defines unary negate like this (binary
85 negate is similar):</p>
86
87 <blockquote>
88 <pre>
89template &lt;class Predicate&gt;
90 class unary_negate
91 : public unary_function&lt;typename Predicate::argument_type,bool&gt; {
92public:
93 explicit unary_negate(const Predicate&amp; pred);
94 bool operator()(<strong>const typename Predicate::argument_type&amp;</strong> x) const;
95};
96</pre>
97 </blockquote>
98
99 <p>Note that if the Predicate's <tt>argument_type</tt> is a reference, the
100 type of <tt>operator()</tt>'s argument would be a reference to a reference.
101 Currently this is illegal in C++ (but see the <a href=
102 "http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/cwg_active.html#106">C++
103 standard core language active issues list</a>).</p>
104
105 <p>However, if we instead defined <tt>operator()</tt> to accept Predicate's
106 argument_type unmodified, this would be needlessly inefficient if it were a
107 value type; the argument would be copied twice - once when calling
108 <tt>unary_negate</tt>'s <tt>operator()</tt>, and again when
109 <tt>operator()</tt> called the adapted function.</p>
110
111 <p>So how we want to declare the argument for <tt>operator()</tt> depends
112 on whether or not the Predicate's <tt>argument_type</tt> is a reference. If
113 it is a reference, we want to declare it simply as <tt>argument_type</tt>;
114 if it is a value we want to declare it as
115 <tt>const&nbsp;argument_type&amp;</tt>.</p>
116
117 <p>The Boost <a href="../utility/call_traits.htm">call_traits</a> class
118 template contains a <tt>param_type</tt> typedef, which uses partial
119 specialisation to make precisely this decision. If we were to declare
120 <tt>operator()</tt> as</p>
121
122 <blockquote>
123 <pre>
124bool operator()(typename call_traits&lt;typename Predicate::argument_type&gt;::param_type x) const
125</pre>
126 </blockquote>
127
128 <p>the desired result would be achieved - we would eliminate references to
129 references without loss of efficiency. In fact, the actual declaration is
130 slightly more complicated because of the use of function object traits, but
131 the effect remains the same.</p>
132
133 <h3>Limitations</h3>
134
135 <p>Both the function object traits and call traits used to realise these
136 improvements rely on partial specialisation, these improvements are only
137 available on compilers that support that feature. With other compilers, the
138 negators in this library behave very much like those in the Standard -
139 <tt>ptr_fun</tt> will be required to adapt functions, and references to
140 references will not be avoided.</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>