libs/functional/negators.html

   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>
  74 bool bad(const Foo &amp;foo) { ... }
  75 ...
  76 std::vector&lt;Foo&gt; c;
  77 ...
  78 std::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>
  89 template &lt;class Predicate&gt;
  90   class unary_negate
  91     : public unary_function&lt;typename Predicate::argument_type,bool&gt; {
  92 public:
  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://www.open-std.org/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>
 124 bool 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>