| Home | Libraries | People | FAQ | More

##### Generator Directives Controlling Case Sensitivity (`upper[]`, `lower[]`)

###### Description

The generator directives `ns::lower[]` and `ns::upper[]` force their embedded generators to emit lower case or upper case only characters based on the interpretation of the generated characters in the character set defined by `ns` (see Character Encoding Namespace).

###### Header

    // forwards to <boost/spirit/home/karma/directive/upper_lower_case.hpp>
    #include <boost/spirit/include/karma_upper_lower_case.hpp>

Also, see Include Structure.

###### Namespace

Name
`ns::lower`
`ns::upper`

In the table above, `ns` represents a Character Encoding Namespace.

###### Model of

> The model of `lower[]` and `upper[]` is the model of its subject generator.

Notation

`a`

  A generator object

`A`

  Attribute type of the generator `a`

`ns`

  A Character Encoding Namespace.

###### Expression Semantics

The `lower[]` and `upper[]` directives have no special generator semantics. They are pure modifier directives. They indirectly influence the way all subject generators work. They add information (the `tag::upper` or `tag::lower`) to the `Modifier` template parameter used while transforming the `proto::expr` into the corresponding generator expression. This is achieved by the following specializations:

    namespace boost { namespace spirit
    {
        template <typename CharEncoding>
        struct is_modifier_directive<
                karma::domain
              , tag::char_code<tag::lower, CharEncoding> >
          : mpl::true_
        {};

        template <typename CharEncoding>
        struct is_modifier_directive<
                karma::domain
              , tag::char_code<tag::upper, CharEncoding> >
          : mpl::true_
    }}

(for more details see the section describing the compilation process of the Boost.Proto expression into the corresponding generator expressions).

Expression | Semantics
--- | ---
`ns::lower[a]` | Generate `a` as lower case, interpreted in the character set defined by `ns`. The directive succeeds as long as the embedded generator succeeded (unless the underlying output stream reports an error).
`ns::upper[a]` | Generate `a` as upper case, interpreted in the character set defined by `ns`. The directive succeeds as long as the embedded generator succeeded (unless the underlying output stream reports an error).

| Note

If both directives are 'active' with regard to a generator, the innermost of those directives takes precedence. For instance:

    generate(sink, ascii::lower['A' << ascii::upper['b']])

will generate `"aB"` (without the quotes).

Further, the directives will have no effect on generators emitting characters not having an upper case or lower case equivalent in the character set defined by `ns`.

###### Attributes

See Compound Attribute Notation.

Expression | Attribute
--- | ---

`ns:lower[a]`

    a: A --> ns:lower[a]: A
    a: Unused --> ns:lower[a]: Unused

`ns:upper[a]`

    a: A --> ns:upper[a]: A
    a: Unused --> ns:upper[a]: Unused

###### Complexity

> The overall complexity of the generator directives `ns::lower[]` and `ns::upper[]` is defined by the complexity of its embedded generators. The directives themselves are compile time only directives, having no impact on runtime performance.

###### 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 <iostream>
    #include <string>

Some using declarations:

    using boost::spirit::karma::double_;
    using boost::spirit::ascii::upper;
    using boost::spirit::ascii::lower;

Basic usage of the `upper` and `lower` generator directives:

    test_generator_attr("abc:2.0e-06", lower["ABC:" << double_], 2e-6);
    test_generator_attr("ABC:2.0E-06", upper["abc:" << double_], 2e-6);