| [/============================================================================== |
| Copyright (C) 2001-2010 Joel de Guzman |
| Copyright (C) 2001-2010 Hartmut Kaiser |
| |
| Distributed under the Boost Software License, Version 1.0. (See accompanying |
| file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) |
| ===============================================================================/] |
| |
| [section String] |
| |
| This module includes parsers for strings. Currently, this module |
| includes the literal and string parsers and the symbol table. |
| |
| [heading Module Header] |
| |
| // forwards to <boost/spirit/home/qi/string.hpp> |
| #include <boost/spirit/include/qi_string.hpp> |
| |
| Also, see __include_structure__. |
| |
| [/------------------------------------------------------------------------------] |
| [section:string String (`string`, `lit`)] |
| |
| [heading Description] |
| |
| The `string` parser matches a string of characters. The `string` parser |
| is an implicit lexeme: the `skip` parser is not applied in between |
| characters of the string. The `string` parser has an associated |
| __char_encoding_namespace__. This is needed when doing basic operations |
| such as inhibiting case sensitivity. Examples: |
| |
| string("Hello") |
| string(L"Hello") |
| string(s) // s is a std::string |
| |
| `lit`, like `string`, also matches a string of characters. The main |
| difference is that `lit` does not synthesize an attribute. A plain |
| string like `"hello"` or a `std::basic_string` is equivalent to a `lit`. |
| Examples: |
| |
| "Hello" |
| lit("Hello") |
| lit(L"Hello") |
| lit(s) // s is a std::string |
| |
| [heading Header] |
| |
| // forwards to <boost/spirit/home/qi/string/lit.hpp> |
| #include <boost/spirit/include/qi_lit.hpp> |
| |
| [heading Namespace] |
| |
| [table |
| [[Name]] |
| [[`boost::spirit::lit // alias: boost::spirit::qi::lit`]] |
| [[`ns::string`]] |
| ] |
| |
| In the table above, `ns` represents a __char_encoding_namespace__. |
| |
| [heading Model of] |
| |
| [:__primitive_parser_concept__] |
| |
| [variablelist Notation |
| [[`s`] [A __string__ or a __qi_lazy_argument__ that evaluates to a __string__.]] |
| [[`ns`] [A __char_encoding_namespace__.]]] |
| |
| [heading Expression Semantics] |
| |
| Semantics of an expression is defined only where it differs from, or is |
| not defined in __primitive_parser_concept__. |
| |
| [table |
| [[Expression] [Semantics]] |
| [[`s`] [Create string parser |
| from a string, `s`.]] |
| [[`lit(s)`] [Create a string parser |
| from a string, `s`.]] |
| [[`ns::string(s)`] [Create a string parser with `ns` encoding |
| from a string, `s`.]] |
| ] |
| |
| [heading Attributes] |
| |
| [table |
| [[Expression] [Attribute]] |
| [[`s`] [__unused__]] |
| [[`lit(s)`] [__unused__]] |
| [[`ns::string(s)`] [`std::basic_string<T>` where `T` |
| is the underlying character type |
| of `s`.]] |
| ] |
| |
| [heading Complexity] |
| |
| [:O(N)] |
| |
| where `N` is the number of characters in the string to be parsed. |
| |
| [heading Example] |
| |
| [note The test harness for the example(s) below is presented in the |
| __qi_basics_examples__ section.] |
| |
| Some using declarations: |
| |
| [reference_using_declarations_lit_string] |
| |
| Basic literals: |
| |
| [reference_string_literals] |
| |
| From a `std::string` |
| |
| [reference_string_std_string] |
| |
| Lazy strings using __phoenix__ |
| |
| [reference_string_phoenix] |
| |
| [endsect] [/ lit/string] |
| |
| |
| [/------------------------------------------------------------------------------] |
| [section:symbols Symbols (`symbols`)] |
| |
| [heading Description] |
| |
| The class `symbols` implements a symbol table: an associative container |
| (or map) of key-value pairs where the keys are strings. The `symbols` |
| class can work efficiently with 8, 16, 32 and even 64 bit characters. |
| |
| Traditionally, symbol table management is maintained separately outside |
| the grammar through semantic actions. Contrary to standard practice, the |
| Spirit symbol table class `symbols` is-a parser, an instance of which may |
| be used anywhere in the grammar specification. It is an example of a |
| dynamic parser. A dynamic parser is characterized by its ability to |
| modify its behavior at run time. Initially, an empty symbols object |
| matches nothing. At any time, symbols may be added, thus, dynamically |
| altering its behavior. |
| |
| [heading Header] |
| |
| // forwards to <boost/spirit/home/qi/string/symbols.hpp> |
| #include <boost/spirit/include/qi_symbols.hpp> |
| |
| Also, see __include_structure__. |
| |
| [heading Namespace] |
| |
| [table |
| [[Name]] |
| [[`boost::spirit::qi::symbols`]] |
| [[`boost::spirit::qi::tst`]] |
| [[`boost::spirit::qi::tst_map`]] |
| ] |
| |
| [heading Synopsis] |
| |
| template <typename Char, typename T, typename Lookup> |
| struct symbols; |
| |
| [heading Template parameters] |
| |
| [table |
| [[Parameter] [Description] [Default]] |
| [[`Char`] [The character type |
| of the symbol strings.] [`char`]] |
| [[`T`] [The data type associated |
| with each symbol.] [__unused_type__]] |
| [[`Lookup`] [The symbol search |
| implementation] [`tst<Char, T>`]] |
| ] |
| |
| [heading Model of] |
| |
| [:__primitive_parser_concept__] |
| |
| [variablelist Notation |
| [[`Sym`] [A `symbols` type.]] |
| [[`Char`] [A character 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.]] |
| ] |
| |
| [heading Expression Semantics] |
| |
| Semantics of an expression is defined only where it differs from, or is not |
| defined in __primitive_parser_concept__. |
| |
| [table |
| [[Expression] [Semantics]] |
| [[`Sym()`] [Construct an empty symbols.]] |
| [[`Sym(sym2)`] [Copy construct a symbols from `sym2` (Another `symbols` object).]] |
| [[`Sym(sseq)`] [Construct symbols from `sseq` (An __stl__ container of strings).]] |
| [[`Sym(sseq, dseq)`] [Construct symbols from `sseq` and `dseq` |
| (An __stl__ container of strings 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`.]] |
| [[`sym += s1, s2, ..., sN`] [Add one or more symbols (`s1`...`sN`) to `sym`.]] |
| [[`sym.add(s1)(s2)...(sN)`] [Add one or more symbols (`s1`...`sN`) to `sym`.]] |
| [[`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.prefix_find(f, l)`] [Return a pointer to the object associated |
| with longest symbol that matches the beginning |
| of the range `[f, l)`, and updates `f` to point |
| to one past the end of that match. If no symbol matches, |
| then return a null pointer, and `f` is unchanged.]] |
| [[`sym.for_each(f)`] [For each symbol in `sym`, `s`, a |
| `std::basic_string<Char>` with associated data, |
| `d`, an object of type `T`, invoke `f(s, d)`.]] |
| ] |
| |
| [heading Attributes] |
| |
| The attribute of `symbol<Char, T>` is `T`. |
| |
| [heading Complexity] |
| |
| The default implementation uses a Ternary Search Tree (TST) with |
| complexity: |
| |
| [:O(log n+k)] |
| |
| Where k is the length of the string to be searched in a TST with n |
| strings. |
| |
| TSTs are faster than hashing for many typical search problems especially |
| when the search interface is iterator based. TSTs are many times faster |
| than hash tables for unsuccessful searches since mismatches are |
| discovered earlier after examining only a few characters. Hash tables |
| always examine an entire key when searching. |
| |
| An alternative implementation uses a hybrid hash-map front end (for the |
| first character) plus a TST: `tst_map`. This gives us a complexity of |
| |
| [:O(1 + log n+k-1)] |
| |
| This is found to be significantly faster than plain TST, albeit with a |
| bit more memory usage requirements (each slot in the hash-map is a TST |
| node). If you require a lot of symbols to be searched, use the `tst_map` |
| implementation. This can be done by using `tst_map` as the third |
| template parameter to the symbols class: |
| |
| symbols<Char, T, tst_map<Char, T> > sym; |
| |
| [heading Example] |
| |
| [note The test harness for the example(s) below is presented in the |
| __qi_basics_examples__ section.] |
| |
| Some using declarations: |
| |
| [reference_using_declarations_symbols] |
| |
| Symbols with data: |
| |
| [reference_symbols_with_data] |
| |
| When `symbols` is used for case-insensitive parsing (in a __qi_no_case__ |
| directive), added symbol strings should be in lowercase. Symbol strings |
| containing one or more uppercase characters will not match any input |
| when symbols is used in a `no_case` directive. |
| |
| [reference_symbols_with_no_case] |
| |
| |
| [endsect] [/ symbols] |
| |
| [endsect] [/ String] |
