1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Chapter 1. Boost.LocalFunction 1.0.0</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.LocalFunction 1.0.0"> 8<link rel="next" href="boost_localfunction/getting_started.html" title="Getting Started"> 9</head> 10<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 11<table cellpadding="2" width="100%"><tr> 12<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td> 13<td align="center"><a href="../../../../index.html">Home</a></td> 14<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> 15<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 16<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 17<td align="center"><a href="../../../../more/index.htm">More</a></td> 18</tr></table> 19<hr> 20<div class="spirit-nav"><a accesskey="n" href="boost_localfunction/getting_started.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a></div> 21<div class="chapter"> 22<div class="titlepage"><div> 23<div><h2 class="title"> 24<a name="boost_localfunction"></a>Chapter 1. Boost.LocalFunction 1.0.0</h2></div> 25<div><div class="author"><h3 class="author"> 26<span class="firstname">Lorenzo</span> <span class="surname">Caminiti <code class="email"><<a class="email" href="mailto:lorcaminiti@gmail.com">lorcaminiti@gmail.com</a>></code></span> 27</h3></div></div> 28<div><p class="copyright">Copyright © 2009-2012 Lorenzo 29 Caminiti</p></div> 30<div><div class="legalnotice"> 31<a name="boost_localfunction.legal"></a><p> 32 Distributed under the Boost Software License, Version 1.0 (see accompanying 33 file LICENSE_1_0.txt or a copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) 34 </p> 35</div></div> 36</div></div> 37<div class="toc"> 38<p><b>Table of Contents</b></p> 39<dl class="toc"> 40<dt><span class="section"><a href="index.html#boost_localfunction.introduction">Introduction</a></span></dt> 41<dt><span class="section"><a href="boost_localfunction/getting_started.html">Getting Started</a></span></dt> 42<dd><dl> 43<dt><span class="section"><a href="boost_localfunction/getting_started.html#boost_localfunction.getting_started.this_documentation">This 44 Documentation</a></span></dt> 45<dt><span class="section"><a href="boost_localfunction/getting_started.html#boost_localfunction.getting_started.compilers_and_platforms">Compilers 46 and Platforms</a></span></dt> 47<dt><span class="section"><a href="boost_localfunction/getting_started.html#boost_localfunction.getting_started.installation">Installation</a></span></dt> 48</dl></dd> 49<dt><span class="section"><a href="boost_localfunction/tutorial.html">Tutorial</a></span></dt> 50<dd><dl> 51<dt><span class="section"><a href="boost_localfunction/tutorial.html#boost_localfunction.tutorial.local_functions">Local Functions</a></span></dt> 52<dt><span class="section"><a href="boost_localfunction/tutorial.html#boost_localfunction.tutorial.Binding">Binding Variables</a></span></dt> 53<dt><span class="section"><a href="boost_localfunction/tutorial.html#boost_localfunction.tutorial.binding_the_object__this_">Binding 54 the Object <code class="computeroutput"><span class="keyword">this</span></code></a></span></dt> 55<dt><span class="section"><a href="boost_localfunction/tutorial.html#boost_localfunction.tutorial.templates">Templates</a></span></dt> 56</dl></dd> 57<dt><span class="section"><a href="boost_localfunction/advanced_topics.html">Advanced Topics</a></span></dt> 58<dd><dl> 59<dt><span class="section"><a href="boost_localfunction/advanced_topics.html#boost_localfunction.advanced_topics.default_parameters">Default 60 Parameters</a></span></dt> 61<dt><span class="section"><a href="boost_localfunction/advanced_topics.html#boost_localfunction.advanced_topics.commas_and_symbols_in_macros">Commas 62 and Symbols in Macros</a></span></dt> 63<dt><span class="section"><a href="boost_localfunction/advanced_topics.html#boost_localfunction.advanced_topics.assignments_and_returns">Assignments 64 and Returns</a></span></dt> 65<dt><span class="section"><a href="boost_localfunction/advanced_topics.html#boost_localfunction.advanced_topics.nesting">Nesting</a></span></dt> 66<dt><span class="section"><a href="boost_localfunction/advanced_topics.html#boost_localfunction.advanced_topics.accessing_types__concepts__etc_">Accessing 67 Types (concepts, etc)</a></span></dt> 68<dt><span class="section"><a href="boost_localfunction/advanced_topics.html#boost_localfunction.advanced_topics.specifying_types__no_boost_typeof_">Specifying 69 Types (no Boost.Typeof)</a></span></dt> 70<dt><span class="section"><a href="boost_localfunction/advanced_topics.html#boost_localfunction.advanced_topics.inlining">Inlining</a></span></dt> 71<dt><span class="section"><a href="boost_localfunction/advanced_topics.html#boost_localfunction.advanced_topics.recursion">Recursion</a></span></dt> 72<dt><span class="section"><a href="boost_localfunction/advanced_topics.html#boost_localfunction.advanced_topics.overloading">Overloading</a></span></dt> 73<dt><span class="section"><a href="boost_localfunction/advanced_topics.html#boost_localfunction.advanced_topics.exception_specifications">Exception 74 Specifications</a></span></dt> 75<dt><span class="section"><a href="boost_localfunction/advanced_topics.html#boost_localfunction.advanced_topics.storage_classifiers">Storage 76 Classifiers</a></span></dt> 77<dt><span class="section"><a href="boost_localfunction/advanced_topics.html#boost_localfunction.advanced_topics.same_line_expansions">Same 78 Line Expansions</a></span></dt> 79<dt><span class="section"><a href="boost_localfunction/advanced_topics.html#boost_localfunction.advanced_topics.limitations__operators__etc_">Limitations 80 (operators, etc)</a></span></dt> 81</dl></dd> 82<dt><span class="section"><a href="boost_localfunction/examples.html">Examples</a></span></dt> 83<dd><dl> 84<dt><span class="section"><a href="boost_localfunction/examples.html#boost_localfunction.examples.gcc_lambdas__without_c__11_">GCC 85 Lambdas (without C++11)</a></span></dt> 86<dt><span class="section"><a href="boost_localfunction/examples.html#boost_localfunction.examples.constant_blocks">Constant 87 Blocks</a></span></dt> 88<dt><span class="section"><a href="boost_localfunction/examples.html#boost_localfunction.examples.scope_exits">Scope Exits</a></span></dt> 89<dt><span class="section"><a href="boost_localfunction/examples.html#boost_localfunction.examples.boost_phoenix_functions">Boost.Phoenix 90 Functions</a></span></dt> 91<dt><span class="section"><a href="boost_localfunction/examples.html#boost_localfunction.examples.closures">Closures</a></span></dt> 92<dt><span class="section"><a href="boost_localfunction/examples.html#boost_localfunction.examples.gcc_nested_functions">GCC 93 Nested Functions</a></span></dt> 94<dt><span class="section"><a href="boost_localfunction/examples.html#boost_localfunction.examples.n_papers">N-Papers</a></span></dt> 95</dl></dd> 96<dt><span class="section"><a href="boost_localfunction/alternatives.html">Annex: Alternatives</a></span></dt> 97<dt><span class="section"><a href="boost_localfunction/no_variadic_macros.html">Annex: No Variadic 98 Macros</a></span></dt> 99<dt><span class="section"><a href="boost_localfunction/implementation.html">Annex: Implementation</a></span></dt> 100<dt><span class="section"><a href="reference.html">Reference</a></span></dt> 101<dt><span class="section"><a href="boost_localfunction/release_notes.html">Release Notes</a></span></dt> 102<dt><span class="section"><a href="boost_localfunction/bibliography.html">Bibliography</a></span></dt> 103<dt><span class="section"><a href="boost_localfunction/acknowledgments.html">Acknowledgments</a></span></dt> 104</dl> 105</div> 106<p> 107 This library allows to program functions locally, within other functions, and 108 directly within the scope where they are needed. 109 </p> 110<div class="section"> 111<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 112<a name="boost_localfunction.introduction"></a><a class="link" href="index.html#boost_localfunction.introduction" title="Introduction">Introduction</a> 113</h2></div></div></div> 114<p> 115 <span class="emphasis"><em>Local functions</em></span> (a.k.a., <a href="http://en.wikipedia.org/wiki/Nested_function" target="_top"><span class="emphasis"><em>nested 116 functions</em></span></a>) are a form of <span class="emphasis"><em>information hiding</em></span> 117 and they are useful for dividing procedural tasks into subtasks which are only 118 meaningful locally, avoiding cluttering other parts of the program with functions, 119 variables, etc unrelated to those parts. Therefore, local functions complement 120 other structuring possibilities such as namespaces and classes. Local functions 121 are a feature of many programming languages, notably <a href="http://en.wikipedia.org/wiki/Nested_function#An_example" target="_top">Pascal</a> 122 and <a href="http://en.wikipedia.org/wiki/Nesting_(computing)#In_programming" target="_top">Ada</a>, 123 yet lacking from <a href="http://www.open-std.org/JTC1/SC22/WG21/docs/standards" target="_top">C++03</a> 124 (see also <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2511.html" target="_top">[N2511]</a>). 125 </p> 126<p> 127 Using <a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++11 128 lambda functions</a>, it is possible to implement local functions by naming 129 lambda functions assigning them to local variables. For example (see also 130 <a href="../../example/add_cxx11_lambda.cpp" target="_top"><code class="literal">add_cxx11_lambda.cpp</code></a>): 131 </p> 132<p> 133</p> 134<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="keyword">void</span><span class="special">)</span> <span class="special">{</span> <span class="comment">// Some local scope.</span> 135 <span class="keyword">int</span> <span class="identifier">sum</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">factor</span> <span class="special">=</span> <span class="number">10</span><span class="special">;</span> <span class="comment">// Variables in scope to bind.</span> 136 137 <span class="keyword">auto</span> <span class="identifier">add</span> <span class="special">=</span> <span class="special">[</span><span class="identifier">factor</span><span class="special">,</span> <span class="special">&</span><span class="identifier">sum</span><span class="special">](</span><span class="keyword">int</span> <span class="identifier">num</span><span class="special">)</span> <span class="special">{</span> <span class="comment">// C++11 only.</span> 138 <span class="identifier">sum</span> <span class="special">+=</span> <span class="identifier">factor</span> <span class="special">*</span> <span class="identifier">num</span><span class="special">;</span> 139 <span class="special">};</span> 140 141 <span class="identifier">add</span><span class="special">(</span><span class="number">1</span><span class="special">);</span> <span class="comment">// Call the lambda.</span> 142 <span class="keyword">int</span> <span class="identifier">nums</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span><span class="number">2</span><span class="special">,</span> <span class="number">3</span><span class="special">};</span> 143 <span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">nums</span><span class="special">,</span> <span class="identifier">nums</span> <span class="special">+</span> <span class="number">2</span><span class="special">,</span> <span class="identifier">add</span><span class="special">);</span> <span class="comment">// Pass it to an algorithm.</span> 144 145 <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">sum</span> <span class="special">==</span> <span class="number">60</span><span class="special">);</span> <span class="comment">// Assert final summation value.</span> 146 <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">report_errors</span><span class="special">();</span> 147<span class="special">}</span> 148</pre> 149<p> 150 </p> 151<p> 152 This library allows to program local functions portably between <a href="http://www.open-std.org/JTC1/SC22/WG21/docs/standards" target="_top">C++03</a> 153 and <a href="http://www.open-std.org/JTC1/SC22/WG21/" target="_top">C++11</a> (and 154 with performances comparable to lambda functions on <a href="http://www.open-std.org/JTC1/SC22/WG21/" target="_top">C++11</a> 155 compilers). For example (see also <a href="../../test/add.cpp" target="_top"><code class="literal">add.cpp</code></a>): 156 </p> 157<p> 158</p> 159<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="keyword">void</span><span class="special">)</span> <span class="special">{</span> <span class="comment">// Some local scope.</span> 160 <span class="keyword">int</span> <span class="identifier">sum</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">factor</span> <span class="special">=</span> <span class="number">10</span><span class="special">;</span> <span class="comment">// Variables in scope to bind.</span> 161 162 <span class="keyword">void</span> <span class="identifier">BOOST_LOCAL_FUNCTION</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">bind</span> <span class="identifier">factor</span><span class="special">,</span> <span class="identifier">bind</span><span class="special">&</span> <span class="identifier">sum</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">num</span><span class="special">)</span> <span class="special">{</span> 163 <span class="identifier">sum</span> <span class="special">+=</span> <span class="identifier">factor</span> <span class="special">*</span> <span class="identifier">num</span><span class="special">;</span> 164 <span class="special">}</span> <span class="identifier">BOOST_LOCAL_FUNCTION_NAME</span><span class="special">(</span><span class="identifier">add</span><span class="special">)</span> 165 166 <span class="identifier">add</span><span class="special">(</span><span class="number">1</span><span class="special">);</span> <span class="comment">// Call the local function.</span> 167 <span class="keyword">int</span> <span class="identifier">nums</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span><span class="number">2</span><span class="special">,</span> <span class="number">3</span><span class="special">};</span> 168 <span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">nums</span><span class="special">,</span> <span class="identifier">nums</span> <span class="special">+</span> <span class="number">2</span><span class="special">,</span> <span class="identifier">add</span><span class="special">);</span> <span class="comment">// Pass it to an algorithm.</span> 169 170 <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">sum</span> <span class="special">==</span> <span class="number">60</span><span class="special">);</span> <span class="comment">// Assert final summation value.</span> 171 <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">report_errors</span><span class="special">();</span> 172<span class="special">}</span> 173</pre> 174<p> 175 </p> 176<p> 177 This library supports the following features for local functions: 178 </p> 179<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 180<li class="listitem"> 181 Local functions can capture, or better <a href="http://en.wikipedia.org/wiki/Name_binding" target="_top"><span class="emphasis"><em>bind</em></span></a>, 182 any of the variables from the enclosing scope (a function together with 183 its captured variables is also called a <a href="http://en.wikipedia.org/wiki/Closure_(computer_science)" target="_top"><span class="emphasis"><em>closure</em></span></a>). 184 </li> 185<li class="listitem"> 186 The local function body is programmed using the usual C++ statement syntax 187 (as a consequence, compiler errors and debugging retain their usual meaning 188 and format). 189 </li> 190<li class="listitem"> 191 Local functions can be passed as template parameters so they can be conveniently 192 used with STL algorithms and other templates. <a href="#ftn.boost_localfunction.introduction.f0" class="footnote" name="boost_localfunction.introduction.f0"><sup class="footnote">[1]</sup></a> 193 </li> 194<li class="listitem"> 195 However, local functions must be specified within a declarative context 196 (e.g., at a point in the code where local variables can be declared) thus 197 they cannot be specified within expressions. <a href="#ftn.boost_localfunction.introduction.f1" class="footnote" name="boost_localfunction.introduction.f1"><sup class="footnote">[2]</sup></a> 198 </li> 199</ul></div> 200<p> 201 See the <a class="link" href="boost_localfunction/alternatives.html" title="Annex: Alternatives">Alternatives</a> 202 section for a comparison between this library, <a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++11 203 lambda functions</a>, <a href="http://www.boost.org/libs/phoenix" target="_top">Boost.Phoenix</a>, 204 and other C++ techniques that implement features related to local functions. 205 </p> 206</div> 207<div class="footnotes"> 208<br><hr style="width:100; text-align:left;margin-left: 0"> 209<div id="ftn.boost_localfunction.introduction.f0" class="footnote"><p><a href="#boost_localfunction.introduction.f0" class="para"><sup class="para">[1] </sup></a> 210 This is a strength with respect to <a href="http://www.open-std.org/JTC1/SC22/WG21/docs/standards" target="_top">C++03</a> 211 functors implemented using local classes which cannot be passed as template 212 parameters (see <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2657.htm" target="_top">[N2657]</a> 213 and the <a class="link" href="boost_localfunction/alternatives.html" title="Annex: Alternatives">Alternatives</a> 214 section). 215 </p></div> 216<div id="ftn.boost_localfunction.introduction.f1" class="footnote"><p><a href="#boost_localfunction.introduction.f1" class="para"><sup class="para">[2] </sup></a> 217 This is a weakness with respect to <a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++11 218 lambda functions</a> which can instead be specified also within expressions 219 (see the <a class="link" href="boost_localfunction/alternatives.html" title="Annex: Alternatives">Alternatives</a> 220 section). 221 </p></div> 222</div> 223</div> 224<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 225<td align="left"><p><small>Last revised: August 11, 2020 at 15:00:10 GMT</small></p></td> 226<td align="right"><div class="copyright-footer"></div></td> 227</tr></table> 228<hr> 229<div class="spirit-nav"><a accesskey="n" href="boost_localfunction/getting_started.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a></div> 230</body> 231</html> 232
