Google Git
Sign in
nest-open-source / nest-learning-thermostat / 5.0 / boost / 317601cb979f96545d0e892ce7cfdf59f676ee0a / . / boost_1_45_0 / libs / spirit / doc / html / spirit / karma / tutorials / num_list.html
blob: dddcb39402976c8d2df46413a4eee0de1788a0a3 [file] [log] [blame]
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Number List - Printing Numbers From a std::vector</title>
<link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.0">
<link rel="home" href="../../../index.html" title="Spirit 2.4.1">
<link rel="up" href="../tutorials.html" title="Tutorials">
<link rel="prev" href="karma_adapted_complex.html" title="Complex - Fully Integrated">
<link rel="next" href="num_matrix.html" title="Matrix of Numbers - Printing Numbers From a Matrix">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="karma_adapted_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_matrix.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="spirit.karma.tutorials.num_list"></a><a class="link" href="num_list.html" title="Number List - Printing Numbers From a std::vector">Number List - Printing
Numbers From a std::vector</a>
</h4></div></div></div>
<a name="spirit.karma.tutorials.num_list.using_the_list_operator"></a><h6>
<a name="id962940"></a>
<a class="link" href="num_list.html#spirit.karma.tutorials.num_list.using_the_list_operator">Using
the List Operator</a>
</h6>
<p>
The C++ Standard library lacks an important feature, namely the support
for any formatted output of containers. Sure, it's fairly easy to write
a custom routine to output a specific container, but doing so over and
over again is tedious at best. In this section we will demonstrate some
more of the capabilities of <span class="emphasis"><em>Spirit.Karma</em></span> for generating
output from arbitrary STL containers. We will build on the example presented
in an earlier section (see <a class="link" href="warming_up.html" title="Warming up">Warming
Up</a>).
</p>
<p>
The full source code of the example shown in this section can be found
here: <a href="../../../../../example/karma/num_list2.cpp" target="_top">num_list2.cpp</a>.
</p>
<p>
This time we take advantage of Karma's <a class="link" href="../reference/operator/list.html" title="Lists (a % b)">List
(<code class="computeroutput"><span class="special">%</span></code>)</a> operator. The semantics
of the list operator are fully equivalent to the semantics of the sequence
we used before. The generator expression
</p>
<pre class="programlisting"><span class="identifier">double_</span> <span class="special">&lt;&lt;</span> <span class="special">*(</span><span class="char">','</span> <span class="special">&lt;&lt;</span> <span class="identifier">double_</span><span class="special">)</span>
</pre>
<p>
is semantically equivalent to the generator expression
</p>
<pre class="programlisting"><span class="identifier">double_</span> <span class="special">%</span> <span class="char">','</span>
</pre>
<p>
simplifying the overall code. The list operator's attribute is compatible
with any STL container as well. For a change we use a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span></code> instead of the <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span></code> we used before. Additionally, the routine
<code class="computeroutput"><span class="identifier">generate_numbers</span></code> takes
the container as a template parameter, so it will now work with any STL
container holding <code class="computeroutput"><span class="keyword">double</span></code> numbers.
</p>
<p>
</p>
<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">,</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">&gt;</span>
<span class="keyword">bool</span> <span class="identifier">generate_numbers</span><span class="special">(</span><span class="identifier">OutputIterator</span><span class="special">&amp;</span> <span class="identifier">sink</span><span class="special">,</span> <span class="identifier">Container</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">v</span><span class="special">)</span>
<span class="special">{</span>
<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>
<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_delimited</span><span class="special">;</span>
<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">ascii</span><span class="special">::</span><span class="identifier">space</span><span class="special">;</span>
<span class="keyword">bool</span> <span class="identifier">r</span> <span class="special">=</span> <span class="identifier">generate_delimited</span><span class="special">(</span>
<span class="identifier">sink</span><span class="special">,</span> <span class="comment">// destination: output iterator
</span> <span class="identifier">double_</span> <span class="special">%</span> <span class="char">','</span><span class="special">,</span> <span class="comment">// the generator
</span> <span class="identifier">space</span><span class="special">,</span> <span class="comment">// the delimiter-generator
</span> <span class="identifier">v</span> <span class="comment">// the data to output
</span> <span class="special">);</span>
<span class="keyword">return</span> <span class="identifier">r</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
</p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
Despite the container being a template parameter, the <span class="emphasis"><em>Spirit.Karma</em></span>
formatting expression (<code class="computeroutput"><span class="identifier">double_</span>
<span class="special">%</span> <span class="char">','</span></code>)
does not depend on the actual type of the passed container. The only
precondition to be met here is that the elements stored in the container
have to be convertible to <code class="computeroutput"><span class="keyword">double</span></code>.
</p></td></tr>
</table></div>
<a name="spirit.karma.tutorials.num_list.generate_output_from_arbitrary_data"></a><h6>
<a name="id963455"></a>
<a class="link" href="num_list.html#spirit.karma.tutorials.num_list.generate_output_from_arbitrary_data">Generate
Output from Arbitrary Data</a>
</h6>
<p>
The output routine developed above is still not generically usable for
all types of STL containers and for arbitrary elements stored in them.
In order to be usable the items stored in the container still need to be
convertible to a <code class="computeroutput"><span class="keyword">double</span></code>. Fortunately
<span class="emphasis"><em>Spirit.Karma</em></span> is capable to output arbitrary data types
while using the same format description expression. It implements the
<a class="link" href="../reference/stream.html" title="Stream"><code class="computeroutput"><span class="identifier">stream</span></code></a>
generators which are able to consume any attribute type as long as a matching
standard streaming operator is defined. I.e. for any attribute type <code class="computeroutput"><span class="identifier">Attrib</span></code> a function:
</p>
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">&lt;&lt;</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span><span class="special">&amp;,</span> <span class="identifier">Attrib</span> <span class="keyword">const</span><span class="special">&amp;);</span>
</pre>
<p>
needs to be available. The <a class="link" href="../reference/stream.html" title="Stream"><code class="computeroutput"><span class="identifier">stream</span></code></a> generator will use the
standard streaming operator to generate the output.
</p>
<p>
The following example modifies the code shown above to utilize the <a class="link" href="../reference/stream.html" title="Stream"><code class="computeroutput"><span class="identifier">stream</span></code></a>
operator, which makes it compatible with almost any data type. We implement
a custom data type <code class="computeroutput"><span class="identifier">complex</span></code>
to demonstrate this. The example shows how it is possible to integrate
this (or any other) custom data type into the <span class="emphasis"><em>Spirit.Karma</em></span>
generator framework.
</p>
<p>
This is the custom data structure together with the required standard streaming
operator:
</p>
<p>
</p>
<pre class="programlisting"><span class="comment">// a simple complex number representation z = a + bi
</span><span class="keyword">struct</span> <span class="identifier">complex</span>
<span class="special">{</span>
<span class="identifier">complex</span> <span class="special">(</span><span class="keyword">double</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">b</span> <span class="special">=</span> <span class="number">0.0</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">a</span><span class="special">(</span><span class="identifier">a</span><span class="special">),</span> <span class="identifier">b</span><span class="special">(</span><span class="identifier">b</span><span class="special">)</span> <span class="special">{}</span>
<span class="keyword">double</span> <span class="identifier">a</span><span class="special">;</span>
<span class="keyword">double</span> <span class="identifier">b</span><span class="special">;</span>
<span class="special">};</span>
<span class="comment">// the streaming operator for the type complex
</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span><span class="special">&amp;</span>
<span class="keyword">operator</span><span class="special">&lt;&lt;</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span><span class="special">&amp;</span> <span class="identifier">os</span><span class="special">,</span> <span class="identifier">complex</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">os</span> <span class="special">&lt;&lt;</span> <span class="string">"{"</span> <span class="special">&lt;&lt;</span> <span class="identifier">z</span><span class="special">.</span><span class="identifier">a</span> <span class="special">&lt;&lt;</span> <span class="string">","</span> <span class="special">&lt;&lt;</span> <span class="identifier">z</span><span class="special">.</span><span class="identifier">b</span> <span class="special">&lt;&lt;</span> <span class="string">"}"</span><span class="special">;</span>
<span class="keyword">return</span> <span class="identifier">os</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
</p>
<p>
And this is the actual call to generate the output from a vector of those.
This time we interleave the generated output with newline breaks (see
<a class="link" href="../reference/auxiliary/eol.html" title="End of Line (eol)"><code class="computeroutput"><span class="identifier">eol</span></code></a>),
putting each complex number onto a separate line:
</p>
<p>
</p>
<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">,</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">&gt;</span>
<span class="keyword">bool</span> <span class="identifier">generate_numbers</span><span class="special">(</span><span class="identifier">OutputIterator</span><span class="special">&amp;</span> <span class="identifier">sink</span><span class="special">,</span> <span class="identifier">Container</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">v</span><span class="special">)</span>
<span class="special">{</span>
<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">stream</span><span class="special">;</span>
<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>
<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">eol</span><span class="special">;</span>
<span class="keyword">bool</span> <span class="identifier">r</span> <span class="special">=</span> <span class="identifier">generate</span><span class="special">(</span>
<span class="identifier">sink</span><span class="special">,</span> <span class="comment">// destination: output iterator
</span> <span class="identifier">stream</span> <span class="special">%</span> <span class="identifier">eol</span><span class="special">,</span> <span class="comment">// the generator
</span> <span class="identifier">v</span> <span class="comment">// the data to output
</span> <span class="special">);</span>
<span class="keyword">return</span> <span class="identifier">r</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
</p>
<p>
The code shown is fully generic and can be used with any STL container
as long as the data items stored in that container implement the standard
streaming operator.
</p>
<p>
The full source code of the example presented in this section can be found
here: <a href="../../../../../example/karma/num_list3.cpp" target="_top">num_list3.cpp</a>.
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2001-2010 Joel de Guzman, Hartmut Kaiser<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
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>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="karma_adapted_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_matrix.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>