<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Character Generators (char_, lit)</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="../char.html" title="Char">
<link rel="prev" href="../char.html" title="Char">
<link rel="next" href="char_class.html" title="Character Classification (alnum, digit, etc.)">
</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="../char.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../char.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="char_class.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.char.char_generator"></a><a class="link" href="char_generator.html" title="Character Generators (char_, lit)"> Character
Generators (<code class="computeroutput"><span class="identifier">char_</span></code>, <code class="computeroutput"><span class="identifier">lit</span></code>)</a>
</h5></div></div></div>
<a name="spirit.karma.reference.char.char_generator.description"></a><h6>
<a name="id1067321"></a>
<a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.description">Description</a>
</h6>
<p>
The character generators described in this section are:
</p>
<p>
The <code class="computeroutput"><span class="identifier">char_</span></code> generator emits
single characters. The <code class="computeroutput"><span class="identifier">char_</span></code>
generator has an associated <a class="link" href="../karma_basics.html#spirit.karma.reference.karma_basics.character_encoding_namespace">Character
Encoding Namespace</a>. This is needed when doing basic operations
such as forcing lower or upper case and dealing with character ranges.
</p>
<p>
There are various forms of <code class="computeroutput"><span class="identifier">char_</span></code>.
</p>
<a name="spirit.karma.reference.char.char_generator.char_"></a><h6>
<a name="id1067371"></a>
<a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.char_">char_</a>
</h6>
<p>
The no argument form of <code class="computeroutput"><span class="identifier">char_</span></code>
emits any character in the associated <a class="link" href="../karma_basics.html#spirit.karma.reference.karma_basics.character_encoding_namespace">Character
Encoding Namespace</a>.
</p>
<pre class="programlisting"><span class="identifier">char_</span> <span class="comment">// emits any character as supplied by the attribute
</span></pre>
<a name="spirit.karma.reference.char.char_generator.char__ch_"></a><h6>
<a name="id1067412"></a>
<a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.char__ch_">char_(ch)</a>
</h6>
<p>
The single argument form of <code class="computeroutput"><span class="identifier">char_</span></code>
(with a character argument) emits the supplied character.
</p>
<pre class="programlisting"><span class="identifier">char_</span><span class="special">(</span><span class="char">'x'</span><span class="special">)</span> <span class="comment">// emits 'x'
</span><span class="identifier">char_</span><span class="special">(</span><span class="identifier">L</span><span class="char">'x'</span><span class="special">)</span> <span class="comment">// emits L'x'
</span><span class="identifier">char_</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="comment">// emits x (a char)
</span></pre>
<a name="spirit.karma.reference.char.char_generator.char__first__last_"></a><h6>
<a name="id1067503"></a>
<a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.char__first__last_">char_(first,
last)</a>
</h6>
<p>
<code class="computeroutput"><span class="identifier">char_</span></code> with two arguments,
emits any character from a range of characters as supplied by the attribute.
</p>
<pre class="programlisting"><span class="identifier">char_</span><span class="special">(</span><span class="char">'a'</span><span class="special">,</span><span class="char">'z'</span><span class="special">)</span> <span class="comment">// alphabetic characters
</span><span class="identifier">char_</span><span class="special">(</span><span class="identifier">L</span><span class="char">'0'</span><span class="special">,</span><span class="identifier">L</span><span class="char">'9'</span><span class="special">)</span> <span class="comment">// digits
</span></pre>
<p>
A range of characters is created from a low-high character pair. Such
a generator emits a single character that is in the range, including
both endpoints. Note, the first character must be <span class="emphasis"><em>before</em></span>
the second, according to the underlying <a class="link" href="../karma_basics.html#spirit.karma.reference.karma_basics.character_encoding_namespace">Character
Encoding Namespace</a>.
</p>
<p>
Character mapping is inherently platform dependent. It is not guaranteed
in the standard for example that <code class="computeroutput"><span class="char">'A'</span>
<span class="special"><</span> <span class="char">'Z'</span></code>,
that is why in Spirit2, we purposely attach a specific <a class="link" href="../karma_basics.html#spirit.karma.reference.karma_basics.character_encoding_namespace">Character
Encoding Namespace</a> (such as ASCII, ISO-8859-1) to the <code class="computeroutput"><span class="identifier">char_</span></code> generator to eliminate such ambiguities.
</p>
<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>
<span class="bold"><strong>Sparse bit vectors</strong></span>
</p>
<p>
To accomodate 16/32 and 64 bit characters, the char-set statically
switches from a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bitset</span></code>
implementation when the character type is not greater than 8 bits,
to a sparse bit/boolean set which uses a sorted vector of disjoint
ranges (<code class="computeroutput"><span class="identifier">range_run</span></code>).
The set is constructed from ranges such that adjacent or overlapping
ranges are coalesced.
</p>
<p>
<code class="computeroutput"><span class="identifier">range_runs</span></code> are very
space-economical in situations where there are lots of ranges and a
few individual disjoint values. Searching is O(log n) where n is the
number of ranges.
</p>
</td></tr>
</table></div>
<a name="spirit.karma.reference.char.char_generator.char__def_"></a><h6>
<a name="id1067686"></a>
<a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.char__def_">char_(def)</a>
</h6>
<p>
Lastly, when given a string (a plain C string, a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_string</span></code>,
etc.), the string is regarded as a char-set definition string following
a syntax that resembles posix style regular expression character sets
(except that double quotes delimit the set elements instead of square
brackets and there is no special negation ^ character). Examples:
</p>
<pre class="programlisting"><span class="identifier">char_</span><span class="special">(</span><span class="string">"a-zA-Z"</span><span class="special">)</span> <span class="comment">// alphabetic characters
</span><span class="identifier">char_</span><span class="special">(</span><span class="string">"0-9a-fA-F"</span><span class="special">)</span> <span class="comment">// hexadecimal characters
</span><span class="identifier">char_</span><span class="special">(</span><span class="string">"actgACTG"</span><span class="special">)</span> <span class="comment">// DNA identifiers
</span><span class="identifier">char_</span><span class="special">(</span><span class="string">"\x7f\x7e"</span><span class="special">)</span> <span class="comment">// Hexadecimal 0x7F and 0x7E
</span></pre>
<p>
These generators emit any character from a range of characters as supplied
by the attribute.
</p>
<a name="spirit.karma.reference.char.char_generator.lit_ch_"></a><h6>
<a name="id1067802"></a>
<a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.lit_ch_">lit(ch)</a>
</h6>
<p>
<code class="computeroutput"><span class="identifier">lit</span></code>, when passed a single
character, behaves like the single argument <code class="computeroutput"><span class="identifier">char_</span></code>
except that <code class="computeroutput"><span class="identifier">lit</span></code> does
not consume an attribute. A plain <code class="computeroutput"><span class="keyword">char</span></code>
or <code class="computeroutput"><span class="keyword">wchar_t</span></code> is equivalent
to a <code class="computeroutput"><span class="identifier">lit</span></code>.
</p>
<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>
<code class="computeroutput"><span class="identifier">lit</span></code> is reused by the
<a class="link" href="../string.html" title="String">String Generators</a>,
the char generators, and the Numeric Generators (see <a class="link" href="../numeric/signed_int.html" title="Signed Integer Number Generators (int_, etc.)">signed
integer</a>, <a class="link" href="../numeric/unsigned_int.html" title="Unsigned Integer Number Generators (uint_, etc.)">unsigned
integer</a>, and <a class="link" href="../numeric/real_number.html" title="Real Number Generators (float_, double_, etc.)">real
number</a> generators). In general, a char generator is created
when you pass in a character, a string generator is created when you
pass in a string, and a numeric generator is created when you use a
numeric literal. The exception is when you pass a single element literal
string, e.g. <code class="computeroutput"><span class="identifier">lit</span><span class="special">(</span><span class="string">"x"</span><span class="special">)</span></code>.
In this case, we optimize this to create a char generator instead of
a string generator.
</p></td></tr>
</table></div>
<p>
Examples:
</p>
<pre class="programlisting"><span class="char">'x'</span>
<span class="identifier">lit</span><span class="special">(</span><span class="char">'x'</span><span class="special">)</span>
<span class="identifier">lit</span><span class="special">(</span><span class="identifier">L</span><span class="char">'x'</span><span class="special">)</span>
<span class="identifier">lit</span><span class="special">(</span><span class="identifier">c</span><span class="special">)</span> <span class="comment">// c is a char
</span></pre>
<a name="spirit.karma.reference.char.char_generator.header"></a><h6>
<a name="id1067980"></a>
<a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.header">Header</a>
</h6>
<pre class="programlisting"><span class="comment">// forwards to <boost/spirit/home/karma/char/char.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_char_</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.char.char_generator.namespace"></a><h6>
<a name="id1068054"></a>
<a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.namespace">Namespace</a>
</h6>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
<p>
Name
</p>
</th></tr></thead>
<tbody>
<tr><td>
<p>
<code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">lit</span> <span class="comment">// alias:
boost::spirit::karma::lit</span></code>
</p>
</td></tr>
<tr><td>
<p>
<code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span></code>
</p>
</td></tr>
</tbody>
</table></div>
<p>
In the table above, <code class="computeroutput"><span class="identifier">ns</span></code>
represents a <a class="link" href="../karma_basics.html#spirit.karma.reference.karma_basics.character_encoding_namespace">Character
Encoding Namespace</a>.
</p>
<a name="spirit.karma.reference.char.char_generator.model_of"></a><h6>
<a name="id1068174"></a>
<a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.model_of">Model
of</a>
</h6>
<div class="blockquote"><blockquote class="blockquote"><p>
<a class="link" href="../generator_concepts/primitivegenerator.html" title="PrimitiveGenerator"><code class="computeroutput"><span class="identifier">PrimitiveGenerator</span></code></a>
</p></blockquote></div>
<div class="variablelist">
<p class="title"><b>Notation</b></p>
<dl>
<dt><span class="term"><code class="computeroutput"><span class="identifier">ch</span></code>, <code class="computeroutput"><span class="identifier">ch1</span></code>, <code class="computeroutput"><span class="identifier">ch2</span></code></span></dt>
<dd><p>
Character-class specific character (See Character Class Types),
or a <a class="link" href="../karma_basics.html#spirit.karma.reference.karma_basics.lazy_argument">Lazy
Argument</a> that evaluates to a character-class specific character
value
</p></dd>
<dt><span class="term"><code class="computeroutput"><span class="identifier">cs</span></code></span></dt>
<dd><p>
Character-set specifier string (See Character Class Types), or
a <a class="link" href="../karma_basics.html#spirit.karma.reference.karma_basics.lazy_argument">Lazy
Argument</a> that evaluates to a character-set specifier string,
or a pointer/reference to a null-terminated array of characters.
This string specifies a char-set definition string following a
syntax that resembles posix style regular expression character
sets (except the square brackets and the negation <code class="computeroutput"><span class="special">^</span></code> character).
</p></dd>
<dt><span class="term"><code class="computeroutput"><span class="identifier">ns</span></code></span></dt>
<dd><p>
A <a class="link" href="../karma_basics.html#spirit.karma.reference.karma_basics.character_encoding_namespace">Character
Encoding Namespace</a>.
</p></dd>
<dt><span class="term"><code class="computeroutput"><span class="identifier">cg</span></code></span></dt>
<dd><p>
A char generator, a char range generator, or a char set generator.
</p></dd>
</dl>
</div>
<a name="spirit.karma.reference.char.char_generator.expression_semantics"></a><h6>
<a name="id1068329"></a>
<a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.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/primitivegenerator.html" title="PrimitiveGenerator"><code class="computeroutput"><span class="identifier">PrimitiveGenerator</span></code></a>.
</p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Expression
</p>
</th>
<th>
<p>
Description
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">ch</span></code>
</p>
</td>
<td>
<p>
Generate the character literal <code class="computeroutput"><span class="identifier">ch</span></code>.
This generator never fails (unless the underlying output stream
reports an error).
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">lit</span><span class="special">(</span><span class="identifier">ch</span><span class="special">)</span></code>
</p>
</td>
<td>
<p>
Generate the character literal <code class="computeroutput"><span class="identifier">ch</span></code>.
This generator never fails (unless the underlying output stream
reports an error).
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span></code>
</p>
</td>
<td>
<p>
Generate the character provided by a mandatory attribute interpreted
in the character set defined by <code class="computeroutput"><span class="identifier">ns</span></code>.
This generator never fails (unless the underlying output stream
reports an error).
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="identifier">ch</span><span class="special">)</span></code>
</p>
</td>
<td>
<p>
Generate the character <code class="computeroutput"><span class="identifier">ch</span></code>
as provided by the immediate literal value the generator is
initialized from. If this generator has an associated attribute
it succeeds only as long as the attribute is equal to the immediate
literal (unless the underlying output stream reports an error).
Otherwise this generator fails and does not generate any output.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="string">"c"</span><span class="special">)</span></code>
</p>
</td>
<td>
<p>
Generate the character <code class="computeroutput"><span class="identifier">c</span></code>
as provided by the immediate literal value the generator is
initialized from. If this generator has an associated attribute
it succeeds only as long as the attribute is equal to the immediate
literal (unless the underlying output stream reports an error).
Otherwise this generator fails and does not generate any output.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="identifier">ch1</span><span class="special">,</span>
<span class="identifier">ch2</span><span class="special">)</span></code>
</p>
</td>
<td>
<p>
Generate the character provided by a mandatory attribute interpreted
in the character set defined by <code class="computeroutput"><span class="identifier">ns</span></code>.
The generator succeeds as long as the attribute belongs to
the character range <code class="computeroutput"><span class="special">[</span><span class="identifier">ch1</span><span class="special">,</span>
<span class="identifier">ch2</span><span class="special">]</span></code>
(unless the underlying output stream reports an error). Otherwise
this generator fails and does not generate any output.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="identifier">cs</span><span class="special">)</span></code>
</p>
</td>
<td>
<p>
Generate the character provided by a mandatory attribute interpreted
in the character set defined by <code class="computeroutput"><span class="identifier">ns</span></code>.
The generator succeeds as long as the attribute belongs to
the character set <code class="computeroutput"><span class="identifier">cs</span></code>
(unless the underlying output stream reports an error). Otherwise
this generator fails and does not generate any output.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="special">~</span><span class="identifier">cg</span></code>
</p>
</td>
<td>
<p>
Negate <code class="computeroutput"><span class="identifier">cg</span></code>.
The result is a negated char generator that inverts the test
condition of the character generator it is attached to.
</p>
</td>
</tr>
</tbody>
</table></div>
<p>
A character <code class="computeroutput"><span class="identifier">ch</span></code> is assumed
to belong to the character range defined by <code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="identifier">ch1</span><span class="special">,</span> <span class="identifier">ch2</span><span class="special">)</span></code> if its character value (binary representation)
interpreted in the character set defined by <code class="computeroutput"><span class="identifier">ns</span></code>
is not smaller than the character value of <code class="computeroutput"><span class="identifier">ch1</span></code>
and not larger then the character value of <code class="computeroutput"><span class="identifier">ch2</span></code>
(i.e. <code class="computeroutput"><span class="identifier">ch1</span> <span class="special"><=</span>
<span class="identifier">ch</span> <span class="special"><=</span>
<span class="identifier">ch2</span></code>).
</p>
<p>
The <code class="computeroutput"><span class="identifier">charset</span></code> parameter
passed to <code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="identifier">charset</span><span class="special">)</span></code>
must be a string containing more than one character. Every single character
in this string is assumed to belong to the character set defined by this
expression. An exception to this is the <code class="computeroutput"><span class="char">'-'</span></code>
character which has a special meaning if it is not specified as the first
and not the last character in <code class="computeroutput"><span class="identifier">charset</span></code>.
If the <code class="computeroutput"><span class="char">'-'</span></code> is used in between
to characters it is interpreted as spanning a character range. A character
<code class="computeroutput"><span class="identifier">ch</span></code> is considered to belong
to the defined character set <code class="computeroutput"><span class="identifier">charset</span></code>
if it matches one of the characters as specified by the string parameter
described above. For example
</p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Example
</p>
</th>
<th>
<p>
Description
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">char_</span><span class="special">(</span><span class="string">"abc"</span><span class="special">)</span></code>
</p>
</td>
<td>
<p>
'a', 'b', and 'c'
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">char_</span><span class="special">(</span><span class="string">"a-z"</span><span class="special">)</span></code>
</p>
</td>
<td>
<p>
all characters (and including) from 'a' to 'z'
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">char_</span><span class="special">(</span><span class="string">"a-zA-Z"</span><span class="special">)</span></code>
</p>
</td>
<td>
<p>
all characters (and including) from 'a' to 'z' and 'A' and
'Z'
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">char_</span><span class="special">(</span><span class="string">"-1-9"</span><span class="special">)</span></code>
</p>
</td>
<td>
<p>
'-' and all characters (and including) from '1' to '9'
</p>
</td>
</tr>
</tbody>
</table></div>
<a name="spirit.karma.reference.char.char_generator.attributes"></a><h6>
<a name="id1070380"></a>
<a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.attributes">Attributes</a>
</h6>
<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">ch</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">unused</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">lit</span><span class="special">(</span><span class="identifier">ch</span><span class="special">)</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">unused</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">Ch</span></code>, attribute
is mandatory (otherwise compilation will fail). <code class="computeroutput"><span class="identifier">Ch</span></code> is the character type
of the <a class="link" href="../karma_basics.html#spirit.karma.reference.karma_basics.character_encoding_namespace">Character
Encoding Namespace</a>, <code class="computeroutput"><span class="identifier">ns</span></code>.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="identifier">ch</span><span class="special">)</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">Ch</span></code>, attribute
is optional, if it is supplied, the generator compares the
attribute with <code class="computeroutput"><span class="identifier">ch</span></code>
and succeeds only if both are equal, failing otherwise. <code class="computeroutput"><span class="identifier">Ch</span></code> is the character type
of the <a class="link" href="../karma_basics.html#spirit.karma.reference.karma_basics.character_encoding_namespace">Character
Encoding Namespace</a>, <code class="computeroutput"><span class="identifier">ns</span></code>.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="string">"c"</span><span class="special">)</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">Ch</span></code>, attribute
is optional, if it is supplied, the generator compares the
attribute with <code class="computeroutput"><span class="identifier">c</span></code>
and succeeds only if both are equal, failing otherwise. <code class="computeroutput"><span class="identifier">Ch</span></code> is the character type
of the <a class="link" href="../karma_basics.html#spirit.karma.reference.karma_basics.character_encoding_namespace">Character
Encoding Namespace</a>, <code class="computeroutput"><span class="identifier">ns</span></code>.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="identifier">ch1</span><span class="special">,</span>
<span class="identifier">ch2</span><span class="special">)</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">Ch</span></code>, attribute
is mandatory (otherwise compilation will fail), the generator
succeeds if the attribute belongs to the character range <code class="computeroutput"><span class="special">[</span><span class="identifier">ch1</span><span class="special">,</span> <span class="identifier">ch2</span><span class="special">]</span></code> interpreted in the character
set defined by <code class="computeroutput"><span class="identifier">ns</span></code>.
<code class="computeroutput"><span class="identifier">Ch</span></code> is the character
type of the <a class="link" href="../karma_basics.html#spirit.karma.reference.karma_basics.character_encoding_namespace">Character
Encoding Namespace</a>, <code class="computeroutput"><span class="identifier">ns</span></code>.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="identifier">cs</span><span class="special">)</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">Ch</span></code>, attribute
is mandatory (otherwise compilation will fail), the generator
succeeds if the attribute belongs to the character set <code class="computeroutput"><span class="identifier">cs</span></code>, interpreted in the character
set defined by <code class="computeroutput"><span class="identifier">ns</span></code>.
<code class="computeroutput"><span class="identifier">Ch</span></code> is the character
type of the <a class="link" href="../karma_basics.html#spirit.karma.reference.karma_basics.character_encoding_namespace">Character
Encoding Namespace</a>, <code class="computeroutput"><span class="identifier">ns</span></code>.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="special">~</span><span class="identifier">cg</span></code>
</p>
</td>
<td>
<p>
Attribute of <code class="computeroutput"><span class="identifier">cg</span></code>
</p>
</td>
</tr>
</tbody>
</table></div>
<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>
In addition to their usual attribute of type <code class="computeroutput"><span class="identifier">Ch</span></code>
all listed generators accept an instance of a <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><</span><span class="identifier">Ch</span><span class="special">></span></code> as well. If the <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><></span></code> is initialized (holds a value)
the generators behave as if their attribute was an instance of <code class="computeroutput"><span class="identifier">Ch</span></code> and emit the value stored in the
<code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><></span></code>.
Otherwise the generators will fail.
</p></td></tr>
</table></div>
<a name="spirit.karma.reference.char.char_generator.complexity"></a><h6>
<a name="id1071029"></a>
<a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.complexity">Complexity</a>
</h6>
<div class="blockquote"><blockquote class="blockquote"><p>
O(1)
</p></blockquote></div>
<p>
The complexity of <code class="computeroutput"><span class="identifier">ch</span></code>,
<code class="computeroutput"><span class="identifier">lit</span><span class="special">(</span><span class="identifier">ch</span><span class="special">)</span></code>,
<code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span></code>, <code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="identifier">ch</span><span class="special">)</span></code>, and <code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="string">"c"</span><span class="special">)</span></code> is constant as all generators emit exactly
one character per invocation.
</p>
<p>
The character range generator (<code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="identifier">ch1</span><span class="special">,</span> <span class="identifier">ch2</span><span class="special">)</span></code>) additionally requires constant lookup
time for the verification whether the attribute belongs to the character
range.
</p>
<p>
The character set generator (<code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="identifier">cs</span><span class="special">)</span></code>) additionally requires O(log N) lookup
time for the verification whether the attribute belongs to the character
set, where N is the number of characters in the character set.
</p>
<a name="spirit.karma.reference.char.char_generator.example"></a><h6>
<a name="id1071209"></a>
<a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.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">lit</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">ascii</span><span class="special">::</span><span class="identifier">char_</span><span class="special">;</span>
</pre>
<p>
</p>
<p>
Basic usage of <code class="computeroutput"><span class="identifier">char_</span></code>
generators:
</p>
<p>
</p>
<pre class="programlisting"><span class="identifier">test_generator</span><span class="special">(</span><span class="string">"A"</span><span class="special">,</span> <span class="char">'A'</span><span class="special">);</span>
<span class="identifier">test_generator</span><span class="special">(</span><span class="string">"A"</span><span class="special">,</span> <span class="identifier">lit</span><span class="special">(</span><span class="char">'A'</span><span class="special">));</span>
<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">"a"</span><span class="special">,</span> <span class="identifier">char_</span><span class="special">,</span> <span class="char">'a'</span><span class="special">);</span>
<span class="identifier">test_generator</span><span class="special">(</span><span class="string">"A"</span><span class="special">,</span> <span class="identifier">char_</span><span class="special">(</span><span class="char">'A'</span><span class="special">));</span>
<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">"A"</span><span class="special">,</span> <span class="identifier">char_</span><span class="special">(</span><span class="char">'A'</span><span class="special">),</span> <span class="char">'A'</span><span class="special">);</span>
<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">""</span><span class="special">,</span> <span class="identifier">char_</span><span class="special">(</span><span class="char">'A'</span><span class="special">),</span> <span class="char">'B'</span><span class="special">);</span> <span class="comment">// fails (as 'A' != 'B')
</span>
<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">"A"</span><span class="special">,</span> <span class="identifier">char_</span><span class="special">(</span><span class="char">'A'</span><span class="special">,</span> <span class="char">'Z'</span><span class="special">),</span> <span class="char">'A'</span><span class="special">);</span>
<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">""</span><span class="special">,</span> <span class="identifier">char_</span><span class="special">(</span><span class="char">'A'</span><span class="special">,</span> <span class="char">'Z'</span><span class="special">),</span> <span class="char">'a'</span><span class="special">);</span> <span class="comment">// fails (as 'a' does not belong to 'A'...'Z')
</span>
<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">"k"</span><span class="special">,</span> <span class="identifier">char_</span><span class="special">(</span><span class="string">"a-z0-9"</span><span class="special">),</span> <span class="char">'k'</span><span class="special">);</span>
<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">""</span><span class="special">,</span> <span class="identifier">char_</span><span class="special">(</span><span class="string">"a-z0-9"</span><span class="special">),</span> <span class="char">'A'</span><span class="special">);</span> <span class="comment">// fails (as 'A' does not belong to "a-z0-9")
</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="../char.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../char.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="char_class.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
