Enumeration of int/string pairs. More...

#include <tsEnumeration.h>

Classes
struct	NameValue
	A structure used in the constructor of an Enumeration. More...

Public Types
using	const_iterator = std::multimap< int_t, UString >::const_iterator
	A constant iterator type for the content of the object.

using	int_t = int
	Integer type used in representations of values.

Public Member Functions
	Enumeration ()=default
	Default constructor.

	Enumeration (std::initializer_list< NameValue > values)
	Constructor from a variable list of string/value pairs.

template<typename INTENUM > requires std::integral<INTENUM> \|\| std::is_enum_v<INTENUM>
void	add (const UString &name, INTENUM value)
	Add a new enumeration value.

const_iterator	begin () const
	Return an iterator pointing to the first element of this object.

UString	bitMaskNames (int_t value, const UString &separator=u", ", bool hexa=false, size_t hexDigitCount=0) const
	Get the names from a bit-mask value.

bool	empty () const
	Check if the enumeration is empty.

const_iterator	end () const
	Return an iterator pointing after the last element of this object.

UString	error (const UString &name, bool caseSensitive=true, bool abbreviated=true, const UString &designator=u"name", const UString &prefix=UString()) const
	Get the error message about a name failing to match a value.

template<class CONTAINER >
void	getAllNames (CONTAINER &names) const
	Get all possible names in a string container.

template<typename INTENUM > requires std::integral<INTENUM> \|\| std::is_enum_v<INTENUM>
bool	getValue (INTENUM &e, const UString &name, bool caseSensitive=true, bool abbreviated=true) const
	Get the enumeration value from a name.

template<typename INTENUM > requires std::integral<INTENUM> \|\| std::is_enum_v<INTENUM>
UString	name (INTENUM value, bool hexa=false, size_t hexDigitCount=0) const
	Get the name from an enumeration value.

UString	nameList (const UString &separator=u", ", const UString &inQuote=UString(), const UString &outQuote=UString()) const
	Return a comma-separated list of all possible names.

template<class CONTAINER >
UString	names (const CONTAINER &container, const UString &separator=u", ") const
	Return a comma-separated list of all names for a list of integer values.

template<class ITERATOR >
UString	names (ITERATOR begin, ITERATOR end, const UString &separator=u", ") const
	Return a comma-separated list of all names for a list of integer values.

bool	operator== (const Enumeration &other) const
	Equality operator.

size_t	size () const
	Get the number of entries in the enumeration.

int_t	value (const UString &name, bool caseSensitive=true, bool abbreviated=true) const
	Get the value from a name.

Static Public Attributes
static const int_t	UNKNOWN
	This value means "not found".

Detailed Description

Enumeration of int/string pairs.

This class is used to manage enumeration values. Here, by enumeration, we mean an association between strings and integers. The strings are manipulated as external values (command line parameters, report output, etc.) and the integers are manipulated as internal values. This class performs the association between these internal and external values.

Some interesting features are:

When provided as input, the string values can be abbreviated up to the shortest unambiguous string.
The strings can be case sensitive or not.
Several strings may have the same value.

Member Typedef Documentation

◆ const_iterator

using ts::Enumeration::const_iterator = std::multimap<int_t, UString>::const_iterator

A constant iterator type for the content of the object.

An iterator points to a pair of integer and string representing an element of the enumeration or more formally to a std::pair<int_t, UString>.

Sample usage:

ts::Enumeration e (...);
 
for (const auto& it : e) {
    const int_t value(it.first);     // the int value
    const UString name(it.second);   // the corresponding name
    ....
}

Constructor & Destructor Documentation

◆ Enumeration()

ts::Enumeration::Enumeration ( std::initializer_list< NameValue > values )

Constructor from a variable list of string/value pairs.

Parameters

[in] values Variable list of name/value pairs.

Member Function Documentation

◆ operator==()

bool ts::Enumeration::operator== ( const Enumeration & other ) const

