Google Git
Sign in
nest-open-source / nest-learning-thermostat / 5.0 / boost / 317601cb979f96545d0e892ce7cfdf59f676ee0a / . / boost_1_45_0 / libs / spirit / doc / html / spirit / karma / reference / operator / optional.html
blob: 3e9a89bc24a7fa5f3690003d20e63aa68085bd45 [file] [log] [blame]
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Optional (-a)</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="../operator.html" title="Operator">
<link rel="prev" href="list.html" title="Lists (a % b)">
<link rel="next" href="and_predicate.html" title="And-Predicate (&amp;a)">
</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="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>
</div>
<div class="section">
<div class="titlepage"><div><div><h5 class="title">
<a name="spirit.karma.reference.operator.optional"></a><a class="link" href="optional.html" title="Optional (-a)">Optional
(<code class="computeroutput"><span class="special">-</span><span class="identifier">a</span></code>)</a>
</h5></div></div></div>
<a name="spirit.karma.reference.operator.optional.description"></a><h6>
<a name="id1095885"></a>
<a class="link" href="optional.html#spirit.karma.reference.operator.optional.description">Description</a>
</h6>
<p>
The optional generator is used to conditionally execute an embedded generator.
It succeeds always.
</p>
<a name="spirit.karma.reference.operator.optional.header"></a><h6>
<a name="id1095902"></a>
<a class="link" href="optional.html#spirit.karma.reference.operator.optional.header">Header</a>
</h6>
<pre class="programlisting"><span class="comment">// forwards to &lt;boost/spirit/home/karma/operator/optional.hpp&gt;
</span><span class="preprocessor">#include</span> <span class="special">&lt;</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">&gt;</span>
</pre>
<p>
Also, see <a class="link" href="../../../structure/include.html" title="Include">Include Structure</a>.
</p>
<a name="spirit.karma.reference.operator.optional.model_of"></a><h6>
<a name="id1095976"></a>
<a class="link" href="optional.html#spirit.karma.reference.operator.optional.model_of">Model
of</a>
</h6>
<div class="blockquote"><blockquote class="blockquote"><p>
<a class="link" href="../generator_concepts/unarygenerator.html" title="UnaryGenerator"><code class="computeroutput"><span class="identifier">UnaryGenerator</span></code></a>
</p></blockquote></div>
<a name="spirit.karma.reference.operator.optional.expression_semantics"></a><h6>
<a name="id1096011"></a>
<a class="link" href="optional.html#spirit.karma.reference.operator.optional.expression_semantics">Expression
Semantics</a>
</h6>
<p>
Semantics of an expression is defined only where it differs from, or
is not defined in <a class="link" href="../generator_concepts/unarygenerator.html" title="UnaryGenerator"><code class="computeroutput"><span class="identifier">UnaryGenerator</span></code></a>.
</p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Expression
</p>
</th>
<th>
<p>
Semantics
</p>
</th>
</tr></thead>
<tbody><tr>
<td>
<p>
<code class="computeroutput"><span class="special">-</span><span class="identifier">a</span></code>
</p>
</td>
<td>
<p>
The generator <code class="computeroutput"><span class="identifier">a</span></code>
is executed depending on the availability of an attribute.
The optional generator succeeds if its embedded generator succeeds
(unless the underlying output stream reports an error).
</p>
</td>
</tr></tbody>
</table></div>
<a name="spirit.karma.reference.operator.optional.attributes"></a><h6>
<a name="id1096113"></a>
<a class="link" href="optional.html#spirit.karma.reference.operator.optional.attributes">Attributes</a>
</h6>
<p>
See <a class="link" href="../../quick_reference/compound_attribute_rules.html#spirit.karma.quick_reference.compound_attribute_rules.notation">Compound
Attribute Notation</a>.
</p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Expression
</p>
</th>
<th>
<p>
Attribute
</p>
</th>
</tr></thead>
<tbody><tr>
<td>
<p>
<code class="computeroutput"><span class="special">-</span><span class="identifier">a</span></code>
(optional, unary <code class="computeroutput"><span class="special">-</span></code>)
</p>
</td>
<td>
<p>
</p>
<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">--&gt;</span> <span class="special">-</span><span class="identifier">a</span><span class="special">:</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span>
<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="special">-</span><span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span></pre>
<p>
</p>
</td>
</tr></tbody>
</table></div>
<div class="important"><table border="0" summary="Important">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../images/important.png"></td>
<th align="left">Important</th>
</tr>
<tr><td align="left" valign="top"><p>
The table above uses <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span></code> as a placeholder only. The notation
of <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span></code>
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">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span></code>.
</p></td></tr>
</table></div>
<p>
The optional generator will execute its embedded generator once if the
provided attribute holds a valid value. It forwards the value held in
its attribute to the embedded generator.
</p>
<p>
It is important to note, that the optional generator does not perform
any buffering of the output generated by its embedded elements. That
means that any failing element might have already generated some output,
which is <span class="emphasis"><em>not</em></span> rolled back.
</p>
<div class="tip"><table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../images/tip.png"></td>
<th align="left">Tip</th>
</tr>
<tr><td align="left" valign="top">
<p>
The simplest way to force a optional generator to behave as if it did
buffering is to wrap it into a buffering directive (see <a class="link" href="../directive/buffer.html" title="Temporary Output Buffering (buffer[])"><code class="computeroutput"><span class="identifier">buffer</span></code></a>):
</p>
<p>
</p>
<pre class="programlisting"><span class="identifier">buffer</span><span class="special">[-</span><span class="identifier">a</span><span class="special">]</span></pre>
<p>
</p>
<p>
which will <span class="emphasis"><em>not</em></span> generate any output in case of
a failing generator <code class="computeroutput"><span class="special">-</span><span class="identifier">a</span></code>.
</p>
</td></tr>
</table></div>
<a name="spirit.karma.reference.operator.optional.complexity"></a><h6>
<a name="id1096426"></a>
<a class="link" href="optional.html#spirit.karma.reference.operator.optional.complexity">Complexity</a>
</h6>
<div class="blockquote"><blockquote class="blockquote"><p>
The overall complexity of the optional generator is defined by the
complexity of its embedded generator. The complexity of the optional
generator itself is O(1).
</p></blockquote></div>
<a name="spirit.karma.reference.operator.optional.example"></a><h6>
<a name="id1096446"></a>
<a class="link" href="optional.html#spirit.karma.reference.operator.optional.example">Example</a>
</h6>
<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>
The test harness for the example(s) below is presented in the <a class="link" href="../karma_basics.html#spirit.karma.reference.karma_basics.examples">Basics Examples</a>
section.
</p></td></tr>
</table></div>
<p>
Some includes:
</p>
<p>
</p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</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">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</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">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</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">&gt;</span>
<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">std_pair</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">string</span><span class="special">&gt;</span>
</pre>
<p>
</p>
<p>
Some using declarations:
</p>
<p>
</p>
<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>
</pre>
<p>
</p>
<p>
Basic usage of an optional generator:
</p>
<p>
</p>
<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">val</span><span class="special">(</span><span class="number">1.0</span><span class="special">);</span>
<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>
<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>
</pre>
<p>
</p>
<p>
Usage and result of an empty optional generator:
</p>
<p>
</p>
<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">val</span><span class="special">;</span> <span class="comment">// empty optional
</span><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>
</pre>
<p>
</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="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>
</div>
</body>
</html>