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