String Generators (string, lit)

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 succeds 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/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::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")