Character Classification Generators (alnum, digit, etc.)

Character Classification Generators (`alnum`, `digit`, etc.)

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 Character Encoding Namespace. This is needed when doing basic operations such as forcing lower or upper case.

Header

// forwards to <boost/spirit/home/karma/char/char_class.hpp>
#include <boost/spirit/include/karma_char_class.hpp>

Also, see Include Structure.

Namespace

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 Character 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.

Model of

PrimitiveGenerator

Notation

ns: A Character Encoding Namespace.

Expression Semantics

Semantics of an expression is defined only where it differs from, or is not defined in PrimitiveGenerator.

Expression	Semantics
`ns::alnum`	If the mandatory attribute satisfies the concept of `std::isalnum` in the Character 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 Character 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 Character 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 Character 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 Character 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 Character 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 Character 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 Character 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 Character 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 Character 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 Character 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 Character 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 Character 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.

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.

Complexity

O(1)

The complexity is constant as the generators emit not more than one character per invocation.

Example

	Note
	The test harness for the example(s) below is presented in the Basics Examples section.

Some includes:

#include <boost/spirit/include/karma.hpp>
#include <boost/spirit/include/support_utree.hpp>
#include <boost/spirit/include/phoenix_core.hpp>
#include <boost/spirit/include/phoenix_operator.hpp>
#include <boost/fusion/include/std_pair.hpp>
#include <iostream>
#include <string>

Some using declarations:

using boost::spirit::karma::alpha;
using boost::spirit::karma::upper;

Basic usage of an alpha generator:

test_generator_attr("a", alpha, 'a');
test_generator_attr("A", alpha, 'A');
test_generator_attr("", alpha, '1');          // fails (as isalpha('1') is false)
test_generator_attr("A", upper[alpha], 'A');
test_generator_attr("", upper[alpha], 'a');   // fails (as isupper('a') is false)