inline

Equality operator.

Parameters

[in] other Another instance to compare with.

Returns: True if this object has the same content as other, false otherwise.

◆ size()

size_t ts::Enumeration::size ( ) const

inline

Get the number of entries in the enumeration.

Returns: The number of entries in the enumeration.

◆ empty()

bool ts::Enumeration::empty ( ) const

inline

Check if the enumeration is empty.

Returns: True if the enumeration is empty.

◆ add()

template<typename INTENUM >
requires std::integral<INTENUM> || std::is_enum_v<INTENUM>

void ts::Enumeration::add	(	const UString &	name,
		INTENUM	value
	)

inline

Add a new enumeration value.

Template Parameters

INTENUM An integer or enumeration type representing the values.

Parameters

[in]	name	A string for a symbol.
[in]	value	The corresponding integer value.

◆ value()

int_t ts::Enumeration::value	(	const UString &	name,
		bool	caseSensitive = `true`,
		bool	abbreviated = `true`
	)		const

Get the value from a name.

Parameters

[in]	name	The string to search. This string may also contain an integer value in decimal or hexadecimal representation in which case this integer value is returned.
[in]	caseSensitive	If false, the search is not case sensitive and name may match an equivalent string with distinct letter case. If true (the default), an exact match is required.
[in]	abbreviated	If true (the default), any non-ambiguous abbreviation is valid. If false, a full name string must be provided.

Returns: The integer value corresponding to name or UNKNOWN if not found or ambiguous, unless name can be interpreted as an integer value. If multiple integer values were registered with the same name, one of them is returned but which one is returned is unspecified.

◆ getValue()

template<typename INTENUM >
requires std::integral<INTENUM> || std::is_enum_v<INTENUM>

bool ts::Enumeration::getValue	(	INTENUM &	e,
		const UString &	name,
		bool	caseSensitive = `true`,
		bool	abbreviated = `true`
	)		const

Get the enumeration value from a name.

Template Parameters

INTENUM An integer or enumeration type representing the values.

Parameters

[out]	e	The enumeration value. Unmodified if name is not valid. If multiple integer values were registered with the same name, one of them is returned but which one is returned is unspecified.
[in]	name	The string to search. This string may also contain an integer value in decimal or hexadecimal representation in which case this integer value is returned.
[in]	caseSensitive	If false, the search is not case sensitive and name may match an equivalent string with distinct letter case. If true (the default), an exact match is required.
[in]	abbreviated	If true (the default), any non-ambiguous abbreviation is valid. If false, a full name string must be provided.

Returns: True on success, false if name is not found or ambiguous, unless name can be interpreted as an integer value.

◆ error()

UString ts::Enumeration::error	(	const UString &	name,
		bool	caseSensitive = `true`,
		bool	abbreviated = `true`,
		const UString &	designator = `u"name"`,
		const UString &	prefix = `UString()`
	)		const

Get the error message about a name failing to match a value.

Parameters

[in]	name	The string to search.
[in]	caseSensitive	If false, the search is not case sensitive.
[in]	abbreviated	If true, any non-ambiguous abbreviation is valid.
[in]	designator	How to designate the name in the message (e.g. "name", "command", "option").
[in]	prefix	Prefix to prepend each candidate in case of ambiguous name.

Returns: The corresponding error message or an empty string is there is no error.

◆ name()

template<typename INTENUM >
requires std::integral<INTENUM> || std::is_enum_v<INTENUM>

UString ts::Enumeration::name	(	INTENUM	value,
		bool	hexa = `false`,
		size_t	hexDigitCount = `0`
	)		const

inline

Get the name from an enumeration value.

Template Parameters

INTENUM An integer or enumeration type.

Parameters

[in]	value	An enumeration value to search.
[in]	hexa	If true and no name exists for value, return the value as an hexadecimal string with "0x" prefix instead of decimal.
[in]	hexDigitCount	When an hexadecimal value is returned, specify the minimum number of digits.

