1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>List Generator (a % b)</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="Spirit 2.5.8"> 8<link rel="up" href="../operator.html" title="Generator Operators"> 9<link rel="prev" href="plus.html" title="Plus Generator (+a)"> 10<link rel="next" href="optional.html" title="Optional Generator (-a)"> 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="plus.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../operator.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="optional.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h5 class="title"> 27<a name="spirit.karma.reference.operator.list"></a><a class="link" href="list.html" title="List Generator (a % b)">List Generator 28 (<code class="computeroutput"><span class="identifier">a</span> <span class="special">%</span> 29 <span class="identifier">b</span></code>)</a> 30</h5></div></div></div> 31<h6> 32<a name="spirit.karma.reference.operator.list.h0"></a> 33 <span class="phrase"><a name="spirit.karma.reference.operator.list.description"></a></span><a class="link" href="list.html#spirit.karma.reference.operator.list.description">Description</a> 34 </h6> 35<p> 36 The list generator is used to repeat the execution of an embedded generator 37 and intersperse it with the output of another generator one or more times. 38 It succeeds if the embedded generator has been successfully executed 39 at least once. 40 </p> 41<h6> 42<a name="spirit.karma.reference.operator.list.h1"></a> 43 <span class="phrase"><a name="spirit.karma.reference.operator.list.header"></a></span><a class="link" href="list.html#spirit.karma.reference.operator.list.header">Header</a> 44 </h6> 45<pre class="programlisting"><span class="comment">// forwards to <boost/spirit/home/karma/operator/list.hpp></span> 46<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">karma_list</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 47</pre> 48<p> 49 Also, see <a class="link" href="../../../structure/include.html" title="Include">Include Structure</a>. 50 </p> 51<h6> 52<a name="spirit.karma.reference.operator.list.h2"></a> 53 <span class="phrase"><a name="spirit.karma.reference.operator.list.model_of"></a></span><a class="link" href="list.html#spirit.karma.reference.operator.list.model_of">Model 54 of</a> 55 </h6> 56<div class="blockquote"><blockquote class="blockquote"><p> 57 <a class="link" href="../generator_concepts/binarygenerator.html" title="BinaryGenerator"><code class="computeroutput"><span class="identifier">BinaryGenerator</span></code></a> 58 </p></blockquote></div> 59<h6> 60<a name="spirit.karma.reference.operator.list.h3"></a> 61 <span class="phrase"><a name="spirit.karma.reference.operator.list.expression_semantics"></a></span><a class="link" href="list.html#spirit.karma.reference.operator.list.expression_semantics">Expression 62 Semantics</a> 63 </h6> 64<p> 65 Semantics of an expression is defined only where it differs from, or 66 is not defined in <a class="link" href="../generator_concepts/binarygenerator.html" title="BinaryGenerator"><code class="computeroutput"><span class="identifier">BinaryGenerator</span></code></a>. 67 </p> 68<div class="informaltable"><table class="table"> 69<colgroup> 70<col> 71<col> 72</colgroup> 73<thead><tr> 74<th> 75 <p> 76 Expression 77 </p> 78 </th> 79<th> 80 <p> 81 Semantics 82 </p> 83 </th> 84</tr></thead> 85<tbody><tr> 86<td> 87 <p> 88 <code class="computeroutput"><span class="identifier">a</span> <span class="special">%</span> 89 <span class="identifier">b</span></code> 90 </p> 91 </td> 92<td> 93 <p> 94 The generator <code class="computeroutput"><span class="identifier">a</span></code> 95 is executed one or more times depending on the availability 96 of an attribute. The output generated by <code class="computeroutput"><span class="identifier">a</span></code> 97 is interspersed with the output generated by <code class="computeroutput"><span class="identifier">b</span></code>. The list generator succeeds 98 if its first embedded generator has been successfully executed 99 at least once (unless the underlying output stream reports 100 an error). 101 </p> 102 </td> 103</tr></tbody> 104</table></div> 105<p> 106 The list expression <code class="computeroutput"><span class="identifier">a</span> <span class="special">%</span> <span class="identifier">b</span></code> 107 is a shortcut for <code class="computeroutput"><span class="identifier">a</span> <span class="special"><<</span> <span class="special">*(</span><span class="identifier">b</span> <span class="special"><<</span> 108 <span class="identifier">a</span><span class="special">)</span></code>. 109 It is almost semantically equivalent, except for the attribute of <code class="computeroutput"><span class="identifier">b</span></code>, which gets ignored in the case of 110 the list generator. 111 </p> 112<div class="note"><table border="0" summary="Note"> 113<tr> 114<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../images/note.png"></td> 115<th align="left">Note</th> 116</tr> 117<tr><td align="left" valign="top"><p> 118 All failing iterations of the embedded generator will consume one element 119 from the supplied attribute. The overall <code class="computeroutput"><span class="identifier">a</span> 120 <span class="special">%</span> <span class="identifier">b</span></code> 121 will succeed as long as at least one invocation of the embedded generator, 122 <code class="computeroutput"><span class="identifier">a</span></code>, will succeed (unless 123 the underlying output stream reports an error). 124 </p></td></tr> 125</table></div> 126<h6> 127<a name="spirit.karma.reference.operator.list.h4"></a> 128 <span class="phrase"><a name="spirit.karma.reference.operator.list.attributes"></a></span><a class="link" href="list.html#spirit.karma.reference.operator.list.attributes">Attributes</a> 129 </h6> 130<p> 131 See <a class="link" href="../../quick_reference/compound_attribute_rules.html#spirit.karma.quick_reference.compound_attribute_rules.notation">Compound 132 Attribute Notation</a>. 133 </p> 134<div class="informaltable"><table class="table"> 135<colgroup> 136<col> 137<col> 138</colgroup> 139<thead><tr> 140<th> 141 <p> 142 Expression 143 </p> 144 </th> 145<th> 146 <p> 147 Attribute 148 </p> 149 </th> 150</tr></thead> 151<tbody><tr> 152<td> 153 <p> 154 <code class="computeroutput"><span class="identifier">a</span> <span class="special">%</span> 155 <span class="identifier">b</span></code> (list) 156 </p> 157 </td> 158<td> 159 <p> 160</p> 161<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><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="identifier">a</span> <span class="special">%</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">vector</span><span class="special"><</span><span class="identifier">A</span><span class="special">></span> 162<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</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="identifier">a</span> <span class="special">%</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">Unused</span></pre> 163<p> 164 </p> 165 </td> 166</tr></tbody> 167</table></div> 168<div class="important"><table border="0" summary="Important"> 169<tr> 170<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../images/important.png"></td> 171<th align="left">Important</th> 172</tr> 173<tr><td align="left" valign="top"><p> 174 The table above uses <code class="computeroutput"><span class="identifier">vector</span><span class="special"><</span><span class="identifier">A</span><span class="special">></span></code> as a placeholder only. The notation 175 of <code class="computeroutput"><span class="identifier">vector</span><span class="special"><</span><span class="identifier">A</span><span class="special">></span></code> 176 stands for <span class="emphasis"><em>any STL container</em></span> holding elements 177 of type <code class="computeroutput"><span class="identifier">A</span></code>. 178 </p></td></tr> 179</table></div> 180<p> 181 The list generator will execute its embedded generator once for each 182 element in the provided container attribute and as long as the embedded 183 generator succeeds. The output generated by its first generator will 184 be interspersed by the output generated by the second generator. On each 185 iteration it will pass the next consecutive element from the container 186 attribute to the first embedded generator. The second embedded generator 187 does not get passed any attributes (it gets invoked using an <code class="computeroutput"><span class="identifier">unused_type</span></code> as its attribute). Therefore 188 the number of iterations will not be larger than the number of elements 189 in the container passed as its attribute. An empty container will make 190 the list generator fail. 191 </p> 192<div class="tip"><table border="0" summary="Tip"> 193<tr> 194<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../images/tip.png"></td> 195<th align="left">Tip</th> 196</tr> 197<tr><td align="left" valign="top"> 198<p> 199 If you want to use the list generator and still allow for an empty 200 attribute, you can use the optional operator (see <a class="link" href="optional.html" title="Optional Generator (-a)">Optional 201 (unary <code class="computeroutput"><span class="special">-</span></code>)</a>): 202 </p> 203<p> 204</p> 205<pre class="programlisting"><span class="special">-(</span><span class="identifier">a</span> <span class="special">%</span> <span class="identifier">b</span><span class="special">)</span></pre> 206<p> 207 </p> 208<p> 209 which will succeed even if the provided container attribute does not 210 contain any elements. 211 </p> 212</td></tr> 213</table></div> 214<h6> 215<a name="spirit.karma.reference.operator.list.h5"></a> 216 <span class="phrase"><a name="spirit.karma.reference.operator.list.complexity"></a></span><a class="link" href="list.html#spirit.karma.reference.operator.list.complexity">Complexity</a> 217 </h6> 218<div class="blockquote"><blockquote class="blockquote"><p> 219 The overall complexity of the list generator is defined by the complexity 220 of its embedded generators multiplied by the number of executed iterations. 221 The complexity of the list generator itself is O(N), where N is the 222 number of elements in the container passed as its attribute. 223 </p></blockquote></div> 224<h6> 225<a name="spirit.karma.reference.operator.list.h6"></a> 226 <span class="phrase"><a name="spirit.karma.reference.operator.list.example"></a></span><a class="link" href="list.html#spirit.karma.reference.operator.list.example">Example</a> 227 </h6> 228<div class="note"><table border="0" summary="Note"> 229<tr> 230<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../images/note.png"></td> 231<th align="left">Note</th> 232</tr> 233<tr><td align="left" valign="top"><p> 234 The test harness for the example(s) below is presented in the <a class="link" href="../basics.html#spirit.karma.reference.basics.examples">Basics Examples</a> 235 section. 236 </p></td></tr> 237</table></div> 238<p> 239 Some includes: 240 </p> 241<p> 242</p> 243<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">karma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 244<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">support_utree</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 245<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">phoenix_core</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 246<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">phoenix_operator</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 247<span class="preprocessor">#include</span> <span class="special"><</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">std_pair</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 248<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> 249<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">string</span><span class="special">></span> 250</pre> 251<p> 252 </p> 253<p> 254 Some using declarations: 255 </p> 256<p> 257</p> 258<pre class="programlisting"><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> 259</pre> 260<p> 261 </p> 262<p> 263 Basic usage of a list generator: 264 </p> 265<p> 266</p> 267<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">double</span><span class="special">></span> <span class="identifier">v1</span><span class="special">;</span> 268<span class="identifier">v1</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">1.0</span><span class="special">);</span> 269<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">"1.0"</span><span class="special">,</span> <span class="identifier">double_</span> <span class="special">%</span> <span class="char">','</span><span class="special">,</span> <span class="identifier">v1</span><span class="special">);</span> 270 271<span class="identifier">v1</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">2.0</span><span class="special">);</span> 272<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">"1.0,2.0"</span><span class="special">,</span> <span class="identifier">double_</span> <span class="special">%</span> <span class="char">','</span><span class="special">,</span> <span class="identifier">v1</span><span class="special">);</span> 273</pre> 274<p> 275 </p> 276</div> 277<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 278<td align="left"></td> 279<td align="right"><div class="copyright-footer">Copyright © 2001-2011 Joel de Guzman, Hartmut Kaiser<p> 280 Distributed under the Boost Software License, Version 1.0. (See accompanying 281 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>) 282 </p> 283</div></td> 284</tr></table> 285<hr> 286<div class="spirit-nav"> 287<a accesskey="p" href="plus.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../operator.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="optional.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a> 288</div> 289</body> 290</html> 291
