Symbols (symbols)

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
	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');