| Jeff Thompson | a28eed8 | 2013-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>Binders</h1> |
| 35 | |
| 36 | <p>The header <a href="../../boost/functional.hpp">functional.hpp</a> |
| 37 | provides enhanced versions of both the binder function object adapters from |
| 38 | the C++ Standard Library (§20.3.6):</p> |
| 39 | |
| 40 | <ul> |
| 41 | <li><tt>binder1st</tt></li> |
| 42 | |
| 43 | <li><tt>binder2nd</tt></li> |
| 44 | </ul> |
| 45 | |
| 46 | <p>As well as the corresponding helper functions</p> |
| 47 | |
| 48 | <ul> |
| 49 | <li><tt>bind1st</tt></li> |
| 50 | |
| 51 | <li><tt>bind2nd</tt></li> |
| 52 | </ul> |
| 53 | |
| 54 | <p>The key benefit of these adapters over those in the Standard Library is |
| 55 | they avoid the problem of <a href="#refref">references to |
| 56 | references.</a></p> |
| 57 | |
| 58 | <h3>Usage</h3> |
| 59 | |
| 60 | <p>Usage is identical to the standard binders. For example,</p> |
| 61 | |
| 62 | <blockquote> |
| 63 | <pre> |
| 64 | class Foo { |
| 65 | public: |
| 66 | void bar(std::ostream &); |
| 67 | // ... |
| 68 | }; |
| 69 | // ... |
| 70 | std::vector<Foo> c; |
| 71 | // ... |
| 72 | std::for_each(c.begin(), c.end(), |
| 73 | boost::bind2nd(boost::mem_fun_ref(&Foo::bar), std::cout)); |
| 74 | </pre> |
| 75 | </blockquote> |
| 76 | |
| 77 | <h3 id="refref">References to References</h3> |
| 78 | |
| 79 | <p>Consider the usage example above</p> |
| 80 | |
| 81 | <blockquote> |
| 82 | <pre> |
| 83 | class Foo { |
| 84 | public: |
| 85 | void bar(<strong>std::ostream &</strong>); |
| 86 | // ... |
| 87 | }; |
| 88 | // ... |
| 89 | std::for_each(c.begin(), c.end(), |
| 90 | boost::bind2nd(boost::mem_fun_ref(&Foo::bar), std::cout)); |
| 91 | </pre> |
| 92 | </blockquote> |
| 93 | |
| 94 | <p>If this had been written using <tt>std::bind2nd</tt> and |
| 95 | <tt>std::mem_fun_ref</tt>, it would be unlikely to compile.</p> |
| 96 | |
| 97 | <p>The problem arises because <tt>bar</tt> takes a reference argument. The |
| 98 | Standard defines <tt>std::mem_fun_ref</tt> such that it creates a function |
| 99 | object whose <tt>second_argument_type</tt> will be |
| 100 | <tt>std::ostream&</tt>.</p> |
| 101 | |
| 102 | <p>The call to <tt>bind2nd</tt> creates a <tt>binder2nd</tt> which the |
| 103 | Standard defines as follows:</p> |
| 104 | |
| 105 | <blockquote> |
| 106 | <pre> |
| 107 | template <class Operation> |
| 108 | class binder2nd |
| 109 | : public unary_function<typename Operation::first_argument_type, |
| 110 | typename Operation::result_type> { |
| 111 | ... |
| 112 | public: |
| 113 | binder2nd(const Operation& x, |
| 114 | <strong>const typename Operation::second_argument_type& y</strong>); |
| 115 | ... |
| 116 | </pre> |
| 117 | </blockquote> |
| 118 | |
| 119 | <p>Since our operation's <tt>second_argument_type</tt> is |
| 120 | <tt>std::ostream&</tt>, the type of <tt>y</tt> in the constructor would |
| 121 | be <tt>std::ostream&&</tt>. Since you cannot have a reference to a |
| 122 | reference, at this point we should get a compilation error because |
| 123 | references to references are illegal in C++ (but see <a href= |
| 124 | "http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/cwg_active.html#106">C++ |
| 125 | Standard core language active issues list</a>).</p> |
| 126 | |
| 127 | <p>The binders in this library avoid this problem by using the Boost |
| 128 | <tt><a href="../utility/call_traits.htm">call_traits</a></tt> |
| 129 | templates.</p> |
| 130 | |
| 131 | <p>Our constructor is declared</p> |
| 132 | |
| 133 | <blockquote> |
| 134 | <pre> |
| 135 | binder2nd(const Operation& x, |
| 136 | <strong>typename call_traits< |
| 137 | typename binary_traits<Operation>::second_argument_type |
| 138 | >::param_type y</strong>) |
| 139 | </pre> |
| 140 | </blockquote> |
| 141 | |
| 142 | <p>As a result, <tt>y</tt> has a type of <tt>std::ostream&</tt>, and |
| 143 | our example compiles.</p> |
| 144 | <hr> |
| 145 | |
| 146 | <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src= |
| 147 | "../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional" |
| 148 | height="31" width="88"></a></p> |
| 149 | |
| 150 | <p>Revised |
| 151 | <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->02 |
| 152 | December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38510" --></p> |
| 153 | |
| 154 | <p><i>Copyright © 2000 Cadenza New Zealand Ltd.</i></p> |
| 155 | |
| 156 | <p><i>Distributed under the Boost Software License, Version 1.0. (See |
| 157 | accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or |
| 158 | copy at <a href= |
| 159 | "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p> |
| 160 | </body> |
| 161 | </html> |