String Generators (string, lit)

| Home | Libraries | People | FAQ | More

##### String Generators (`string`, `lit`)

###### Description

The string generators described in this section are:

The `string` generator emits a string of characters. The `string` generator is implicitly verbatim: the `delimit` parser is not applied in between characters of the string. The `string` generator has an associated Character Encoding Namespace. This is needed when doing basic operations such as forcing lower or upper case. Examples:

    string("Hello")
    string(L"Hello")
    string(s)         // s is a std::string

`lit`, like `string`, also emits a string of characters. The main difference is that `lit` does not consumes an attribute. A plain string like `"hello"` or a `std::basic_string` is equivalent to a `lit`. Examples:

    "Hello"
    lit("Hello")
    lit(L"Hello")
    lit(s)            // s is a std::string

###### Header

    // forwards to <boost/spirit/home/karma/string/lit.hpp>
    #include <boost/spirit/include/karma_string.hpp>

Also, see Include Structure.

###### Namespace

Name
`boost::spirit::lit // alias: boost::spirit::karma::lit`
`ns::string`

In the table above, `ns` represents a Character Encoding Namespace used by the corresponding string generator.

###### Model of

> `PrimitiveGenerator`

Notation

`s`

  Character-class specific string (See Character Class Types), or a Lazy Argument that evaluates to a character-class specific string value

`S`

  The type of a character-class specific string `s`.

`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 | Description
--- | ---
`s` | Generate the string literal `s`. This generator never fails (unless the underlying output stream reports an error).
`lit(s)` | Generate the string literal `s`. This generator never fails (unless the underlying output stream reports an error).
`ns::string` | Generate the string 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::string(s)` | Generate the string `s` as provided by the immediate literal value the generator is initialized from. If this generator has an associated attribute it succeeds only if 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.

| Note
The generators `lit(s)` and `string(s)` can be initialized either using a string literal value (i.e. `"abc"`), or using a `std::basic_string<char_type, ...>`, where `char_type` is the required value type of the underlying character sequence.

| Caution
The generator `string(s)` up to version 2.4.1 of Spirit has an undocumented feature. Given argument `s` generator succeeds as long as `s` is a prefix of given attribute. This problem has been fixed in Spirit V2.4.2.

###### Attributes

Expression | Attribute
--- | ---
`s` | `unused`
`lit(s)` | `unused`
`ns::string` | `S`, attribute is mandatory (otherwise compilation will fail)
`ns::string(s)` | `S`, attribute is optional, if it is supplied, the generator compares the attribute with `s` and succeeds only if both are equal, failing otherwise

| Note
In addition to their usual attribute of type `S` all listed generators accept an instance of a `boost::optional<S>` as well. If the `boost::optional<>` is initialized (holds a value) the generators behave as if their attribute was an instance of `S` and emit the value stored in the `boost::optional<>`. Otherwise the generators will fail.

###### Complexity

> O(N), where N is the number of characters emitted by the string generator

###### 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::lit;
    using boost::spirit::ascii::string;

Basic usage of `string` generators:

    test_generator("abc", "abc");
    test_generator("abc", lit("abc"));
    test_generator("abc", lit(std::string("abc")));

    test_generator_attr("abc", string, "abc");
    test_generator("abc", string("abc"));
    test_generator("abc", string(std::string("abc")));

    test_generator_attr("abc", string("abc"), "abc");
    test_generator_attr("", string("abc"), "cba");     // fails (as "abc" != "cba")