1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Tutorial</title> 5<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../index.html" title="Chapter 1. Boost.Functional/OverloadedFunction 1.0.0"> 8<link rel="up" href="../index.html" title="Chapter 1. Boost.Functional/OverloadedFunction 1.0.0"> 9<link rel="prev" href="getting_started.html" title="Getting Started"> 10<link rel="next" href="../reference.html" title="Reference"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr> 14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td> 15<td align="center"><a href="../../../../../../index.html">Home</a></td> 16<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td> 17<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 18<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 19<td align="center"><a href="../../../../../../more/index.htm">More</a></td> 20</tr></table> 21<hr> 22<div class="spirit-nav"> 23<a accesskey="p" href="getting_started.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../reference.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 27<a name="boost_functional_overloadedfunction.tutorial"></a><a class="link" href="tutorial.html" title="Tutorial">Tutorial</a> 28</h2></div></div></div> 29<div class="toc"><dl class="toc"> 30<dt><span class="section"><a href="tutorial.html#boost_functional_overloadedfunction.tutorial.overloading">Overloading</a></span></dt> 31<dt><span class="section"><a href="tutorial.html#boost_functional_overloadedfunction.tutorial.without_function_types">Without 32 Function Types</a></span></dt> 33</dl></div> 34<p> 35 This section explains how to use this library. 36 </p> 37<div class="section"> 38<div class="titlepage"><div><div><h3 class="title"> 39<a name="boost_functional_overloadedfunction.tutorial.overloading"></a><a class="link" href="tutorial.html#boost_functional_overloadedfunction.tutorial.overloading" title="Overloading">Overloading</a> 40</h3></div></div></div> 41<p> 42 Consider the following functions which have distinct signatures: 43 </p> 44<p> 45</p> 46<pre class="programlisting"><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&</span> <span class="identifier">identity_s</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&</span> <span class="identifier">x</span><span class="special">)</span> <span class="comment">// Function (as pointer).</span> 47 <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span> 48 49<span class="keyword">int</span> <span class="identifier">identity_i_impl</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span> 50<span class="keyword">int</span> <span class="special">(&</span><span class="identifier">identity_i</span><span class="special">)(</span><span class="keyword">int</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">identity_i_impl</span><span class="special">;</span> <span class="comment">// Function reference.</span> 51 52<span class="keyword">double</span> <span class="identifier">identity_d_impl</span><span class="special">(</span><span class="keyword">double</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span> 53<span class="identifier">boost</span><span class="special">::</span><span class="identifier">function</span><span class="special"><</span><span class="keyword">double</span> <span class="special">(</span><span class="keyword">double</span><span class="special">)></span> <span class="identifier">identity_d</span> <span class="special">=</span> <span class="identifier">identity_d_impl</span><span class="special">;</span> <span class="comment">// Functor.</span> 54</pre> 55<p> 56 </p> 57<p> 58 This library header <code class="computeroutput">boost/functional/overloaded_function.hpp</code> 59 provides a <code class="computeroutput">boost::overloaded_function</code> 60 class template that creates a single overloaded function object that can 61 be used to call the specified functions instead of using the separate function 62 names (see also <a href="../../../test/functor.cpp" target="_top"><code class="literal">functor.cpp</code></a> 63 and <a href="../../../test/identity.hpp" target="_top"><code class="literal">identity.hpp</code></a>): 64 </p> 65<p> 66</p> 67<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">overloaded_function</span><span class="special"><</span> 68 <span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&)</span> 69 <span class="special">,</span> <span class="keyword">int</span> <span class="special">(</span><span class="keyword">int</span><span class="special">)</span> 70 <span class="special">,</span> <span class="keyword">double</span> <span class="special">(</span><span class="keyword">double</span><span class="special">)</span> 71<span class="special">></span> <span class="identifier">identity</span><span class="special">(</span><span class="identifier">identity_s</span><span class="special">,</span> <span class="identifier">identity_i</span><span class="special">,</span> <span class="identifier">identity_d</span><span class="special">);</span> 72 73<span class="comment">// All calls via single `identity` function.</span> 74<span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">identity</span><span class="special">(</span><span class="string">"abc"</span><span class="special">)</span> <span class="special">==</span> <span class="string">"abc"</span><span class="special">);</span> 75<span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">identity</span><span class="special">(</span><span class="number">123</span><span class="special">)</span> <span class="special">==</span> <span class="number">123</span><span class="special">);</span> 76<span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">identity</span><span class="special">(</span><span class="number">1.23</span><span class="special">)</span> <span class="special">==</span> <span class="number">1.23</span><span class="special">);</span> 77</pre> 78<p> 79 </p> 80<p> 81 Note how each function type is passed as a template parameter of <code class="computeroutput">boost::overloaded_function</code> using 82 the following syntax (this is <a href="http://www.boost.org/libs/function" target="_top">Boost.Function</a>'s 83 preferred syntax): 84 </p> 85<pre class="programlisting"><span class="emphasis"><em>result-type</em></span> <span class="special">(</span><span class="emphasis"><em>argument1-type</em></span><span class="special">,</span> <span class="emphasis"><em>argument2-type</em></span><span class="special">,</span> <span class="special">...)</span> 86</pre> 87<p> 88 Then the relative function pointers, function references, or <a href="http://en.wikipedia.org/wiki/Polymorphism_(computer_science)" target="_top">monomorphic 89 function</a> objects are passed to the <code class="computeroutput">boost::overloaded_function</code> 90 constructor matching the order of the specified template parameters. <a href="#ftn.boost_functional_overloadedfunction.tutorial.overloading.f0" class="footnote" name="boost_functional_overloadedfunction.tutorial.overloading.f0"><sup class="footnote">[2]</sup></a> In the above example, <code class="computeroutput"><span class="identifier">identity_s</span></code> 91 is passed as a function pointer (the function address is automatically taken 92 from the function name by the compiler), <code class="computeroutput"><span class="identifier">identity_i</span></code> 93 as a function reference, and <code class="computeroutput"><span class="identifier">identity_d</span></code> 94 as a function object. 95 </p> 96<p> 97 All specified function types must have distinct parameters from one another 98 (so the overloaded calls can be resolved by this library). <a href="#ftn.boost_functional_overloadedfunction.tutorial.overloading.f1" class="footnote" name="boost_functional_overloadedfunction.tutorial.overloading.f1"><sup class="footnote">[3]</sup></a> In order to create an overloaded function object, it is necessary 99 to specify at least two function types (because there is nothing to overload 100 between one or zero functions). 101 </p> 102</div> 103<div class="section"> 104<div class="titlepage"><div><div><h3 class="title"> 105<a name="boost_functional_overloadedfunction.tutorial.without_function_types"></a><a class="link" href="tutorial.html#boost_functional_overloadedfunction.tutorial.without_function_types" title="Without Function Types">Without 106 Function Types</a> 107</h3></div></div></div> 108<p> 109 For convenience, this library also provides the <code class="computeroutput">boost::make_overloaded_function</code> 110 function template which allows to create the overloaded function object without 111 explicitly specifying the function types. The function types are automatically 112 deduced from the specified functions and the appropriate <code class="computeroutput">boost::overloaded_function</code> 113 instantiation is returned by <code class="computeroutput">boost::make_overloaded_function</code>. 114 </p> 115<p> 116 The <code class="computeroutput">boost::make_overloaded_function</code> 117 function template can be useful when used together with <a href="http://www.boost.org/doc/libs/typeof" target="_top">Boost.Typeof</a>'s 118 <code class="computeroutput"><span class="identifier">BOOST_AUTO</span></code> (or C++11 <code class="computeroutput"><span class="keyword">auto</span></code>). For example (see also <a href="../../../test/make_decl.cpp" target="_top"><code class="literal">make_decl.cpp</code></a> 119 and <a href="../../../test/identity.hpp" target="_top"><code class="literal">identity.hpp</code></a>): 120 </p> 121<p> 122</p> 123<pre class="programlisting"><span class="identifier">BOOST_AUTO</span><span class="special">(</span><span class="identifier">identity</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_overloaded_function</span><span class="special">(</span> 124 <span class="identifier">identity_s</span><span class="special">,</span> <span class="identifier">identity_i</span><span class="special">,</span> <span class="identifier">identity_d</span><span class="special">));</span> 125 126<span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">identity</span><span class="special">(</span><span class="string">"abc"</span><span class="special">)</span> <span class="special">==</span> <span class="string">"abc"</span><span class="special">);</span> 127<span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">identity</span><span class="special">(</span><span class="number">123</span><span class="special">)</span> <span class="special">==</span> <span class="number">123</span><span class="special">);</span> 128<span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">identity</span><span class="special">(</span><span class="number">1.23</span><span class="special">)</span> <span class="special">==</span> <span class="number">1.23</span><span class="special">);</span> 129</pre> 130<p> 131 </p> 132<p> 133 Note how the overloaded function object <code class="computeroutput"><span class="identifier">identity</span></code> 134 has been created specifying only the functions <code class="computeroutput"><span class="identifier">identity_s</span></code>, 135 <code class="computeroutput"><span class="identifier">identity_i</span></code>, <code class="computeroutput"><span class="identifier">identity_d</span></code> and without specifying the function 136 types <code class="computeroutput"><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&</span> <span class="special">(</span><span class="keyword">const</span> 137 <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&)</span></code>, 138 <code class="computeroutput"><span class="keyword">int</span> <span class="special">(</span><span class="keyword">int</span><span class="special">)</span></code>, and 139 <code class="computeroutput"><span class="keyword">double</span> <span class="special">(</span><span class="keyword">double</span><span class="special">)</span></code> as 140 required instead by <code class="computeroutput">boost::overloaded_function</code>. 141 Therefore, <code class="computeroutput">boost::make_overloaded_function</code> 142 provides a more concise syntax in this context when compared with <code class="computeroutput">boost::overloaded_function</code>. 143 </p> 144<p> 145 Another case where <code class="computeroutput">boost::make_overloaded_function</code> 146 can be useful is when the overloaded function object is passed to a function 147 template which can hold the specific <code class="computeroutput">boost::overloaded_function</code> 148 type using a template parameter. For example (see also <a href="../../../test/make_call.cpp" target="_top"><code class="literal">make_call.cpp</code></a> 149 and <a href="../../../test/identity.hpp" target="_top"><code class="literal">identity.hpp</code></a>): 150 </p> 151<p> 152</p> 153<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">F</span><span class="special">></span> 154<span class="keyword">void</span> <span class="identifier">check</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">identity</span><span class="special">)</span> <span class="special">{</span> 155 <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">identity</span><span class="special">(</span><span class="string">"abc"</span><span class="special">)</span> <span class="special">==</span> <span class="string">"abc"</span><span class="special">);</span> 156 <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">identity</span><span class="special">(</span><span class="number">123</span><span class="special">)</span> <span class="special">==</span> <span class="number">123</span><span class="special">);</span> 157 <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">identity</span><span class="special">(</span><span class="number">1.23</span><span class="special">)</span> <span class="special">==</span> <span class="number">1.23</span><span class="special">);</span> 158<span class="special">}</span> 159</pre> 160<p> 161 </p> 162<p> 163</p> 164<pre class="programlisting"><span class="identifier">check</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_overloaded_function</span><span class="special">(</span><span class="identifier">identity_s</span><span class="special">,</span> <span class="identifier">identity_i</span><span class="special">,</span> <span class="identifier">identity_d</span><span class="special">));</span> 165</pre> 166<p> 167 </p> 168<p> 169 The library implementation of <code class="computeroutput">boost::make_overloaded_function</code> 170 uses <a href="http://www.boost.org/doc/libs/typeof" target="_top">Boost.Typeof</a> 171 to automatically deduce some of the function types. In order to compile code 172 in <a href="http://www.boost.org/doc/libs/typeof" target="_top">Boost.Typeof</a> 173 emulation mode, all types should be properly registered using <code class="computeroutput"><span class="identifier">BOOST_TYPEOF_REGISTER_TYPE</span></code> and <code class="computeroutput"><span class="identifier">BOOST_TYPEOF_REGISTER_TEMPLATE</span></code>, or appropriate 174 <a href="http://www.boost.org/doc/libs/typeof" target="_top">Boost.Typeof</a> headers 175 should be included (see <a href="http://www.boost.org/doc/libs/typeof" target="_top">Boost.Typeof</a> 176 for more information). For the above examples, it is sufficient to include 177 the <a href="http://www.boost.org/doc/libs/typeof" target="_top">Boost.Typeof</a> 178 header that registers <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code> 179 (this library does not require to register <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">function</span></code> 180 for <a href="http://www.boost.org/doc/libs/typeof" target="_top">Boost.Typeof</a> 181 emulation): 182 </p> 183<p> 184</p> 185<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">typeof</span><span class="special">/</span><span class="identifier">std</span><span class="special">/</span><span class="identifier">string</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> <span class="comment">// No need to register `boost::function`.</span> 186</pre> 187<p> 188 </p> 189</div> 190<div class="footnotes"> 191<br><hr style="width:100; text-align:left;margin-left: 0"> 192<div id="ftn.boost_functional_overloadedfunction.tutorial.overloading.f0" class="footnote"><p><a href="#boost_functional_overloadedfunction.tutorial.overloading.f0" class="para"><sup class="para">[2] </sup></a> 193 Function pointers are of the form <code class="literal"><span class="emphasis"><em>result-type </em></span></code><code class="computeroutput"><span class="special">(*)(</span></code><code class="literal"><span class="emphasis"><em>argument1-type</em></span></code><code class="computeroutput"><span class="special">,</span> <span class="special">...)</span></code> (the 194 C++ compiler is usually able to automatically promote a function name to 195 a function pointer in a context where a function pointer is expected even 196 if the function name is not prefixed by <code class="computeroutput"><span class="special">&</span></code>). 197 Function references are of the form <code class="literal"><span class="emphasis"><em>result-type </em></span></code><code class="computeroutput"><span class="special">(&)(</span></code><code class="literal"><span class="emphasis"><em>argument1-type</em></span></code><code class="computeroutput"><span class="special">,</span> <span class="special">...)</span></code>. 198 Function types are of the form <code class="literal"><span class="emphasis"><em>result-type </em></span></code><code class="computeroutput"><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>argument1-type</em></span></code><code class="computeroutput"><span class="special">,</span> <span class="special">...)</span></code> (note 199 how they lack of both <code class="computeroutput"><span class="special">*</span></code> and 200 <code class="computeroutput"><span class="special">&</span></code> when compared to function 201 pointers and function references). Finally, monomorphic function objects 202 are instances of classes with a non-template call operator of the form 203 <code class="literal"><span class="emphasis"><em>result-type </em></span></code><code class="computeroutput"><span class="keyword">operator</span><span class="special">()(</span></code><code class="literal"><span class="emphasis"><em>argument1-type</em></span></code><code class="computeroutput"><span class="special">,</span> <span class="special">...)</span></code>. 204 Unfortunately, it is not possible to support polymorphic function objects 205 (see <a href="http://lists.boost.org/Archives/boost/2012/03/191744.php" target="_top">http://lists.boost.org/Archives/boost/2012/03/191744.php</a>). 206 </p></div> 207<div id="ftn.boost_functional_overloadedfunction.tutorial.overloading.f1" class="footnote"><p><a href="#boost_functional_overloadedfunction.tutorial.overloading.f1" class="para"><sup class="para">[3] </sup></a> 208 Note that in C++ the function result type is not used for overload resolution 209 (to avoid making the overload resolution context dependent). Therefore, 210 at least one of the function parameters must be distinct for each specified 211 function type. 212 </p></div> 213</div> 214</div> 215<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 216<td align="left"></td> 217<td align="right"><div class="copyright-footer">Copyright © 2011, 2012 Lorenzo Caminiti<p> 218 Distributed under the Boost Software License, Version 1.0 (see accompanying 219 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) 220 </p> 221</div></td> 222</tr></table> 223<hr> 224<div class="spirit-nav"> 225<a accesskey="p" href="getting_started.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../reference.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 226</div> 227</body> 228</html> 229
