Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

Click here to view the latest version of this page.
PrevUpHomeNext
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] 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] 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] 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] 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")


PrevUpHomeNext