|  | Home | Libraries | People | FAQ | More | 
            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]](../../../../images/note.png) | 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');