Representation of a set of translations between names for identifiers. More...

#include <tsNames.h>

Classes
struct	NameValue
	A structure used in the constructor of a Names instance. More...

class	RegisterExtensionFile
	A class to register additional names files to merge with the TSDuck names file. More...

class	Visitor
	A visitor interface class to be implemented by applications needing ranges of values. More...

Public Types
using	int_t = std::make_signed_t< uint_t >
	Signed integer type used in representations of values.

using	uint_t = std::uintmax_t
	Unsigned integer type used in representations of values.

Public Member Functions
	Names ()=default
	Default constructor.

	Names (const Names &other)
	Copy constructor.

	Names (Names &&other)
	Move constructor.

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

template<typename T > requires ts::int_enum<T>
void	add (const UString &name, T value)
	Add a new translation.

template<typename T1 , typename T2 > requires ts::int_enum<T1> && ts::int_enum<T2>
void	add (const UString &name, T1 first, T2 last)
	Add a new translation.

int_t	addNewValue (const UString &name)
	Add a translation from a given name to a new unique value.

template<typename T > requires ts::int_enum<T>
UString	bitMaskNames (T value, const UString &separator=u", ", bool hexa=false, size_t hex_digit_count=0) const
	Get the names from a bit-mask value.

size_t	bits () const
	Get the number of significant bits in values, when specified using "Bits = nn" in a ".names" file.

bool	contains (const UString &name, bool case_sensitive=true, bool abbreviated=false) const
	Check if a name exists in the section.

template<typename T > requires ts::int_enum<T>
bool	contains (T value) const
	Check if a name exists for a given value.

bool	empty () const
	Check if the list of names is empty.