Returns: The corresponding string or a numeric representation of value if not found. If several names were registered with the same value, one of them is returned but which one is returned is unspecified.

◆ bitMaskNames()

UString ts::Enumeration::bitMaskNames	(	int_t	value,
		const UString &	separator = `u", "`,
		bool	hexa = `false`,
		size_t	hexDigitCount = `0`
	)		const

Get the names from a bit-mask value.

The method is useful only when the integer values in the enumeration are bit-masks.

Parameters

[in]	value	A bit-mask, built from integer values in the Enumeration object.
[in]	separator	The separator to be used between values, a comma by default.
[in]	hexa	If true and no name exists for a value, insert the value as an hexadecimal string with "0x" prefix instead of decimal.
[in]	hexDigitCount	When an hexadecimal value is returned, specify the minimum number of digits.

Returns: The corresponding string containing a list of names. If several names were registered with the same value, all of them are inserted in the string.

◆ names() [1/2]

template<class CONTAINER >

UString ts::Enumeration::names	(	const CONTAINER &	container,
		const UString &	separator = `u", "`
	)		const

inline

Return a comma-separated list of all names for a list of integer values.

Template Parameters

CONTAINER A container class of integer values as defined by the C++ Standard Template Library (STL).

Parameters

[in]	container	A container of integer values.
[in]	separator	The separator to be used between values, a comma by default.

Returns: A comma-separated list of the names for the integer values in container. Each value is formatted according to name().

◆ names() [2/2]

template<class ITERATOR >

UString ts::Enumeration::names	(	ITERATOR	begin,
		ITERATOR	end,
		const UString &	separator = `u", "`
	)		const

Return a comma-separated list of all names for a list of integer values.

The values are accessed through iterators in a container.

Template Parameters

ITERATOR An iterator class over integer values as defined by the C++ Standard Template Library (STL).

Parameters

[in]	begin	An iterator pointing to the first value.
[in]	end	An iterator pointing after the last value.
[in]	separator	The separator to be used between values, a comma by default.

Returns: A comma-separated list of the names for the integer values in container. Each value is formatted according to name().

◆ getAllNames()

template<class CONTAINER >

void ts::Enumeration::getAllNames ( CONTAINER & names ) const

Get all possible names in a string container.

Template Parameters

CONTAINER A container class of strings as defined by the C++ Standard Template Library (STL).

Parameters

[out] names A container of strings.

◆ nameList()

UString ts::Enumeration::nameList	(	const UString &	separator = `u", "`,
		const UString &	inQuote = `UString()`,
		const UString &	outQuote = `UString()`
	)		const

Return a comma-separated list of all possible names.

Parameters

[in]	separator	The separator to be used between values, a comma by default.
[in]	inQuote	Opening quote for each name.
[in]	outQuote	Closing quote for each name.

Returns: A comma-separated list of all possible names.

◆ begin()

const_iterator ts::Enumeration::begin ( ) const

inline

Return an iterator pointing to the first element of this object.

Returns: An iterator pointing to the first element of this object.

◆ end()

const_iterator ts::Enumeration::end ( ) const

inline

Return an iterator pointing after the last element of this object.

Returns: An iterator pointing after the last element of this object.

Member Data Documentation

◆ UNKNOWN

const int_t ts::Enumeration::UNKNOWN

static

This value means "not found".

It is returned by methods which search an integer value.

The documentation for this class was generated from the following file:

tsEnumeration.h

Classes

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ const_iterator

Constructor & Destructor Documentation

◆ Enumeration()

Member Function Documentation

◆ operator==()

◆ size()

◆ empty()

◆ add()

◆ value()

◆ getValue()

◆ error()

◆ name()

◆ bitMaskNames()

◆ names() [1/2]

◆ names() [2/2]

◆ getAllNames()

◆ nameList()

◆ begin()

◆ end()

Member Data Documentation

◆ UNKNOWN