Character Classification Generators (alnum, digit, etc.)

| Home | Libraries | People | FAQ | More

##### 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/phoenix/core.hpp>
    #include <boost/phoenix/operator.hpp>
    #include <boost/fusion/include/std_pair.hpp>
    #include <boost/proto/deep_copy.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)