UString	error (const UString &name, bool case_sensitive=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.

bool	freeRange (uint_t first, uint_t last) const
	Check if a range is free, ie no value is defined in the range.

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

template<typename T > requires ts::int_enum<T>
bool	getValue (T &e, const UString &name, bool case_sensitive=true, bool abbreviated=true) const
	Get the value from a name.

bool	isSigned () const
	Check if the list of values contains negative values from a signed integral type.

template<typename T > requires ts::int_enum<T>
UString	name (T value, bool hexa=false, size_t hex_digit_count=0) const
	Get the name from a value.

template<typename T1 , typename T2 = uint_t> requires ts::int_enum<T1> && ts::int_enum<T2>
UString	name (T1 value, NamesFlags flags, T2 alternate_value=0, size_t bits=0) const
	Get a fully formatted name from a value.

UString	nameList (const UString &separator=u", ", const UString &in_quote=UString(), const UString &out_quote=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.

template<typename T1 , typename T2 , typename T3 = uint_t> requires ts::int_enum<T1> && ts::int_enum<T2> && ts::int_enum<T3>
UString	nameWithFallback (T1 value1, T2 value2, NamesFlags flags, T3 alternate_value=0, size_t bits=0) const
	Get a fully formatted name from a value, with alternate fallback value.

Names &	operator= (const Names &other)
	Copy assignment.

Names &	operator= (Names &&other)
	Move assignment.

const UString &	sectionName () const
	Get the section name of this instance when it was loaded from a ".names" file.

void	subscribe (Visitor *visitor)
	Subscribe to all new values which will be merged into this Names instance.

void	unsubscribe (Visitor *visitor)
	Unsubscribe from all new values which will be merged into this Names instance.

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

size_t	visit (Visitor *visitor) const
	Get all values in this Names instance.

size_t	visit (Visitor *visitor, uint_t value) const
	Get all extended values of a specified value in this Names instance.

Static Public Member Functions
static UString	Format (uint_t value, const UString &name, NamesFlags flags, size_t bits, uint_t alternate_value=0)
	Format a name using flags.

static NamesPtr	GetSection (const UString &file_name, const UString &section_name, bool create)
	Get the Names instance for a specified section of a ".names" file.

static bool	MergeFile (const UString &file_name)
	Load a ".names" file and merge its content into all loaded Names instances.

Static Public Attributes
static constexpr int_t	UNKNOWN = std::numeric_limits<int_t>::max()
	This value means "not found".

Detailed Description

Representation of a set of translations between names for identifiers.

An instance of Names contains a consistent set of translations for one type of identifier. Identifiers are integer values of any integral or enumeration type. Translations can be performed in both directions, from name to identifier or from identifier to name.

When translating from name to identifier value:

The string values can be abbreviated up to the shortest unambiguous string within that set of translations.
The strings can be case sensitive or not.
Several strings may translate to the same value.

When translating from identifier to name, various types of formatting are possible. See the enum class NamesFlags.

An instance of Names can be used to define values for command line arguments or XML elements and attributes.

An instance of Names can be manually constructed in the code, either using a list of name / identifier pairs in the constructor, or adding translations one by one, or both.

Example:

ts::Names e({{u"FirstElement", -1}, {u"SecondElement", 7}, {u"LastElement", 458}});

e.add(u"Other", 48);

ts::Names

Representation of a set of translations between names for identifiers.

Definition tsNames.h:102

ts::Names::add

void add(const UString &name, T value)

Add a new translation.

Definition tsNames.h:248

An instance of Names can also be constructed from a section of a ".names" file. See the method Names::MergeFile() for the designation method for ".names" files. All ".names" files are loaded in a global repository of sections.

If sections with the same name are loaded from different files, their content are merged. This is how "TSDuck extensions" can add their own identifiers to TSDuck-provided names. It is possible to query a section by name, returning a shared pointer to the corresponding instance of Names. It is also possible to directly translate a value into a name using the non-member functions NameFromSection() and NameFromSectionWithFallback().

The integer type for the identifier is the largest signed or unsigned integer in the system (in practice, this is 64 bits). To avoid making the whole class a template one, the internal storage of identifiers use the unsigned type but values can be added and retrieved in signed format. An instance is globally marked as "signed" or "unsigned". Initially, a Names instance is "unsigned". As soon as one negative value of a signed type is added, the Names instance is marked "signed" and stays so.

See also: NamesFlags; Args; xml::Element

Constructor & Destructor Documentation

◆ Names() [1/3]

ts::Names::Names ( const Names & other )

Copy constructor.

Parameters

[in] other Other instance to copy.

◆ Names() [2/3]

ts::Names::Names ( Names && other )

Move constructor.

Parameters

[in] other Other instance to move.

◆ Names() [3/3]

ts::Names::Names ( 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=() [1/2]

Names & ts::Names::operator= ( const Names & other )

Copy assignment.

Parameters

[in] other Other instance to copy.

Returns: A reference to this object.

◆ operator=() [2/2]

Names & ts::Names::operator= ( Names && other )

Move assignment.

Parameters

[in] other Other instance to move.

Returns: A reference to this object.

◆ empty()

bool ts::Names::empty ( ) const

inline

Check if the list of names is empty.

Returns: True if the list of names is empty.

◆ isSigned()

bool ts::Names::isSigned ( ) const

inline

Check if the list of values contains negative values from a signed integral type.

Returns: True if the list of values contains negative values from a signed integral type.

◆ bits()

size_t ts::Names::bits ( ) const

inline

Get the number of significant bits in values, when specified using "Bits = nn" in a ".names" file.

Returns: The number of significant bits in values. Zero means unspecified.

◆ sectionName()

const UString & ts::Names::sectionName ( ) const

inline

Get the section name of this instance when it was loaded from a ".names" file.

Returns: A constant reference to the section name or the empty string if not loaded from a ".names" file.

◆ add() [1/2]

template<typename T >
requires ts::int_enum<T>

void ts::Names::add	(	const UString &	name,
		T	value
	)

inline

Add a new translation.

Parameters

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

◆ add() [2/2]

template<typename T1 , typename T2 >
requires ts::int_enum<T1> && ts::int_enum<T2>

void ts::Names::add	(	const UString &	name,
		T1	first,
		T2	last
	)

inline

Add a new translation.

Parameters

[in]	name	A string for a symbol.
[in]	first	First value for the name.
[in]	last	Last value for the name.

◆ addNewValue()

int_t ts::Names::addNewValue ( const UString & name )

Add a translation from a given name to a new unique value.

Parameters

[in] name A string for a symbol.

Returns: The corresponding new unique integer value or UNKNOWN if no new value is available.

◆ freeRange()

bool ts::Names::freeRange	(	uint_t	first,
		uint_t	last
	)		const

Check if a range is free, ie no value is defined in the range.

Parameters

[in]	first	First value in the range to check.
[in]	last	Last value in the range to check.

Returns: True if no value is assigned in the first to last range.

◆ contains() [1/2]

bool ts::Names::contains	(	const UString &	name,
		bool	case_sensitive = `true`,
		bool	abbreviated = `false`
	)		const

inline

Check if a name exists in the section.

Parameters

[in]	name	The string to search.
[in]	case_sensitive	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 if name exists in the section.

◆ value()

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

Get the signed 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]	case_sensitive	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 first 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 T >
requires ts::int_enum<T>

bool ts::Names::getValue	(	T &	e,
		const UString &	name,
		bool	case_sensitive = `true`,
		bool	abbreviated = `true`
	)		const

Get the value from a name.

Parameters

[out]	e	The value corresponding to name. 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]	case_sensitive	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.

◆ contains() [2/2]

template<typename T >
requires ts::int_enum<T>

bool ts::Names::contains ( T value ) const

inline

Check if a name exists for a given value.

Parameters

[in] value Value to get the name for.

Returns: True if a name exists for value.

◆ name() [1/2]

template<typename T >
requires ts::int_enum<T>

UString ts::Names::name	(	T	value,
		bool	hexa = `false`,
		size_t	hex_digit_count = `0`
	)		const

inline

Get the name from a value.

Parameters

[in]	value	A 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]	hex_digit_count	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.

