#include <Lexicon.h>
Classes | |
| class | base_iterator |
| Common features of container iterators. More... | |
| struct | Definition |
| struct | Item |
| class | name_iterator |
| struct | NameDefaultVisitor |
Visitor functor for handling NameDefault. More... | |
| class | value_iterator |
| struct | ValueDefaultVisitor |
Visitor functor for handling ValueDefault. More... | |
Public Types | |
| using | Pair = detail::lexicon_pair_type<E> |
| using | UnknownValueHandler = std::function<TextView(E)> |
| using | UnknownNameHandler = std::function<E(TextView)> |
| using | Default = std::variant<std::monostate, E, TextView, UnknownNameHandler, UnknownValueHandler> |
| using | with = std::initializer_list<Pair> const & |
| using | with_multi = std::initializer_list<Definition> const & |
| using | const_iterator = value_iterator |
| Iterator over values (each with a primary name). | |
| using | iterator = const_iterator |
Public Member Functions | |
| Lexicon () | |
| Construct empty instance. | |
| Lexicon (with_multi items, Default handler_1=Default{}, Default handler_2=Default{}) | |
| Lexicon (with items, Default handler_1=Default{}, Default handler_2=Default{}) | |
| Lexicon (Default handler_1, Default handler_2=Default{}) | |
| Lexicon (self_type &&that)=default | |
| TextView | operator[] (E const &value) const |
| E | operator[] (TextView const &name) const |
| template<typename... Args> | |
| self_type & | define (E value, Args &&...names) |
| self_type & | define (E value, const std::initializer_list< TextView > &names) |
| self_type & | define (const Pair &pair) |
| self_type & | define (const Definition &init) |
| self_type & | set_default (Default const &handler) |
| size_t | count () const |
| Get the number of values with definitions. | |
| const_iterator | begin () const |
| Iteration begin. | |
| const_iterator | end () const |
| Iteration end. | |
| name_iterator | begin_names () const |
| Iteration over names - every value/name pair. | |
| name_iterator | end_names () const |
| Iteration over names - every value/name pair. | |
| ByNameHelper | by_names () const |
| template<typename... Args> | |
| auto | define (E value, Args &&...names) -> self_type & |
Static Public Attributes | |
| static constexpr auto | VALUE_IDX = 0 |
Index in Pair for the enumeration value. | |
| static constexpr auto | NAME_IDX = 1 |
Index in Pair for name. | |
Protected Types | |
| using | NameDefault = std::variant<std::monostate, std::string_view, UnknownValueHandler> |
| Handle providing a default name. | |
| using | ValueDefault = std::variant<std::monostate, E, UnknownNameHandler> |
| Handle providing a default value. | |
Protected Member Functions | |
| TextView | localize (TextView const &name) |
| Copy name in to local storage. | |
Protected Attributes | |
| MemArena | _arena {1024} |
| Storage for names. | |
| IntrusiveHashMap< typename Item::NameLinkage > | _by_name |
| Access by name. | |
| IntrusiveHashMap< typename Item::ValueLinkage > | _by_value |
| Access by value. | |
| NameDefault | _name_default |
| Name to return if no value not found. | |
| ValueDefault | _value_default |
| Value to return if name not found. | |
Detailed Description
class swoc::Lexicon< E >
A bidirectional mapping between names and enumeration values.
This is intended to be a support class to make interacting with enumerations easier for configuration and logging. Names and enumerations can then be easily and reliably interchanged. The names are case insensitive but preserving.
Each enumeration has a primary name and an arbitrary number of secondary names. When converting from an enumeration, the primary name is used. However, any of the names will be converted to the enumeration. For instance, a Lexicon for a boolean might have the primary name of TRUE be "true" with the secondary names "1", "yes", "enable". In that case converting TRUE would always be "true", while converting any of "true", "1", "yes", or "enable" would yield TRUE. This is convenient for parsing configurations to be more tolerant of input.
The constructors are a bit baroque, but this is necessary in order to be able to declare constant instances of the Lexicon. If this isn't necessary, everything that can be done via the constructor can be done with other methods. The implementation of the constructors consists entirely of calls to define and set_default, the only difference is these methods can be called on a const instance from there.
- Note
- All names and value must be unique across the Lexicon. All name comparisons are case insensitive.
Member Typedef Documentation
◆ const_iterator
| using swoc::Lexicon< E >::const_iterator = value_iterator |
◆ Default
| using swoc::Lexicon< E >::Default = std::variant<std::monostate, E, TextView, UnknownNameHandler, UnknownValueHandler> |
◆ iterator
| using swoc::Lexicon< E >::iterator = const_iterator |
◆ NameDefault
|
protected |
◆ Pair
| using swoc::Lexicon< E >::Pair = detail::lexicon_pair_type<E> |
◆ UnknownNameHandler
| using swoc::Lexicon< E >::UnknownNameHandler = std::function<E(TextView)> |
◆ UnknownValueHandler
| using swoc::Lexicon< E >::UnknownValueHandler = std::function<TextView(E)> |
A function to be called if a value is not found to provide a default name.
- Parameters
-
value The value.
- Returns
- A name for the value.
The name is return by view and therefore managing the lifetime of the name is problematic. Generally it should be process lifetime, unless some other shorter lifetime can be managed without a destructor being called. Unfortunately this can't be done any better without imposing memory management costs on normal use.
◆ ValueDefault
|
protected |
◆ with
| using swoc::Lexicon< E >::with = std::initializer_list<Pair> const & |
◆ with_multi
| using swoc::Lexicon< E >::with_multi = std::initializer_list<Definition> const & |
Constructor & Destructor Documentation
◆ Lexicon() [1/4]
| swoc::Lexicon< E >::Lexicon | ( | ) |
◆ Lexicon() [2/4]
|
explicit |
Construct with names, possible secondary values, and optional default handlers.
- Parameters
-
items A list of initializers, each of which is a name and a list of values. handler_1 A default handler. handler_2 A default hander.
Each item in the intializers must be a Definition, that is a name and a list of values. The first value is the primary value and is required. Subsequent values are optional and become secondary values.
The default handlers are optional can be omitted. If so, exceptions are thrown when values or names not in the Lexicon are used. See set_default for more details.
- See also
- set_default.
◆ Lexicon() [3/4]
|
explicit |
Construct with names / value pairs, and optional default handlers.
- Parameters
-
items A list of initializers, each of which is a name and a list of values. handler_1 A default handler. handler_2 A default handler.
Each item in the intializers must be a Pair, that is a name and a value.
The default handlers are optional can be omitted. If so, exceptions are thrown when values or names not in the Lexicon are used. See set_default for more details.
- See also
- set_default.
◆ Lexicon() [4/4]
|
explicit |
Construct with only default values / handlers.
- Parameters
-
handler_1 A default handler. handler_2 A default handler.
handler_2 is optional can be omitted. The argument values are the same as for set_default.
- See also
- set_default.
Member Function Documentation
◆ begin()
| auto swoc::Lexicon< E >::begin | ( | ) | const |
◆ begin_names()
|
inline |
◆ by_names()
|
inline |
Enable container iteration by name. The return value is a tempoary of indeterminate type that provides begin and end methods which return name based iterators for this. This is useful for container based iteration. E.g. to iterate over all of the value/name pairs,
- Returns
- Temporary.
◆ count()
| size_t swoc::Lexicon< E >::count | ( | ) | const |
◆ define() [1/5]
| auto swoc::Lexicon< E >::define | ( | const Definition & | init | ) |
Define a name with a primary and secondary values.
- Parameters
-
init The Definitionwith the name and values.
- Returns
- this.
This defines the name, with the first value in the value list becoming the primary value and subsequent values (if any) being the secondary values. A primary value is required but secondary values are not. This is to make it possible to define all values in this style even if some do not have secondary values.
◆ define() [2/5]
| auto swoc::Lexicon< E >::define | ( | const Pair & | pair | ) |
◆ define() [3/5]
| self_type & swoc::Lexicon< E >::define | ( | E | value, |
| Args &&... | names ) |
Define the names for a value. The first name is the primary name. All names must be convertible to std::string_view. lexicon.define(Value, primary, [secondary, ... ]);
◆ define() [4/5]
| auto swoc::Lexicon< E >::define | ( | E | value, |
| Args &&... | names ) -> self_type & |
◆ define() [5/5]
| auto swoc::Lexicon< E >::define | ( | E | value, |
| const std::initializer_list< TextView > & | names ) |
◆ end()
| auto swoc::Lexicon< E >::end | ( | ) | const |
◆ end_names()
|
inline |
◆ localize()
|
protected |
◆ operator[]() [1/2]
| TextView swoc::Lexicon< E >::operator[] | ( | E const & | value | ) | const |
◆ operator[]() [2/2]
| E swoc::Lexicon< E >::operator[] | ( | TextView const & | name | ) | const |
◆ set_default()
| auto swoc::Lexicon< E >::set_default | ( | Default const & | handler | ) |
Set default handler.
- Parameters
-
handler The handler.
- Returns
- this.
The handler can be of various types.
- An enumeration value. This sets the default value handler to return that value for any name not found.
- A
string_view. The sets the default name handler to return thestring_viewas the name for any value not found. - A
DefaultNameHandler. This is a functor that takes an enumeration value parameter and returns astring_viewas the name for any value that is not found. - A
DefaultValueHandler. This is a functor that takes a name as astring_viewand returns an enumeration value as the value for any name that is not found.
Member Data Documentation
◆ _arena
|
protected |
◆ _by_name
|
protected |
◆ _by_value
|
protected |
◆ _name_default
|
protected |
◆ _value_default
|
protected |
◆ NAME_IDX
|
staticconstexpr |
◆ VALUE_IDX
|
staticconstexpr |
The documentation for this class was generated from the following file:
Generated by
1.13.2