libs/spirit/doc/karma/char.qbk
[/==============================================================================
Copyright (C) 2001-2011 Hartmut Kaiser
Copyright (C) 2001-2011 Joel de Guzman
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
===============================================================================/]
[section:char Char Generators]
This module includes different character oriented generators allowing to output
single characters. Currently, it includes literal chars (e.g. `'x'`, `L'x'`),
`char_` (single characters, ranges and character sets) and the encoding
specific character classifiers (`alnum`, `alpha`, `digit`, `xdigit`, etc.).
[heading Module Header]
// forwards to <boost/spirit/home/karma/char.hpp>
#include <boost/spirit/include/karma_char.hpp>
Also, see __include_structure__.
[/////////////////////////////////////////////////////////////////////////////]
[section:char_generator Character Generators (`char_`, `lit`)]
[heading Description]
The character generators described in this section are:
The `char_` generator emits single characters. The `char_` generator has an
associated __karma_char_encoding_namespace__. This is needed when doing basic
operations such as forcing lower or upper case and dealing with
character ranges.
There are various forms of `char_`.
[heading char_]
The no argument form of `char_` emits any character in the associated
__karma_char_encoding_namespace__.
char_ // emits any character as supplied by the attribute
[heading char_(ch)]
The single argument form of `char_` (with a character argument) emits
the supplied character.
char_('x') // emits 'x'
char_(L'x') // emits L'x'
char_(x) // emits x (a char)
[heading char_(first, last)]
`char_` with two arguments, emits any character from a range of characters as
supplied by the attribute.
char_('a','z') // alphabetic characters
char_(L'0',L'9') // digits
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 /before/ the second,
according to the underlying __karma_char_encoding_namespace__.
Character mapping is inherently platform dependent. It is not guaranteed
in the standard for example that `'A' < 'Z'`, that is why in Spirit2, we
purposely attach a specific __karma_char_encoding_namespace__ (such as ASCII,
ISO-8859-1) to the `char_` generator to eliminate such ambiguities.
[note *Sparse bit vectors*
To accommodate 16/32 and 64 bit characters, the char-set statically
switches from a `std::bitset` 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 (`range_run`). The set is constructed from
ranges such that adjacent or overlapping ranges are coalesced.
`range_runs` 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.]
[heading char_(def)]
Lastly, when given a string (a plain C string, a `std::basic_string`,
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:
char_("a-zA-Z") // alphabetic characters
char_("0-9a-fA-F") // hexadecimal characters
char_("actgACTG") // DNA identifiers
char_("\x7f\x7e") // Hexadecimal 0x7F and 0x7E
These generators emit any character from a range of characters as
supplied by the attribute.
[heading lit(ch)]
`lit`, when passed a single character, behaves like the single argument
`char_` except that `lit` does not consume an attribute. A plain
`char` or `wchar_t` is equivalent to a `lit`.
[note `lit` is reused by the [karma_string String Generators], the
char generators, and the Numeric Generators (see [signed_int signed integer],
[unsigned_int unsigned integer], and [real_number real number] 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.
`lit("x")`. In this case, we optimize this to create a char generator
instead of a string generator.]
Examples:
'x'
lit('x')
lit(L'x')
lit(c) // c is a char
[heading Header]
// forwards to <boost/spirit/home/karma/char/char.hpp>
#include <boost/spirit/include/karma_char_.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::lit // alias: boost::spirit::karma::lit` ]]
[[`ns::char_`]]
]
In the table above, `ns` represents a __karma_char_encoding_namespace__.
[heading Model of]
[:__primitive_generator_concept__]
[variablelist Notation
[[`ch`, `ch1`, `ch2`]
[Character-class specific character (See __char_class_types__),
or a __karma_lazy_argument__ that evaluates to a
character-class specific character value]]
[[`cs`] [Character-set specifier string (See
__char_class_types__), or a __karma_lazy_argument__ 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 `^` character).]]
[[`ns`] [A __karma_char_encoding_namespace__.]]
[[`cg`] [A char generator, a char range generator, or a char set generator.]]]
[heading Expression Semantics]
Semantics of an expression is defined only where it differs from, or is
not defined in __primitive_generator_concept__.
[table
[[Expression] [Description]]
[[`ch`] [Generate the character literal `ch`. This generator
never fails (unless the underlying output stream
reports an error).]]
[[`lit(ch)`] [Generate the character literal `ch`. This generator
never fails (unless the underlying output stream
reports an error).]]
[[`ns::char_`] [Generate the character provided by a mandatory
attribute interpreted in the character set defined
by `ns`. This generator never fails (unless the
underlying output stream reports an error).]]
[[`ns::char_(ch)`] [Generate the character `ch` 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.]]
[[`ns::char_("c")`] [Generate the character `c` 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.]]
[[`ns::char_(ch1, ch2)`][Generate the character provided by a mandatory
attribute interpreted in the character set defined
by `ns`. The generator succeeds as long as the
attribute belongs to the character range `[ch1, ch2]`
(unless the underlying output stream reports an
error). Otherwise this generator fails and does not
generate any output.]]
[[`ns::char_(cs)`] [Generate the character provided by a mandatory
attribute interpreted in the character set defined
by `ns`. The generator succeeds as long as the
attribute belongs to the character set `cs`
(unless the underlying output stream reports an
error). Otherwise this generator fails and does not
generate any output.]]
[[`~cg`] [Negate `cg`. The result is a negated char generator
that inverts the test condition of the character
generator it is attached to.]]
]
A character `ch` is assumed to belong to the character range defined by
`ns::char_(ch1, ch2)` if its character value (binary representation)
interpreted in the character set defined by `ns` is not smaller than the
character value of `ch1` and not larger then the character value of `ch2` (i.e.
`ch1 <= ch <= ch2`).
The `charset` parameter passed to `ns::char_(charset)` 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 `'-'` character which has a special meaning if it is not
specified as the first and not the last character in `charset`. If the `'-'`
is used in between to characters it is interpreted as spanning a character
range. A character `ch` is considered to belong to the defined character set
`charset` if it matches one of the characters as specified by the string
parameter described above. For example
[table
[[Example] [Description]]
[[`char_("abc")`] ['a', 'b', and 'c']]
[[`char_("a-z")`] [all characters (and including) from 'a' to 'z']]
[[`char_("a-zA-Z")`] [all characters (and including) from 'a' to 'z' and 'A' and 'Z']]
[[`char_("-1-9")`] ['-' and all characters (and including) from '1' to '9']]
]
[heading Attributes]
[table
[[Expression] [Attribute]]
[[`ch`] [__unused__]]
[[`lit(ch)`] [__unused__]]
[[`ns::char_`] [`Ch`, attribute is mandatory (otherwise compilation
will fail). `Ch` is the character type of the
__karma_char_encoding_namespace__, `ns`.]]
[[`ns::char_(ch)`] [`Ch`, attribute is optional, if it is supplied, the
generator compares the attribute with `ch` and
succeeds only if both are equal, failing otherwise.
`Ch` is the character type of the
__karma_char_encoding_namespace__, `ns`.]]
[[`ns::char_("c")`] [`Ch`, attribute is optional, if it is supplied, the
generator compares the attribute with `c` and
succeeds only if both are equal, failing otherwise.
`Ch` is the character type of the
__karma_char_encoding_namespace__, `ns`.]]
[[`ns::char_(ch1, ch2)`][`Ch`, attribute is mandatory (otherwise compilation
will fail), the generator succeeds if the attribute
belongs to the character range `[ch1, ch2]`
interpreted in the character set defined by `ns`.
`Ch` is the character type of the
__karma_char_encoding_namespace__, `ns`.]]
[[`ns::char_(cs)`] [`Ch`, attribute is mandatory (otherwise compilation
will fail), the generator succeeds if the attribute
belongs to the character set `cs`, interpreted
in the character set defined by `ns`.
`Ch` is the character type of the
__karma_char_encoding_namespace__, `ns`.]]
[[`~cg`] [Attribute of `cg`]]
]
[note In addition to their usual attribute of type `Ch` all listed generators
accept an instance of a `boost::optional<Ch>` as well. If the
`boost::optional<>` is initialized (holds a value) the generators behave
as if their attribute was an instance of `Ch` and emit the value stored
in the `boost::optional<>`. Otherwise the generators will fail.]
[heading Complexity]
[:O(1)]
The complexity of `ch`, `lit(ch)`, `ns::char_`, `ns::char_(ch)`, and
`ns::char_("c")` is constant as all generators emit exactly one character per
invocation.
The character range generator (`ns::char_(ch1, ch2)`) additionally requires
constant lookup time for the verification whether the attribute belongs to
the character range.
The character set generator (`ns::char_(cs)`) 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.
[heading Example]
[note The test harness for the example(s) below is presented in the
__karma_basics_examples__ section.]
Some includes:
[reference_karma_includes]
Some using declarations:
[reference_karma_using_declarations_char]
Basic usage of `char_` generators:
[reference_karma_char]
[endsect]
[/////////////////////////////////////////////////////////////////////////////]
[section:char_class Character Classification Generators (`alnum`, `digit`, etc.)]
[heading Description]
The library has the full repertoire of single character generators for
character classification. This includes the usual `alnum`, `alpha`,
`digit`, `xdigit`, etc. generators. These generators have an associated
__karma_char_encoding_namespace__. This is needed when doing basic operations
such as forcing lower or upper case.
[heading Header]
// forwards to <boost/spirit/home/karma/char/char_class.hpp>
#include <boost/spirit/include/karma_char_class.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`ns::alnum`]]
[[`ns::alpha`]]
[[`ns::blank`]]
[[`ns::cntrl`]]
[[`ns::digit`]]
[[`ns::graph`]]
[[`ns::lower`]]
[[`ns::print`]]
[[`ns::punct`]]
[[`ns::space`]]
[[`ns::upper`]]
[[`ns::xdigit`]]
]
In the table above, `ns` represents a __karma_char_encoding_namespace__ used by the
corresponding character class generator. All listed generators have a mandatory
attribute `Ch` and will not compile if no attribute is associated.
[heading Model of]
[:__primitive_generator_concept__]
[variablelist Notation
[[`ns`] [A __karma_char_encoding_namespace__.]]]
[heading Expression Semantics]
Semantics of an expression is defined only where it differs from, or is
not defined in __primitive_generator_concept__.
[table
[[Expression] [Semantics]]
[[`ns::alnum`] [If the mandatory attribute satisfies the concept of
`std::isalnum` in the __karma_char_encoding_namespace__
the generator succeeds after emitting
its attribute (unless the underlying output stream
reports an error). This generator fails otherwise
while not generating anything.]]
[[`ns::alpha`] [If the mandatory attribute satisfies the concept of
`std::isalpha` in the __karma_char_encoding_namespace__
the generator succeeds after emitting
its attribute (unless the underlying output stream
reports an error). This generator fails otherwise
while not generating anything.]]
[[`ns::blank`] [If the mandatory attribute satisfies the concept of
`std::isblank` in the __karma_char_encoding_namespace__
the generator succeeds after emitting
its attribute (unless the underlying output stream
reports an error). This generator fails otherwise
while not generating anything.]]
[[`ns::cntrl`] [If the mandatory attribute satisfies the concept of
`std::iscntrl` in the __karma_char_encoding_namespace__
the generator succeeds after emitting
its attribute (unless the underlying output stream
reports an error). This generator fails otherwise
while not generating anything.]]
[[`ns::digit`] [If the mandatory attribute satisfies the concept of
`std::isdigit` in the __karma_char_encoding_namespace__
the generator succeeds after emitting
its attribute (unless the underlying output stream
reports an error). This generator fails otherwise
while not generating anything.]]
[[`ns::graph`] [If the mandatory attribute satisfies the concept of
`std::isgraph` in the __karma_char_encoding_namespace__
the generator succeeds after emitting
its attribute (unless the underlying output stream
reports an error). This generator fails otherwise
while not generating anything.]]
[[`ns::print`] [If the mandatory attribute satisfies the concept of
`std::isprint` in the __karma_char_encoding_namespace__
the generator succeeds after emitting
its attribute (unless the underlying output stream
reports an error). This generator fails otherwise
while not generating anything.]]
[[`ns::punct`] [If the mandatory attribute satisfies the concept of
`std::ispunct` in the __karma_char_encoding_namespace__
the generator succeeds after emitting
its attribute (unless the underlying output stream
reports an error). This generator fails otherwise
while not generating anything.]]
[[`ns::xdigit`] [If the mandatory attribute satisfies the concept of
`std::isxdigit` in the __karma_char_encoding_namespace__
the generator succeeds after emitting
its attribute (unless the underlying output stream
reports an error). This generator fails otherwise
while not generating anything.]]
[[`ns::lower`] [If the mandatory attribute satisfies the concept of
`std::islower` in the __karma_char_encoding_namespace__
the generator succeeds after emitting
its attribute (unless the underlying output stream
reports an error). This generator fails otherwise
while not generating anything.]]
[[`ns::upper`] [If the mandatory attribute satisfies the concept of
`std::isupper` in the __karma_char_encoding_namespace__
the generator succeeds after emitting
its attribute (unless the underlying output stream
reports an error). This generator fails otherwise
while not generating anything.]]
[[`ns::space`] [If the optional attribute satisfies the concept of
`std::isspace` in the __karma_char_encoding_namespace__
the generator succeeds after emitting
its attribute (unless the underlying output stream
reports an error). This generator fails otherwise
while not generating anything.If no attribute is
supplied this generator emits a single space
character in the character set defined by `ns`.]]
]
Possible values for `ns` are described in the section __karma_char_encoding_namespace__.
[note The generators `alpha` and `alnum` might seem to behave unexpected if
used inside a `lower[]` or `upper[]` directive. Both directives
additionally apply the semantics of `std::islower` or `std::isupper`
to the respective character class. Some examples:
``
std::string s;
std::back_insert_iterator<std::string> out(s);
generate(out, lower[alpha], 'a'); // succeeds emitting 'a'
generate(out, lower[alpha], 'A'); // fails
``
The generator directive `upper[]` behaves correspondingly.
]
[heading Attributes]
[:All listed character class generators can take any attribute `Ch`. All
character class generators (except `space`) require an attribute and will
fail compiling otherwise.]
[note In addition to their usual attribute of type `Ch` all listed generators
accept an instance of a `boost::optional<Ch>` as well. If the
`boost::optional<>` is initialized (holds a value) the generators behave
as if their attribute was an instance of `Ch` and emit the value stored
in the `boost::optional<>`. Otherwise the generators will fail.]
[heading Complexity]
[:O(1)]
The complexity is constant as the generators emit not more than one character
per invocation.
[heading Example]
[note The test harness for the example(s) below is presented in the
__karma_basics_examples__ section.]
Some includes:
[reference_karma_includes]
Some using declarations:
[reference_karma_using_declarations_char_class]
Basic usage of an `alpha` generator:
[reference_karma_char_class]
[endsect]
[endsect]