◆ name() [2/2]

template<typename T1 , typename T2 = uint_t>
requires ts::int_enum<T1> && ts::int_enum<T2>

UString ts::Names::name	(	T1	value,
		NamesFlags	flags,
		T2	alternate_value = `0`,
		size_t	bits = `0`
	)		const

inline

Get a fully formatted name from a value.

Parameters

[in]	value	A value to search.
[in]	flags	Presentation flags.
[in]	alternate_value	Display this integer value if flags ALTERNATE is set.
[in]	bits	Optional size in bits of the displayed data. Used in replacement of the "Bits=XX" directive in the .names file.

Returns: The corresponding name.

◆ nameWithFallback()

template<typename T1 , typename T2 , typename T3 = uint_t>
requires ts::int_enum<T1> && ts::int_enum<T2> && ts::int_enum<T3>

UString ts::Names::nameWithFallback	(	T1	value1,
		T2	value2,
		NamesFlags	flags,
		T3	alternate_value = `0`,
		size_t	bits = `0`
	)		const

inline

Get a fully formatted name from a value, with alternate fallback value.

Parameters

[in]	value1	A value to search.
[in]	value2	Alternate value if no name is found for value1.
[in]	flags	Presentation flags.
[in]	alternate_value	Display this integer value if flags ALTERNATE is set.
[in]	bits	Optional size in bits of the displayed data. Used in replacement of the "Bits=XX" directive in the .names file.

Returns: The corresponding name.

◆ GetSection()

static NamesPtr ts::Names::GetSection	(	const UString &	file_name,
		const UString &	section_name,
		bool	create
	)

inlinestatic

Get the Names instance for a specified section of a ".names" file.

Parameters

[in]	file_name	Name of the ".names" file. This is typically a short name. See MergeFile() for details. If empty, only search in already loaded sections.
[in]	section_name	Name of section to search. Not case-sensitive.
[in]	create	If true, create the section if it does not exist.

Returns: A shared pointer to the Names instance for the section. Return null if the section does not exist and create is false.

See also: MergeFile()

◆ bitMaskNames()

template<typename T >
requires ts::int_enum<T>

UString ts::Names::bitMaskNames	(	T	value,
		const UString &	separator = `u", "`,
		bool	hexa = `false`,
		size_t	hex_digit_count = `0`
	)		const

