TSDuck v3.38-3675
MPEG Transport Stream Toolkit
Loading...
Searching...
No Matches
ts::Enumeration Class Reference

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 , typename std::enable_if< std::is_integral< INTENUM >::value||std::is_enum< INTENUM >::value >::type * = nullptr>
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 , typename std::enable_if< std::is_integral< INTENUM >::value||std::is_enum< INTENUM >::value >::type * = nullptr>
bool getValue (INTENUM &e, const UString &name, bool caseSensitive=true, bool abbreviated=true) const
 Get the enumeration value from a name.
 
template<typename INT , typename std::enable_if< std::is_integral< INT >::value||std::is_enum< INT >::value >::type * = nullptr>
UString name (INT 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:

for (const auto& it : e) {
const int_t value(it.first); // the int value
const UString name(it.second); // the corresponding name
....
}
Enumeration of int/string pairs.
Definition tsEnumeration.h:38
UString name(INT value, bool hexa=false, size_t hexDigitCount=0) const
Get the name from an enumeration value.
Definition tsEnumeration.h:183
int int_t
Integer type used in representations of values.
Definition tsEnumeration.h:43
int_t value(const UString &name, bool caseSensitive=true, bool abbreviated=true) const
Get the value from a name.
An implementation of UTF-16 strings.
Definition tsUString.h:122

Constructor & Destructor Documentation

◆ Enumeration()

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

Constructor from a variable list of string/value pairs.

Parameters
[in]valuesVariable list of name/value pairs.

Member Function Documentation

◆ operator==()

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

Equality operator.

Parameters
[in]otherAnother 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 , typename std::enable_if< std::is_integral< INTENUM >::value||std::is_enum< INTENUM >::value >::type * = nullptr>
void ts::Enumeration::add ( const UString name,
INTENUM  value 
)
inline

Add a new enumeration value.

Template Parameters
INTENUMAn integer or enumeration type representing the values.
Parameters
[in]nameA string for a symbol.
[in]valueThe 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]nameThe 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]caseSensitiveIf 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]abbreviatedIf 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 , typename std::enable_if< std::is_integral< INTENUM >::value||std::is_enum< INTENUM >::value >::type * = nullptr>
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
INTENUMAn integer or enumeration type representing the values.
Parameters
[out]eThe 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]nameThe 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]caseSensitiveIf 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]abbreviatedIf 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]nameThe string to search.
[in]caseSensitiveIf false, the search is not case sensitive.
[in]abbreviatedIf true, any non-ambiguous abbreviation is valid.
[in]designatorHow to designate the name in the message (e.g. "name", "command", "option").
[in]prefixPrefix 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 INT , typename std::enable_if< std::is_integral< INT >::value||std::is_enum< INT >::value >::type * = nullptr>
UString ts::Enumeration::name ( INT  value,
bool  hexa = false,
size_t  hexDigitCount = 0 
) const
inline

Get the name from an enumeration value.

Template Parameters
INTAn integer or enumeration type.
Parameters
[in]valueAn enumeration value to search.
[in]hexaIf true and no name exists for value, return the value as an hexadecimal string with "0x" prefix instead of decimal.
[in]hexDigitCountWhen 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]valueA bit-mask, built from integer values in the Enumeration object.
[in]separatorThe separator to be used between values, a comma by default.
[in]hexaIf true and no name exists for a value, insert the value as an hexadecimal string with "0x" prefix instead of decimal.
[in]hexDigitCountWhen 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
CONTAINERA container class of integer values as defined by the C++ Standard Template Library (STL).
Parameters
[in]containerA container of integer values.
[in]separatorThe 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
ITERATORAn iterator class over integer values as defined by the C++ Standard Template Library (STL).
Parameters
[in]beginAn iterator pointing to the first value.
[in]endAn iterator pointing after the last value.
[in]separatorThe 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
CONTAINERA container class of strings as defined by the C++ Standard Template Library (STL).
Parameters
[out]namesA 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]separatorThe separator to be used between values, a comma by default.
[in]inQuoteOpening quote for each name.
[in]outQuoteClosing 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: