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

This is the documentation for an old version of Boost. Click here to view this page for the latest version.
PrevUpHomeNext
Symbols (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.

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).

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).

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).

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.

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/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