inline

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 Names 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]	hex_digit_count	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::Names::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::Names::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::Names::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::Names::nameList	(	const UString &	separator = `u", "`,
		const UString &	in_quote = `UString()`,
		const UString &	out_quote = `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]	in_quote	Opening quote for each name.
[in]	out_quote	Closing quote for each name.

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

◆ error()

UString ts::Names::error	(	const UString &	name,
		bool	case_sensitive = `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]	case_sensitive	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.

◆ visit() [1/2]

size_t ts::Names::visit ( Visitor * visitor ) const

Get all values in this Names instance.

Parameters

[in,out] visitor An instance of a subclass of Visitor which receives all values.

Returns: The number of visited values.

◆ visit() [2/2]

size_t ts::Names::visit	(	Visitor *	visitor,
		uint_t	value
	)		const

Get all extended values of a specified value in this Names instance.

In a ".names" file, all sections shall have a nominal width, "Bits=8" for instance. However, when the section has "Extended=true", "extended" values can be provided. With "Bits=8", the value 0x00AA, 0x01AA, or 0xFFAA, are all extended values for the base 8-bit value 0xAA, as an example.

Parameters

[in,out]	visitor	An instance of a subclass of Visitor which receives all extended values for value.
[in]	value	The base value to get extended values for.

Returns: The number of visited values.

◆ subscribe()

void ts::Names::subscribe ( Visitor * visitor )

Subscribe to all new values which will be merged into this Names instance.

Parameters

[in,out] visitor An instance of a subclass of Visitor which will receive all new values.

◆ unsubscribe()

void ts::Names::unsubscribe ( Visitor * visitor )

Unsubscribe from all new values which will be merged into this Names instance.

Parameters

[in,out] visitor An instance of a subclass of Visitor to unsubscribe. If null, remove all visitors.

◆ Format()

static UString ts::Names::Format	(	uint_t	value,
		const UString &	name,
		NamesFlags	flags,
		size_t	bits,
		uint_t	alternate_value = `0`
	)

static

Format a name using flags.

Parameters

[in]	value	Value for the name.
[in]	name	Name for the value. If empty, there is no name for value.
[in]	flags	Presentation flags.
[in]	bits	Nominal size in bits of the data.
[in]	alternate_value	Display this integer value instead of value if flag ALTERNATE is set.

Returns: The corresponding name.

◆ MergeFile()

static bool ts::Names::MergeFile ( const UString & file_name )

inlinestatic

Load a ".names" file and merge its content into all loaded Names instances.

Parameters

[in] file_name Configuration file name. Typically without directory name. Without directory, the file is automatically searched in the TSDuck configuration directory. If the file is not found, try with ".names" suffix and then "tsduck." prefix. For instance, when file_name is "foo", the configuration directories are searched for files "foo", "foo.names" and "tsduck.foo.names" until one is found.

Returns: True on success, false on error.

Member Data Documentation

◆ UNKNOWN

constexpr int_t ts::Names::UNKNOWN = std::numeric_limits<int_t>::max()

staticconstexpr

This value means "not found".

It is returned by methods which search a signed integer value.

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

tsNames.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Names() [1/3]

◆ Names() [2/3]

◆ Names() [3/3]

Member Function Documentation

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ empty()

◆ isSigned()

◆ bits()

◆ sectionName()

◆ add() [1/2]

◆ add() [2/2]

◆ addNewValue()

◆ freeRange()

◆ contains() [1/2]

◆ value()

◆ getValue()

◆ contains() [2/2]

◆ name() [1/2]

◆ name() [2/2]

◆ nameWithFallback()

◆ GetSection()

◆ bitMaskNames()

◆ names() [1/2]

◆ names() [2/2]

◆ getAllNames()

◆ nameList()

◆ error()

◆ visit() [1/2]

◆ visit() [2/2]

◆ subscribe()

◆ unsubscribe()

◆ Format()

◆ MergeFile()

Member Data Documentation

◆ UNKNOWN