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