libs/local_function/doc/html/index.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Chapter&#160;1.&#160;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&#160;1.&#160;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&#160;1.&#160;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">&lt;<a class="email" href="mailto:lorcaminiti@gmail.com">lorcaminiti@gmail.com</a>&gt;</code></span>
  27 </h3></div></div>
  28 <div><p class="copyright">Copyright &#169; 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">&amp;</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">&amp;</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: April 17, 2017 at 02:42:24 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>