ceph/src/boost/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.78.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 <dd><dl>
 102 <dt><span class="section"><a href="reference.html#header.boost.local_function_hpp">Header &lt;boost/local_function.hpp&gt;</a></span></dt>
 103 <dt><span class="section"><a href="reference.html#header.boost.local_function.config_hpp">Header &lt;boost/local_function/config.hpp&gt;</a></span></dt>
 104 </dl></dd>
 105 <dt><span class="section"><a href="boost_localfunction/release_notes.html">Release Notes</a></span></dt>
 106 <dt><span class="section"><a href="boost_localfunction/bibliography.html">Bibliography</a></span></dt>
 107 <dt><span class="section"><a href="boost_localfunction/acknowledgments.html">Acknowledgments</a></span></dt>
 108 </dl>
 109 </div>
 110 <p>
 111     This library allows to program functions locally, within other functions, and
 112     directly within the scope where they are needed.
 113   </p>
 114 <div class="section">
 115 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 116 <a name="boost_localfunction.introduction"></a><a class="link" href="index.html#boost_localfunction.introduction" title="Introduction">Introduction</a>
 117 </h2></div></div></div>
 118 <p>
 119       <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
 120       functions</em></span></a>) are a form of <span class="emphasis"><em>information hiding</em></span>
 121       and they are useful for dividing procedural tasks into subtasks which are only
 122       meaningful locally, avoiding cluttering other parts of the program with functions,
 123       variables, etc unrelated to those parts. Therefore, local functions complement
 124       other structuring possibilities such as namespaces and classes. Local functions
 125       are a feature of many programming languages, notably <a href="http://en.wikipedia.org/wiki/Nested_function#An_example" target="_top">Pascal</a>
 126       and <a href="http://en.wikipedia.org/wiki/Nesting_(computing)#In_programming" target="_top">Ada</a>,
 127       yet lacking from <a href="http://www.open-std.org/JTC1/SC22/WG21/docs/standards" target="_top">C++03</a>
 128       (see also <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2511.html" target="_top">[N2511]</a>).
 129     </p>
 130 <p>
 131       Using <a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++11
 132       lambda functions</a>, it is possible to implement local functions by naming
 133       lambda functions assigning them to local variables. For example (see also
 134       <a href="../../example/add_cxx11_lambda.cpp" target="_top"><code class="literal">add_cxx11_lambda.cpp</code></a>):
 135     </p>
 136 <p>
 137 </p>
 138 <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>
 139     <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>
 140
 141     <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>
 142         <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>
 143     <span class="special">};</span>
 144
 145     <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>
 146     <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>
 147     <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>
 148
 149     <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>
 150     <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">report_errors</span><span class="special">();</span>
 151 <span class="special">}</span>
 152 </pre>
 153 <p>
 154     </p>
 155 <p>
 156       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>
 157       and <a href="http://www.open-std.org/JTC1/SC22/WG21/" target="_top">C++11</a> (and
 158       with performances comparable to lambda functions on <a href="http://www.open-std.org/JTC1/SC22/WG21/" target="_top">C++11</a>
 159       compilers). For example (see also <a href="../../test/add.cpp" target="_top"><code class="literal">add.cpp</code></a>):
 160     </p>
 161 <p>
 162 </p>
 163 <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>
 164     <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>
 165
 166     <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>
 167         <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>
 168     <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>
 169
 170     <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>
 171     <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>
 172     <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>
 173
 174     <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>
 175     <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">report_errors</span><span class="special">();</span>
 176 <span class="special">}</span>
 177 </pre>
 178 <p>
 179     </p>
 180 <p>
 181       This library supports the following features for local functions:
 182     </p>
 183 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 184 <li class="listitem">
 185           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>,
 186           any of the variables from the enclosing scope (a function together with
 187           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>).
 188         </li>
 189 <li class="listitem">
 190           The local function body is programmed using the usual C++ statement syntax
 191           (as a consequence, compiler errors and debugging retain their usual meaning
 192           and format).
 193         </li>
 194 <li class="listitem">
 195           Local functions can be passed as template parameters so they can be conveniently
 196           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>
 197         </li>
 198 <li class="listitem">
 199           However, local functions must be specified within a declarative context
 200           (e.g., at a point in the code where local variables can be declared) thus
 201           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>
 202         </li>
 203 </ul></div>
 204 <p>
 205       See the <a class="link" href="boost_localfunction/alternatives.html" title="Annex: Alternatives">Alternatives</a>
 206       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
 207       lambda functions</a>, <a href="http://www.boost.org/libs/phoenix" target="_top">Boost.Phoenix</a>,
 208       and other C++ techniques that implement features related to local functions.
 209     </p>
 210 </div>
 211 <div class="footnotes">
 212 <br><hr style="width:100; text-align:left;margin-left: 0">
 213 <div id="ftn.boost_localfunction.introduction.f0" class="footnote"><p><a href="#boost_localfunction.introduction.f0" class="para"><sup class="para">[1] </sup></a>
 214             This is a strength with respect to <a href="http://www.open-std.org/JTC1/SC22/WG21/docs/standards" target="_top">C++03</a>
 215             functors implemented using local classes which cannot be passed as template
 216             parameters (see <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2657.htm" target="_top">[N2657]</a>
 217             and the <a class="link" href="boost_localfunction/alternatives.html" title="Annex: Alternatives">Alternatives</a>
 218             section).
 219           </p></div>
 220 <div id="ftn.boost_localfunction.introduction.f1" class="footnote"><p><a href="#boost_localfunction.introduction.f1" class="para"><sup class="para">[2] </sup></a>
 221             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
 222             lambda functions</a> which can instead be specified also within expressions
 223             (see the <a class="link" href="boost_localfunction/alternatives.html" title="Annex: Alternatives">Alternatives</a>
 224             section).
 225           </p></div>
 226 </div>
 227 </div>
 228 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 229 <td align="left"><p><small>Last revised: October 14, 2015 at 23:57:30 GMT</small></p></td>
 230 <td align="right"><div class="copyright-footer"></div></td>
 231 </tr></table>
 232 <hr>
 233 <div class="spirit-nav"><a accesskey="n" href="boost_localfunction/getting_started.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a></div>
 234 </body>
 235 </html>