libs/spirit/doc/html/spirit/karma/tutorials/karma_adapted_complex.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Complex - Fully Integrated</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="Spirit 2.5.2">
   8 <link rel="up" href="../tutorials.html" title="Tutorials">
   9 <link rel="prev" href="karma_easier_complex.html" title="Complex - Made easier">
  10 <link rel="next" href="num_list.html" title="Number List - Printing Numbers From a std::vector">
  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="karma_easier_complex.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorials.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="num_list.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h4 class="title">
  27 <a name="spirit.karma.tutorials.karma_adapted_complex"></a><a class="link" href="karma_adapted_complex.html" title="Complex - Fully Integrated">Complex
  28         - Fully Integrated</a>
  29 </h4></div></div></div>
  30 <p>
  31           Until now, we have been working around the fact that <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">complex</span><span class="special">&lt;&gt;</span></code> is not a native <a href="../../../../../../../libs/fusion/doc/html/index.html" target="_top">Boost.Fusion</a>
  32           sequence. We have not been able to use it with the same simplicity and
  33           natural grace of a <code class="computeroutput"><span class="identifier">fusion</span><span class="special">::</span><span class="identifier">tuple</span><span class="special">&lt;&gt;</span></code> or a similar <a href="../../../../../../../libs/fusion/doc/html/index.html" target="_top">Boost.Fusion</a>
  34           data structure. Fortunately, starting with Boost V1.43 it is possible to
  35           adapt any data structure (not only, as before, structures with publicly
  36           accessible members) as a <a href="../../../../../../../libs/fusion/doc/html/index.html" target="_top">Boost.Fusion</a>
  37           sequence. All we have to do is to employ one of the new <code class="computeroutput"><span class="identifier">BOOST_FUSION_ADAPT_ADT</span></code>
  38           macros.
  39         </p>
  40 <h6>
  41 <a name="spirit.karma.tutorials.karma_adapted_complex.h0"></a>
  42           <span class="phrase"><a name="spirit.karma.tutorials.karma_adapted_complex.adapting_a_class_as_a_fusion_sequence"></a></span><a class="link" href="karma_adapted_complex.html#spirit.karma.tutorials.karma_adapted_complex.adapting_a_class_as_a_fusion_sequence">Adapting
  43           a Class As a Fusion Sequence</a>
  44         </h6>
  45 <p>
  46           Let us start with the code again, following up with the explanations afterwards.
  47         </p>
  48 <p>
  49           Wouldn't it be optimal if we could pass our instance of a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">complex</span><span class="special">&lt;&gt;</span></code>
  50           directly to <span class="emphasis"><em>Karma's</em></span> <code class="computeroutput"><span class="identifier">generate</span><span class="special">()</span></code> function:
  51         </p>
  52 <p>
  53 </p>
  54 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">OutputIterator</span><span class="special">&gt;</span>
  55 <span class="keyword">bool</span> <span class="identifier">generate_complex</span><span class="special">(</span><span class="identifier">OutputIterator</span> <span class="identifier">sink</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">complex</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">c</span><span class="special">)</span>
  56 <span class="special">{</span>
  57     <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">karma</span><span class="special">::</span><span class="identifier">double_</span><span class="special">;</span>
  58     <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">karma</span><span class="special">::</span><span class="identifier">bool_</span><span class="special">;</span>
  59     <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">karma</span><span class="special">::</span><span class="identifier">true_</span><span class="special">;</span>
  60     <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">karma</span><span class="special">::</span><span class="identifier">omit</span><span class="special">;</span>
  61     <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">karma</span><span class="special">::</span><span class="identifier">generate</span><span class="special">;</span>
  62
  63     <span class="keyword">return</span> <span class="identifier">generate</span><span class="special">(</span><span class="identifier">sink</span><span class="special">,</span>
  64
  65         <span class="comment">//  Begin grammar</span>
  66         <span class="special">(</span>
  67            <span class="special">&amp;</span><span class="identifier">true_</span> <span class="special">&lt;&lt;</span> <span class="char">'('</span> <span class="special">&lt;&lt;</span> <span class="identifier">double_</span> <span class="special">&lt;&lt;</span> <span class="string">", "</span> <span class="special">&lt;&lt;</span> <span class="identifier">double_</span> <span class="special">&lt;&lt;</span> <span class="char">')'</span>
  68         <span class="special">|</span>   <span class="identifier">omit</span><span class="special">[</span><span class="identifier">bool_</span><span class="special">]</span>  <span class="special">&lt;&lt;</span> <span class="identifier">double_</span>
  69         <span class="special">),</span>
  70         <span class="comment">//  End grammar</span>
  71
  72         <span class="identifier">c</span>     <span class="comment">//  Data to output</span>
  73     <span class="special">);</span>
  74 <span class="special">}</span>
  75 </pre>
  76 <p>
  77         </p>
  78 <p>
  79           Indeed, this is possible! All we have to supply to make this work is a
  80           magic incantation (somewhere in the global namespace):
  81         </p>
  82 <p>
  83 </p>
  84 <pre class="programlisting"><span class="comment">// We can leave off the setters as Karma does not need them.</span>
  85 <span class="identifier">BOOST_FUSION_ADAPT_ADT</span><span class="special">(</span>
  86     <span class="identifier">std</span><span class="special">::</span><span class="identifier">complex</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;,</span>
  87     <span class="special">(</span><span class="keyword">bool</span><span class="special">,</span> <span class="keyword">bool</span><span class="special">,</span> <span class="identifier">obj</span><span class="special">.</span><span class="identifier">imag</span><span class="special">()</span> <span class="special">!=</span> <span class="number">0</span><span class="special">,</span> <span class="comment">/**/</span><span class="special">)</span>
  88     <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">obj</span><span class="special">.</span><span class="identifier">real</span><span class="special">(),</span> <span class="comment">/**/</span><span class="special">)</span>
  89     <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">obj</span><span class="special">.</span><span class="identifier">imag</span><span class="special">(),</span> <span class="comment">/**/</span><span class="special">)</span>
  90 <span class="special">)</span>
  91 </pre>
  92 <p>
  93         </p>
  94 <p>
  95           Most of the formatting grammar itself has not changed from the last section.
  96           We still utilize a very similar scheme. We have an alternative providing
  97           the formatting rules for our both use cases: one for the full complex format
  98           and one for complex numbers with a zero imaginary part. But instead of
  99           selecting the required alternative by comparing the imaginary part to zero
 100           in the grammar we assume to receive a boolean attribute carrying this information:
 101         </p>
 102 <pre class="programlisting"><span class="special">&amp;</span><span class="identifier">true_</span> <span class="special">&lt;&lt;</span> <span class="string">"("</span> <span class="special">&lt;&lt;</span> <span class="identifier">double_</span> <span class="special">&lt;&lt;</span> <span class="string">", "</span> <span class="special">&lt;&lt;</span> <span class="identifier">double_</span> <span class="special">&lt;&lt;</span> <span class="string">")"</span>
 103 </pre>
 104 <p>
 105           This reads as: 'if the first (boolean) element of the supplied fusion sequence
 106           is <code class="computeroutput"><span class="keyword">true</span></code>, proceed as specified,
 107           else select the next alternative'. The next alternative now accounts for
 108           the boolean element as well, but is otherwise (almost) unchanged from the
 109           last section's example.
 110         </p>
 111 <p>
 112           Now it should be clear why our adapt construct above exposes a three element
 113           <a href="../../../../../../../libs/fusion/doc/html/index.html" target="_top">Boost.Fusion</a>
 114           sequence: a boolean and two double values (the real and the imaginary part
 115           of the complex number). We want it to match the requirements of our formatting
 116           grammar, which expects those exact values. The <code class="computeroutput"><span class="identifier">BOOST_FUSION_ADAPT_ADT</span></code>
 117           macro allows us to specify an arbitrary accessor construct, not necessarily
 118           limited to just calling a member function of the object instance (represented
 119           by <code class="computeroutput"><span class="identifier">obj</span></code> in the context of
 120           this macro). This allows us to nicely encapsulate the decision logic into
 121           the class adaptation.
 122         </p>
 123 <p>
 124           Here is the last new bit of information. If you look closely you realize
 125           the second alternative to be 'shorter' than the first one. It consumes
 126           only two elements of the supplied fusion sequence: it ignores the boolean
 127           and uses the real part of the complex number to generate its output. If
 128           there are more elements in our attribute than needed, we now can safely
 129           omit them from the grammar (which is a new 'feature' added to <a href="http://boost-spirit.com" target="_top">Spirit</a>
 130           in V1.43 as well). Note, we could have written the alternative as
 131         </p>
 132 <pre class="programlisting"><span class="special">&amp;</span><span class="identifier">false_</span> <span class="special">&lt;&lt;</span> <span class="identifier">double_</span>
 133 </pre>
 134 <p>
 135           but this would have been a bit less efficient as we needed to compare the
 136           boolean value again, while the final solution provided will just ignore
 137           it.
 138         </p>
 139 </div>
 140 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 141 <td align="left"></td>
 142 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2011 Joel de Guzman, Hartmut Kaiser<p>
 143         Distributed under the Boost Software License, Version 1.0. (See accompanying
 144         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>)
 145       </p>
 146 </div></td>
 147 </tr></table>
 148 <hr>
 149 <div class="spirit-nav">
 150 <a accesskey="p" href="karma_easier_complex.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorials.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="num_list.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
 151 </div>
 152 </body>
 153 </html>