Release 1.39.0
[boost.git] / Boost_1_39_0 / libs / fusion / doc / html / fusion / quick_start.html
blob7b92387dfb0efafd5f258ee2d0f2023f480f09e7
1 <html>
2 <head>
3 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4 <title>Quick Start</title>
5 <link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
6 <meta name="generator" content="DocBook XSL Stylesheets V1.66.1">
7 <link rel="start" href="../index.html" title="Chapter 1. Fusion 2.0">
8 <link rel="up" href="../index.html" title="Chapter 1. Fusion 2.0">
9 <link rel="prev" href="introduction.html" title="Introduction">
10 <link rel="next" href="organization.html" title="Organization">
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="../../../../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="introduction.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="organization.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
24 </div>
25 <div class="section" lang="en">
26 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
27 <a name="fusion.quick_start"></a><a href="quick_start.html" title="Quick Start">Quick Start</a></h2></div></div></div>
28 <p>
29 I assume the reader is already familiar with tuples (<a href="http://www.boost.org/libs/tuple/doc/tuple_users_guide.html" target="_top">Boost.Tuple</a>)
30 and its ancestor <tt class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span></tt>. The tuple is a generalization of <tt class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span></tt>
31 for multiple heterogeneous elements (triples, quadruples, etc.). The tuple
32 is more or less a synonym for fusion's <tt class="computeroutput"><a href="container/vector.html" title="vector"><tt class="computeroutput"><span class="identifier">vector</span></tt></a></tt>.
33 </p>
34 <p>
35 For starters, we shall include all of Fusion's <a href="sequence.html" title="Sequence">Sequence</a>(s)
36 <sup>[<a name="id456330" href="#ftn.id456330">2</a>]</sup>
38 </p>
39 <pre class="programlisting">
40 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">fusion</span><span class="special">/</span><span class="identifier">sequence</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
41 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">fusion</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">sequence</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
42 </pre>
43 <p>
44 Let's begin with a <tt class="computeroutput"><a href="container/vector.html" title="vector"><tt class="computeroutput"><span class="identifier">vector</span></tt></a></tt>
45 <sup>[<a name="id456497" href="#ftn.id456497">3</a>]</sup>
47 </p>
48 <pre class="programlisting">
49 <a href="container/vector.html" title="vector"><tt class="computeroutput"><span class="identifier">vector</span></tt></a><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">char</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;</span> <span class="identifier">stuff</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="char">'x'</span><span class="special">,</span> <span class="string">"howdy"</span><span class="special">);</span>
50 <span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <a href="sequence/intrinsic/functions/at_c.html" title="at_c"><tt class="computeroutput"><span class="identifier">at_c</span></tt></a><span class="special">&lt;</span><span class="number">0</span><span class="special">&gt;(</span><span class="identifier">stuff</span><span class="special">);</span>
51 <span class="keyword">char</span> <span class="identifier">ch</span> <span class="special">=</span> <a href="sequence/intrinsic/functions/at_c.html" title="at_c"><tt class="computeroutput"><span class="identifier">at_c</span></tt></a><span class="special">&lt;</span><span class="number">1</span><span class="special">&gt;(</span><span class="identifier">stuff</span><span class="special">);</span>
52 <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">s</span> <span class="special">=</span> <a href="sequence/intrinsic/functions/at_c.html" title="at_c"><tt class="computeroutput"><span class="identifier">at_c</span></tt></a><span class="special">&lt;</span><span class="number">2</span><span class="special">&gt;(</span><span class="identifier">stuff</span><span class="special">);</span>
53 </pre>
54 <p>
55 Just replace <tt class="computeroutput"><span class="identifier">tuple</span></tt> for <tt class="computeroutput"><a href="container/vector.html" title="vector"><tt class="computeroutput"><span class="identifier">vector</span></tt></a></tt>
56 and <tt class="computeroutput"><span class="identifier">get</span></tt> for <tt class="computeroutput"><a href="sequence/intrinsic/functions/at_c.html" title="at_c"><tt class="computeroutput"><span class="identifier">at_c</span></tt></a></tt> and this is exactly like
57 <a href="http://www.boost.org/libs/tuple/doc/tuple_users_guide.html" target="_top">Boost.Tuple</a>.
58 Actually, either names can be used interchangeably. Yet, the similarity ends
59 there. You can do a lot more with Fusion <tt class="computeroutput"><a href="container/vector.html" title="vector"><tt class="computeroutput"><span class="identifier">vector</span></tt></a></tt> or <tt class="computeroutput"><span class="identifier">tuple</span></tt>.
60 Let's see some examples.
61 </p>
62 <a name="fusion.quick_start.print_the_vector_as_xml"></a><h3>
63 <a name="id456960"></a>
64 <a href="quick_start.html#fusion.quick_start.print_the_vector_as_xml">Print the vector
65 as XML</a>
66 </h3>
67 <p>
68 First, let's include the algorithms:
69 </p>
70 <pre class="programlisting">
71 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">fusion</span><span class="special">/</span><span class="identifier">algorithm</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
72 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">fusion</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">algorithm</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
73 </pre>
74 <p>
75 Now, let's write a function object that prints XML of the form &lt;type&gt;data&lt;/type&gt;
76 for each member in the tuple.
77 </p>
78 <pre class="programlisting">
79 <span class="keyword">struct</span> <span class="identifier">print_xml</span>
80 <span class="special">{</span>
81 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">T</span><span class="special">&gt;</span>
82 <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">x</span><span class="special">)</span> <span class="keyword">const</span>
83 <span class="special">{</span>
84 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span>
85 <span class="special">&lt;&lt;</span> <span class="char">'&lt;'</span> <span class="special">&lt;&lt;</span> <span class="keyword">typeid</span><span class="special">(</span><span class="identifier">x</span><span class="special">).</span><span class="identifier">name</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="char">'&gt;'</span>
86 <span class="special">&lt;&lt;</span> <span class="identifier">x</span>
87 <span class="special">&lt;&lt;</span> <span class="string">"&lt;/"</span> <span class="special">&lt;&lt;</span> <span class="keyword">typeid</span><span class="special">(</span><span class="identifier">x</span><span class="special">).</span><span class="identifier">name</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="char">'&gt;'</span>
88 <span class="special">;</span>
89 <span class="special">}</span>
90 <span class="special">};</span>
91 </pre>
92 <p>
93 Now, finally:
94 </p>
95 <pre class="programlisting">
96 <a href="algorithm/iteration/functions/for_each.html" title="for_each"><tt class="computeroutput"><span class="identifier">for_each</span></tt></a><span class="special">(</span><span class="identifier">stuff</span><span class="special">,</span> <span class="identifier">print_xml</span><span class="special">());</span>
97 </pre>
98 <p>
99 That's it! <tt class="computeroutput"><a href="algorithm/iteration/functions/for_each.html" title="for_each"><tt class="computeroutput"><span class="identifier">for_each</span></tt></a></tt> is a fusion algorithm.
100 It is a generic algorithm similar to <a href="http://en.wikipedia.org/wiki/Standard_Template_Library" target="_top">STL</a>'s.
101 It iterates over the sequence and calls a user supplied function. In our case,
102 it calls <tt class="computeroutput"><span class="identifier">print_xml</span></tt>'s <tt class="computeroutput"><span class="keyword">operator</span><span class="special">()</span></tt> for
103 each element in <tt class="computeroutput"><span class="identifier">stuff</span></tt>.
104 </p>
105 <div class="caution"><table border="0" summary="Caution">
106 <tr>
107 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../doc/html/images/caution.png"></td>
108 <th align="left">Caution</th>
109 </tr>
110 <tr><td colspan="2" align="left" valign="top"><p>
111 The result of <tt class="computeroutput"><span class="keyword">typeid</span><span class="special">(</span><span class="identifier">x</span><span class="special">).</span><span class="identifier">name</span><span class="special">()</span></tt> is platform specific. The code here is
112 just for exposition. Of course you already know that :-)
113 </p></td></tr>
114 </table></div>
116 <tt class="computeroutput"><a href="algorithm/iteration/functions/for_each.html" title="for_each"><tt class="computeroutput"><span class="identifier">for_each</span></tt></a></tt> is generic. With
117 <tt class="computeroutput"><span class="identifier">print_xml</span></tt>, you can use it to
118 print just about any Fusion <a href="sequence.html" title="Sequence">Sequence</a>.
119 </p>
120 <a name="fusion.quick_start.print_only_pointers"></a><h3>
121 <a name="id457618"></a>
122 <a href="quick_start.html#fusion.quick_start.print_only_pointers">Print only pointers</a>
123 </h3>
125 Let's get a little cleverer. Say we wish to write a <span class="emphasis"><em>generic</em></span>
126 function that takes in an arbitrary sequence and XML prints only those elements
127 which are pointers. Ah, easy. First, let's include the <tt class="computeroutput"><span class="identifier">is_pointer</span></tt>
128 boost type trait:
129 </p>
130 <pre class="programlisting">
131 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">type_traits</span><span class="special">/</span><span class="identifier">is_pointer</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
132 </pre>
134 Then, simply:
135 </p>
136 <pre class="programlisting">
137 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Sequence</span><span class="special">&gt;</span>
138 <span class="keyword">void</span> <span class="identifier">xml_print_pointers</span><span class="special">(</span><span class="identifier">Sequence</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">seq</span><span class="special">)</span>
139 <span class="special">{</span>
140 <a href="algorithm/iteration/functions/for_each.html" title="for_each"><tt class="computeroutput"><span class="identifier">for_each</span></tt></a><span class="special">(</span><a href="algorithm/transformation/functions/filter_if.html" title="filter_if"><tt class="computeroutput"><span class="identifier">filter_if</span></tt></a><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">is_pointer</span><span class="special">&lt;</span><span class="identifier">_</span><span class="special">&gt;</span> <span class="special">&gt;(</span><span class="identifier">seq</span><span class="special">),</span> <span class="identifier">print_xml</span><span class="special">());</span>
141 <span class="special">}</span>
142 </pre>
144 <tt class="computeroutput"><a href="algorithm/transformation/functions/filter_if.html" title="filter_if"><tt class="computeroutput"><span class="identifier">filter_if</span></tt></a></tt> is another Fusion
145 algorithm. It returns a <a href="view/filter_view.html" title="filter_view"><tt class="computeroutput"><span class="identifier">filter_view</span></tt></a>, a conforming Fusion sequence.
146 This view reflects only those elements that pass the given predicate. In this
147 case, the predicate is <tt class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">is_pointer</span><span class="special">&lt;</span><span class="identifier">_</span><span class="special">&gt;</span></tt>.
148 This "filtered view" is then passed to the <a href="algorithm/iteration/functions/for_each.html" title="for_each"><tt class="computeroutput"><span class="identifier">for_each</span></tt></a> algorithm, which then prints
149 the "filtered view" as XML.
150 </p>
152 Easy, right?
153 </p>
154 <a name="fusion.quick_start.associative_tuples"></a><h3>
155 <a name="id458029"></a>
156 <a href="quick_start.html#fusion.quick_start.associative_tuples">Associative tuples</a>
157 </h3>
159 Ok, moving on...
160 </p>
162 Apart from <tt class="computeroutput"><a href="container/vector.html" title="vector"><tt class="computeroutput"><span class="identifier">vector</span></tt></a></tt>,
163 fusion has a couple of other sequence types to choose from. Each sequence has
164 its own characteristics. We have <tt class="computeroutput"><a href="container/list.html" title="list"><tt class="computeroutput"><span class="identifier">list</span></tt></a></tt>, <tt class="computeroutput"><a href="container/set.html" title="set"><tt class="computeroutput"><span class="identifier">set</span></tt></a></tt>, <tt class="computeroutput"><a href="container/map.html" title="map"><tt class="computeroutput"><span class="identifier">map</span></tt></a></tt>, plus a multitude of <tt class="computeroutput"><span class="identifier">views</span></tt> that provide various ways to present
165 the sequences.
166 </p>
168 Fusion's <tt class="computeroutput"><a href="container/map.html" title="map"><tt class="computeroutput"><span class="identifier">map</span></tt></a></tt>
169 associate types with elements. It can be used as a cleverer replacement of
170 the <tt class="computeroutput"><span class="keyword">struct</span></tt>. Example:
171 </p>
172 <pre class="programlisting">
173 <span class="keyword">namespace</span> <span class="identifier">fields</span>
174 <span class="special">{</span>
175 <span class="keyword">struct</span> <span class="identifier">name</span><span class="special">;</span>
176 <span class="keyword">struct</span> <span class="identifier">age</span><span class="special">;</span>
177 <span class="special">}</span>
179 <span class="keyword">typedef</span> <a href="container/map.html" title="map"><tt class="computeroutput"><span class="identifier">map</span></tt></a><span class="special">&lt;</span>
180 <a href="support/pair.html" title="pair"><tt class="computeroutput"><span class="identifier">fusion</span><span class="special">::</span><span class="identifier">pair</span></tt></a><span class="special">&lt;</span><span class="identifier">fields</span><span class="special">::</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;</span>
181 <span class="special">,</span> <a href="support/pair.html" title="pair"><tt class="computeroutput"><span class="identifier">fusion</span><span class="special">::</span><span class="identifier">pair</span></tt></a><span class="special">&lt;</span><span class="identifier">fields</span><span class="special">::</span><span class="identifier">age</span><span class="special">,</span> <span class="keyword">int</span><span class="special">&gt;</span> <span class="special">&gt;</span>
182 <span class="identifier">person</span><span class="special">;</span>
183 </pre>
185 <tt class="computeroutput"><a href="container/map.html" title="map"><tt class="computeroutput"><span class="identifier">map</span></tt></a></tt>
186 is an associative sequence. Its elements are Fusion pairs which differ somewhat
187 from <tt class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span></tt>. Fusion pairs only contain one member,
188 with the type of their second template parameter. The first type parameter
189 of the pair is used as an index to the associated element in the sequence.
190 For example, given a <tt class="computeroutput"><span class="identifier">a_person</span></tt>
191 of type, <tt class="computeroutput"><span class="identifier">person</span></tt>, you can do:
192 </p>
193 <pre class="programlisting">
194 <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">fields</span><span class="special">;</span>
195 <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">person_name</span> <span class="special">=</span> <a href="sequence/intrinsic/functions/at_key.html" title="at_key"><tt class="computeroutput"><span class="identifier">at_key</span></tt></a><span class="special">&lt;</span><span class="identifier">name</span><span class="special">&gt;(</span><span class="identifier">a_person</span><span class="special">);</span>
196 <span class="keyword">int</span> <span class="identifier">person_age</span> <span class="special">=</span> <a href="sequence/intrinsic/functions/at_key.html" title="at_key"><tt class="computeroutput"><span class="identifier">at_key</span></tt></a><span class="special">&lt;</span><span class="identifier">age</span><span class="special">&gt;(</span><span class="identifier">a_person</span><span class="special">);</span>
197 </pre>
199 Why go through all this trouble, you say? Well, for one, unlike the <tt class="computeroutput"><span class="keyword">struct</span></tt>, we are dealing with a generic data structure.
200 There are a multitude of facilities available at your disposal provided out
201 of the box with fusion or written by others. With these facilities, introspection
202 comes for free, for example. We can write one serialization function (well,
203 two, if you consider loading and saving) that will work for all your fusion
204 <tt class="computeroutput"><a href="container/map.html" title="map"><tt class="computeroutput"><span class="identifier">map</span></tt></a></tt>s.
205 Example:
206 </p>
207 <pre class="programlisting">
208 <span class="keyword">struct</span> <span class="identifier">saver</span>
209 <span class="special">{</span>
210 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Pair</span><span class="special">&gt;</span>
211 <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">Pair</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">data</span><span class="special">)</span> <span class="keyword">const</span>
212 <span class="special">{</span>
213 <span class="identifier">some_archive</span> <span class="special">&lt;&lt;</span> <span class="identifier">data</span><span class="special">.</span><span class="identifier">second</span><span class="special">;</span>
214 <span class="special">}</span>
215 <span class="special">};</span>
217 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Stuff</span><span class="special">&gt;</span>
218 <span class="keyword">void</span> <span class="identifier">save</span><span class="special">(</span><span class="identifier">Stuff</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">stuff</span><span class="special">)</span>
219 <span class="special">{</span>
220 <a href="algorithm/iteration/functions/for_each.html" title="for_each"><tt class="computeroutput"><span class="identifier">for_each</span></tt></a><span class="special">(</span><span class="identifier">stuff</span><span class="special">,</span> <span class="identifier">saver</span><span class="special">());</span>
221 <span class="special">}</span>
222 </pre>
224 The <tt class="computeroutput"><span class="identifier">save</span></tt> function is generic
225 and will work for all types of <tt class="computeroutput"><span class="identifier">stuff</span></tt>
226 regardless if it is a <tt class="computeroutput"><span class="identifier">person</span></tt>,
227 a <tt class="computeroutput"><span class="identifier">dog</span></tt> or a whole <tt class="computeroutput"><span class="identifier">alternate_universe</span></tt>.
228 </p>
229 <a name="fusion.quick_start.tip_of_the_iceberg"></a><h3>
230 <a name="id459070"></a>
231 <a href="quick_start.html#fusion.quick_start.tip_of_the_iceberg">Tip of the Iceberg</a>
232 </h3>
234 And... we've barely scratched the surface! You can compose and expand the data
235 structures, remove elements from the structures, find specific data types,
236 query the elements, filter out types for inspection, transform data structures,
237 etc. What you've seen is just the tip of the iceberg.
238 </p>
239 <div class="footnotes">
240 <br><hr width="100" align="left">
241 <div class="footnote"><p><sup>[<a name="ftn.id456330" href="#id456330">2</a>] </sup>
242 There are finer grained header files available if you wish to have more
243 control over which components to include (see section <a href="organization.html" title="Organization">Orgainization</a>
244 for details).
245 </p></div>
246 <div class="footnote"><p><sup>[<a name="ftn.id456497" href="#id456497">3</a>] </sup>
247 Unless otherwise noted, components are in namespace <tt class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">fusion</span></tt>.
248 For the sake of simplicity, code in this quick start implies <tt class="computeroutput"><span class="keyword">using</span></tt> directives for the fusion components
249 we will be using.
250 </p></div>
251 </div>
252 </div>
253 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
254 <td align="left"></td>
255 <td align="right"><div class="copyright-footer">Copyright © 2001-2007 Joel de Guzman, Dan Marsden, Tobias
256 Schwinger<p>
257 Distributed under the Boost Software License, Version 1.0. (See accompanying
258 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>)
259 </p>
260 </div></td>
261 </tr></table>
262 <hr>
263 <div class="spirit-nav">
264 <a accesskey="p" href="introduction.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="organization.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
265 </div>
266 </body>
267 </html>