...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
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.
// forwards to <boost/spirit/home/karma/string/symbols.hpp> #include <boost/spirit/include/karma_symbols.hpp>
Also, see Include Structure.
Name |
---|
|
template <typename Attrib, typename T, typename Lookup , typename CharEncoding, typename Tag> struct symbols;
Parameter |
Description |
Default |
---|---|---|
|
The type of the original attribute to be used as the key into the symbol generator (the symbol). |
|
|
The data type associated with each key. |
|
|
The symbol search implementation |
if T is |
|
Used for character set selection, normally not used by end user. |
|
|
Used for character set selection, normally not used by end user. |
|
Notation
Semantics of an expression is defined only where it differs from, or
is not defined in PrimitiveGenerator
.
Expression |
Semantics |
---|---|
|
Construct an empty symbols object instance named |
|
Construct an empty symbols object instance named |
|
Copy construct a symbols from |
|
Construct symbols from |
|
Construct symbols from |
|
Construct symbols from |
|
Construct symbols from |
|
Assign |
|
Assign one or more symbols ( |
|
Add one or more symbols ( |
|
Add one or more symbols ( |
|
Add one or more symbols ( |
|
Remove one or more symbols ( |
|
Remove one or more symbols ( |
|
Erase all of the symbols in |
|
Return a reference to the object associated with symbol, |
|
Return a pointer to the object associated with symbol, |
|
For each symbol in |
|
Retrieve the current name of the symbols object. |
|
Set the current name of the symbols object to be |
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.
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')));
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.
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/phoenix/core.hpp> #include <boost/phoenix/operator.hpp> #include <boost/fusion/include/std_pair.hpp> #include <boost/proto/deep_copy.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');