<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Alternative (a | b)</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">
<link rel="up" href="../operator.html" title="Operator">
<link rel="prev" href="sequence.html" title="Sequences (a << b)">
<link rel="next" href="kleene.html" title="Kleene Star (*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="sequence.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="kleene.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.alternative"></a><a class="link" href="alternative.html" title="Alternative (a | b)"> Alternative
(<code class="computeroutput"><span class="identifier">a</span> <span class="special">|</span>
<span class="identifier">b</span></code>)</a>
</h5></div></div></div>
<a name="spirit.karma.reference.operator.alternative.description"></a><h6>
<a name="id1131252"></a>
<a class="link" href="alternative.html#spirit.karma.reference.operator.alternative.description">Description</a>
</h6>
<p>
Generator alternatives are used to combine different, more primitive
generators into alternatives. All generators in an alternative are invoked
from left to right until one of them succeeds.
</p>
<a name="spirit.karma.reference.operator.alternative.header"></a><h6>
<a name="id1131268"></a>
<a class="link" href="alternative.html#spirit.karma.reference.operator.alternative.header">Header</a>
</h6>
<pre class="programlisting"><span class="comment">// forwards to <boost/spirit/home/karma/operator/alternative.hpp>
</span><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_alternative</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
</pre>
<p>
Also, see <a class="link" href="../../../structure/include.html" title="Include">Include Structure</a>.
</p>
<a name="spirit.karma.reference.operator.alternative.model_of"></a><h6>
<a name="id1131343"></a>
<a class="link" href="alternative.html#spirit.karma.reference.operator.alternative.model_of">Model
of</a>
</h6>
<div class="blockquote"><blockquote class="blockquote"><p>
<a class="link" href="../generator_concepts/narygenerator.html" title="NaryGenerator"><code class="computeroutput"><span class="identifier">NaryGenerator</span></code></a>
</p></blockquote></div>
<a name="spirit.karma.reference.operator.alternative.expression_semantics"></a><h6>
<a name="id1131373"></a>
<a class="link" href="alternative.html#spirit.karma.reference.operator.alternative.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/narygenerator.html" title="NaryGenerator"><code class="computeroutput"><span class="identifier">NaryGenerator</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="identifier">a</span> <span class="special">|</span>
<span class="identifier">b</span></code>
</p>
</td>
<td>
<p>
The generators <code class="computeroutput"><span class="identifier">a</span></code>
and <code class="computeroutput"><span class="identifier">b</span></code> are executed
sequentially from left to right until one of them succeeds.
A failed generator forces the alternative generator to try
the next one. The alternative fails as a whole only if all
elements of the alternative fail. Each element of the alternative
gets passed the whole attribute of the alternative.
</p>
</td>
</tr></tbody>
</table></div>
<p>
Alternatives intercept and buffer the output of the currently executed
element. This allows to avoid partial outputs from failing elements as
the buffered content will be forwarded to the actual output only after
an element succeeded.
</p>
<a name="spirit.karma.reference.operator.alternative.attributes"></a><h6>
<a name="id1131487"></a>
<a class="link" href="alternative.html#spirit.karma.reference.operator.alternative.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="identifier">a</span> <span class="special">|</span>
<span class="identifier">b</span></code> (alternative)
</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">,</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">variant</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">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">Unused</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">A</span>
<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">B</span>
<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">Unused</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>
<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">A</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">A</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">variant</span><span class="special"><</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">B</span><span class="special">></span></code> as a placeholder only. The notation
<code class="computeroutput"><span class="identifier">variant</span><span class="special"><</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">B</span><span class="special">></span></code>
stands for the type <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">variant</span><span class="special"><</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">B</span><span class="special">></span></code>.
</p></td></tr>
</table></div>
<p>
The attribute handling of Alternatives is special as their behavior is
not completely defined at compile time. First of all the selected alternative
element depends on the actual type of the attribute supplied to the alternative
generator (i.e. what is stored in the variant). The attribute type supplied
at <span class="emphasis"><em>runtime</em></span> narrows the set of considered alternatives
to those being compatible attribute wise. The remaining alternatives
are tried sequentially until the first of them succeeds. See below for
an example of this behavior.
</p>
<a name="spirit.karma.reference.operator.alternative.complexity"></a><h6>
<a name="id1132009"></a>
<a class="link" href="alternative.html#spirit.karma.reference.operator.alternative.complexity">Complexity</a>
</h6>
<div class="blockquote"><blockquote class="blockquote"><p>
The overall complexity of the alternative generator is defined by the
sum of the complexities of its elements. The complexity of the alternative
itself is O(N), where N is the number of elements in the alternative.
</p></blockquote></div>
<a name="spirit.karma.reference.operator.alternative.example"></a><h6>
<a name="id1132029"></a>
<a class="link" href="alternative.html#spirit.karma.reference.operator.alternative.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"><</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>
<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>
<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>
<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>
<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span>
<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">string</span><span class="special">></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>
<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">ascii</span><span class="special">::</span><span class="identifier">string</span><span class="special">;</span>
</pre>
<p>
</p>
<p>
Basic usage of an alternative. While being only the second alternative,
the <code class="computeroutput"><span class="identifier">double_</span></code> generator
is chosen for output formatting because the supplied attribute type is
not compatible (i.e. not convertible) to the attribute type of the <code class="computeroutput"><span class="identifier">string</span></code> alternative.
</p>
<p>
</p>
<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">variant</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">,</span> <span class="keyword">double</span><span class="special">></span> <span class="identifier">v1</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="identifier">string</span> <span class="special">|</span> <span class="identifier">double_</span><span class="special">,</span> <span class="identifier">v1</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="identifier">string</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>
The same formatting rules may be used to output a string. This time we
supply the string <code class="computeroutput"><span class="string">"example"</span></code>,
resulting in the first alternative to be chosen for the generated output.
</p>
<p>
</p>
<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">variant</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">,</span> <span class="keyword">double</span><span class="special">></span> <span class="identifier">v2</span><span class="special">(</span><span class="string">"example"</span><span class="special">);</span>
<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">"example"</span><span class="special">,</span> <span class="identifier">string</span> <span class="special">|</span> <span class="identifier">double_</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">);</span>
<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">"example"</span><span class="special">,</span> <span class="identifier">string</span> <span class="special">|</span> <span class="identifier">double_</span><span class="special">,</span> <span class="string">"example"</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 © 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="sequence.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="kleene.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
