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

PrevUpHomeNext
Symbols Generator (symbols)
Description

The class symbols implements an 'inverse' symbol table: an associative container (or map) of key-value pairs where the values are (most of the time) strings. It maps the value to be generated (the key) to any other value which will be emitted instead of the original key.

The Karma symbol table class symbols is-a generator, an instance of which may be used anywhere in the grammar specification. It is an example of a dynamic generator. A dynamic generator is characterized by its ability to modify its behavior at run time. Initially, an empty symbols object will emit nothing. At any time, symbols may be added, thus, dynamically altering its behavior.

Header
// forwards to <boost/spirit/home/karma/string/symbols.hpp>
#include <boost/spirit/include/karma_symbols.hpp>

Also, see Include Structure.

Namespace

Name

boost::spirit::karma::symbols

Synopsis
template <typename Attrib, typename T, typename Lookup
  , typename CharEncoding, typename Tag>
struct symbols;
Template parameters

Parameter

Description

Default

Attrib

The type of the original attribute to be used as the key into the symbol generator (the symbol).

char

T

The data type associated with each key.

unused_type

Lookup

The symbol search implementation

if T is unused_type, std::set<Attrib>, and std::map<Attrib, T> otherwise

CharEncoding

Used for character set selection, normally not used by end user.

unused_type

Tag

Used for character set selection, normally not used by end user.

unused_type

Model of

PrimitiveGenerator

Notation

Sym

A symbols type.

Attrib

An attribute type.

T

A data type.

sym, sym2

symbols objects.

sseq

An STL container of strings.

dseq

An STL container of data with value_type T.

s1...sN

A String.

d1...dN

Objects of type T.

f

A callable function or function object.

f, l

ForwardIterator first/last pair.

Expression Semantics

Semantics of an expression is defined only where it differs from, or is not defined in PrimitiveGenerator.

Expression

Semantics

Sym()

Construct an empty symbols object instance named "symbols".

Sym(name)

Construct an empty symbols object instance named name.

Sym(sym2)

Copy construct a symbols from sym2 (Another symbols object).

Sym(sseq)

Construct symbols from sseq (An STL container of symbols of type Attrib) named "symbols".

Sym(sseq, name)

Construct symbols from sseq (an STL container of symbols of type Attrib) named name.

Sym(sseq, dseq)

Construct symbols from sseq and dseq (An STL container of symbols of type Attrib and an STL container of data with value_type T) which is named "symbols".

Sym(sseq, dseq, name)

Construct symbols from sseq and dseq (An STL container of symbols of type Attrib and an STL container of data with value_type T) which is named name.

sym = sym2

Assign sym2 to sym.

sym = s1, s2, ..., sN

Assign one or more symbols (s1...sN) to sym. The associated data values of type T are default constructed.

sym += s1, s2, ..., sN

Add one or more symbols (s1...sN) to sym. The associated data values of type T are default constructed.

sym.add(s1)(s2)...(sN)

Add one or more symbols (s1...sN) to sym. The associated data values of type T are default constructed.

sym.add(s1, d1)(s2, d2)...(sN, dN)

Add one or more symbols (s1...sN) with associated data (d1...dN) to sym.

sym -= s1, s2, ..., sN

Remove one or more symbols (s1...sN) from sym.

sym.remove(s1)(s2)...(sN)

Remove one or more symbols (s1...sN) from sym.

sym.clear()

Erase all of the symbols in sym.

sym.at(s)

Return a reference to the object associated with symbol, s. If sym does not already contain such an object, at inserts the default object T().

sym.find(s)

Return a pointer to the object associated with symbol, s. If sym does not already contain such an object, find returns a null pointer.

sym.for_each(f)

For each symbol in sym s invoke f(typename Lookup::value_type).

sym.name()

Retrieve the current name of the symbols object.

sym.name(name)

Set the current name of the symbols object to be name.

The symbols generator uses the supplied attribute as the key to be looked up in the internal associative container. If the key exists the generator emits the associated value and succeeds (unless the underlying output stream reports an error). If the value type stored in the symbol generator is unused_type it will emit the key instead. If the key does not exist the generator fails while not emitting anything.

Attributes

The attribute of symbol<Attrib, T> is Attrib.

If the supplied attribute is a Boost.Fusion sequence, then the symbol table generator will use the first element of that Boost.Fusion sequence as the key to be used for lookup. The type of that first element needs to be convertible to Attrib. In this case the second element of the Boost.Fusion sequence is used as the attribute while calling a generator derived from the value stored in the symbol table for the found entry.

If the supplied attribute is a container type (traits::is_container resolves to mpl::true_), then the symbol table generator will use the first element stored in that container as the key to be used for lookup. The value_type (returned by traits::container_value) has to be convertible to Attrib. In this case the second element stored in that container is used as the attribute while calling a generator derived from the value stored in the symbol table for the found entry.

If the supplied attribute is not a Boost.Fusion sequence and not a container type, the supplied attribute is directly used as the key for item lookup. The attribute is used as the attribute while calling a generator derived from the value stored in the symbol table for the found entry.

In any case, because the supplied key (i.e. either the first element of the Boost.Fusion sequence, the first container element, or the attribute otherwise) is passed as the attribute to a generator derived from the value stored in the symbol table for the found entry, the symbol table may store generators, which will produce output based on that value. For instance:

// The symbol table maps a single character key to a rule<>
// The rule<> exposes an attribute of char as well
rule<output_iterator_type, char()> r1 = char_;

symbols<char, rule<output_iterator_type, char()> > sym;
sym.add
    ('j', r1.alias())
    ('h', r1.alias())
    ('t', r1.alias())
    ('k', r1.alias())
;

// Supplying a fusion vector as the attribute will use the first element
// (the 'j') as the key to be looked up, while the second element (the 'J') 
// is passed on as the attribute to the rule<> stored in the symbol table. 
// Consequently, the example generates a single 'J'.
BOOST_ASSERT(test("J", sym, make_vector('j', 'J')));
Complexity

The default implementation uses a std::map<> or a std::set<> with a complexity of:

O(log n)

Where n is the number of stored symbols.

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::symbols;

Basic usage of symbol generators:

symbols<char, char const*> sym;

sym.add
    ('a', "Apple")
    ('b', "Banana")
    ('o', "Orange")
;

test_generator_attr("Banana", sym, 'b');


PrevUpHomeNext