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

Representation of an ATSC multiple_string_structure. More...

#include <tsATSCMultipleString.h>

Public Member Functions

 ATSCMultipleString ()=default
 Default constructor.
 
 ATSCMultipleString (const UString &language, const UString &text)
 Constructor with one string.
 
void add (const UString &language, const UString &text)
 Add a new string.
 
bool append (size_t index, const UString &text)
 Append text to an existing string.
 
void clear ()
 Clear all strings.
 
bool deserialize (DuckContext &duck, const uint8_t *&buffer, size_t &buffer_size, size_t mss_size=NPOS, bool ignore_empty=false)
 Deserialize a binary multiple_string_structure.
 
bool empty () const
 Check if this instance has strings.
 
bool fromXML (DuckContext &duck, const xml::Element *elem)
 Decode an XML structure and assign the result to this instance.
 
bool fromXML (DuckContext &duck, const xml::Element *parent, const UString &name, bool required)
 Decode an XML structure and assign the result to this instance.
 
bool hasLanguage (const UString &language) const
 Check if a given language is present.
 
UString language (size_t index=0) const
 Get the language of the specified string (first string by default).
 
bool lengthDeserialize (DuckContext &duck, const uint8_t *&buffer, size_t &buffer_size, size_t length_bytes=1)
 Deserialize a binary multiple_string_structure with a leading length field.
 
size_t lengthSerialize (DuckContext &duck, ByteBlock &data, size_t length_bytes=1) const
 Serialize a binary multiple_string_structure and append to a byte block with a leading length field.
 
size_t lengthSerialize (DuckContext &duck, uint8_t *&data, size_t &size, size_t length_bytes=1) const
 Serialize a binary multiple_string_structure with a leading length field.
 
void reserve (size_t count)
 Allocate the appropriate memory for a target number of strings.
 
void resize (size_t count)
 Set the number of strings in this instance.
 
size_t searchLanguage (const UString &language) const
 Search the first string with a given language.
 
size_t serialize (DuckContext &duck, ByteBlock &data, size_t max_size=NPOS, bool ignore_empty=false) const
 Serialize a binary multiple_string_structure and append to a byte block.
 
size_t serialize (DuckContext &duck, uint8_t *&data, size_t &size, size_t max_size=NPOS, bool ignore_empty=false) const
 Serialize a binary multiple_string_structure.
 
bool set (size_t index, const UString &language, const UString &text)
 Set the value of an existing string.
 
size_t size () const
 Get the number of strings in this instance.
 
UString text (const UString &language=UString()) const
 Get the concatenation of all texts of the specified language.
 
UString text (size_t index) const
 Get the text of the specified string.
 
xml::ElementtoXML (DuckContext &duck, xml::Element *parent, const UString &name, bool ignore_empty) const
 Convert to an XML structure.
 

Static Public Member Functions

static void Display (TablesDisplay &display, const UString &title, const UString &margin, const uint8_t *&buffer, size_t &buffer_size, size_t mss_size=NPOS)
 A static method to display a binary multiple_string_structure.
 

Detailed Description

Representation of an ATSC multiple_string_structure.

An ATSC multiple_string_structure is a set of strings. Each string has a language code and a compression mode. In this implementation, we only support non-compressed text.

See also
ATSC A/65, section 6.10.

Constructor & Destructor Documentation

◆ ATSCMultipleString()

ts::ATSCMultipleString::ATSCMultipleString ( const UString language,
const UString text 
)

Constructor with one string.

Parameters
[in]language3-character ISO-639 language code.
[in]textText string.

Member Function Documentation

◆ empty()

bool ts::ATSCMultipleString::empty ( ) const
inline

Check if this instance has strings.

Returns
True if there is no string in this instance.

◆ size()

size_t ts::ATSCMultipleString::size ( ) const
inline

Get the number of strings in this instance.

Returns
The number of strings in this instance.

◆ resize()

void ts::ATSCMultipleString::resize ( size_t  count)
inline

Set the number of strings in this instance.

Parameters
[in]countThe new number of strings. Either truncate current list of strings or create additional empty strings.

◆ reserve()

void ts::ATSCMultipleString::reserve ( size_t  count)
inline

Allocate the appropriate memory for a target number of strings.

The actual number of strings in unchanged.

Parameters
[in]countThe target number of strings.

◆ language()

UString ts::ATSCMultipleString::language ( size_t  index = 0) const

Get the language of the specified string (first string by default).

Parameters
[in]indexString index.
Returns
The 3-character ISO-639 language code for the specified (or first) string. Empty string if the string does not exist.

◆ text() [1/2]

UString ts::ATSCMultipleString::text ( const UString language = UString()) const

Get the concatenation of all texts of the specified language.

Parameters
[in]language3-character ISO-639 language code. If empty, use the language code of the first string.
Returns
The concatenation of all texts of the specified language.

◆ text() [2/2]

UString ts::ATSCMultipleString::text ( size_t  index) const

Get the text of the specified string.

Parameters
[in]indexString index.
Returns
The text for the specified string. Empty string if the string does not exist.

◆ searchLanguage()

size_t ts::ATSCMultipleString::searchLanguage ( const UString language) const

Search the first string with a given language.

Parameters
[in]language3-character ISO-639 language code.
Returns
The index of the first string with the specified language or NPOS if not found.

◆ hasLanguage()

bool ts::ATSCMultipleString::hasLanguage ( const UString language) const
inline

Check if a given language is present.

Parameters
[in]language3-character ISO-639 language code.
Returns
True if the language is present.

◆ add()

void ts::ATSCMultipleString::add ( const UString language,
const UString text 
)

Add a new string.

Parameters
[in]language3-character ISO-639 language code.
[in]textText string.

◆ set()

bool ts::ATSCMultipleString::set ( size_t  index,
const UString language,
const UString text 
)

Set the value of an existing string.

Parameters
[in]indexString index.
[in]language3-character ISO-639 language code.
[in]textText string.
Returns
True if the string was set, false if index is out of range.

◆ append()

bool ts::ATSCMultipleString::append ( size_t  index,
const UString text 
)

Append text to an existing string.

Parameters
[in]indexString index.
[in]textText string to append.
Returns
True if the string was updated, false if index is out of range.

◆ toXML()

xml::Element * ts::ATSCMultipleString::toXML ( DuckContext duck,
xml::Element parent,
const UString name,
bool  ignore_empty 
) const

Convert to an XML structure.

Parameters
[in,out]duckTSDuck execution context.
[in,out]parentParent XML node.
[in]nameName of the XML node to create.
[in]ignore_emptyDo not insert the node if the structure is empty.
Returns
The created XML element or nullptr on error or empty and ignore_empty is true.

An ATSC multiple_string_structure can be represented as an XML element with a predefined structure. The name is application-dependent. The XML structure is the following:

<XXX>
<string language="char3" text="string"/>
<string language="char3" text="string"/>
...
</XXX>
bool set(size_t index, const UString &language, const UString &text)
Set the value of an existing string.
UString language(size_t index=0) const
Get the language of the specified string (first string by default).
UString text(const UString &language=UString()) const
Get the concatenation of all texts of the specified language.

◆ fromXML() [1/2]

bool ts::ATSCMultipleString::fromXML ( DuckContext duck,
const xml::Element elem 
)

Decode an XML structure and assign the result to this instance.

Parameters
[in,out]duckTSDuck execution context.
[in]elemXML node to decode as an ATSC multiple_string_structure.
Returns
True on success, false on invalid XLM structure.
See also
toXML()

◆ fromXML() [2/2]

bool ts::ATSCMultipleString::fromXML ( DuckContext duck,
const xml::Element parent,
const UString name,
bool  required 
)

Decode an XML structure and assign the result to this instance.

Parameters
[in,out]duckTSDuck execution context.
[in]parentParent XML node.
[in]nameName of the child XML node to decode as an ATSC multiple_string_structure.
[in]requiredWhen true, the name node shall be present. When false, if the node if not present, simply clear this object.
Returns
True on success, false on invalid XLM structure.
See also
toXML()

◆ serialize() [1/2]

size_t ts::ATSCMultipleString::serialize ( DuckContext duck,
uint8_t *&  data,
size_t size,
size_t  max_size = NPOS,
bool  ignore_empty = false 
) const

Serialize a binary multiple_string_structure.

Parameters
[in,out]duckTSDuck execution context.
[in,out]dataAddress of the buffer where to serialize the structure. On return, it is updated to point after the structure.
[in,out]sizeSize in bytes of the buffer. On return, it is updated to the remaining size in the buffer.
[in]max_sizeMax size to serialize, possibly lower than the buffer size.
[in]ignore_emptyIf true and the multiple_string_structure is empty, do nothing.
Returns
The number of serialized bytes.

◆ serialize() [2/2]

size_t ts::ATSCMultipleString::serialize ( DuckContext duck,
ByteBlock data,
size_t  max_size = NPOS,
bool  ignore_empty = false 
) const

Serialize a binary multiple_string_structure and append to a byte block.

Parameters
[in,out]duckTSDuck execution context.
[in,out]dataByte block where to serialize the structure. The structure is added at the end.
[in]max_sizeMax size to serialize.
[in]ignore_emptyIf true and the multiple_string_structure is empty, do nothing.
Returns
The number of serialized bytes.

◆ lengthSerialize() [1/2]

size_t ts::ATSCMultipleString::lengthSerialize ( DuckContext duck,
uint8_t *&  data,
size_t size,
size_t  length_bytes = 1 
) const

Serialize a binary multiple_string_structure with a leading length field.

Parameters
[in,out]duckTSDuck execution context.
[in,out]dataAddress of the buffer where to serialize the structure. On return, it is updated to point after the structure.
[in,out]sizeSize in bytes of the buffer. On return, it is updated to the remaining size in the buffer.
[in]length_bytesSize in bytes of the leading length field (1 byte by default).
Returns
The number of serialized bytes.

◆ lengthSerialize() [2/2]

size_t ts::ATSCMultipleString::lengthSerialize ( DuckContext duck,
ByteBlock data,
size_t  length_bytes = 1 
) const

Serialize a binary multiple_string_structure and append to a byte block with a leading length field.

Parameters
[in,out]duckTSDuck execution context.
[in,out]dataByte block where to serialize the structure. The structure is added at the end.
[in]length_bytesSize in bytes of the leading length field (1 byte by default).
Returns
The number of serialized bytes.

◆ deserialize()

bool ts::ATSCMultipleString::deserialize ( DuckContext duck,
const uint8_t *&  buffer,
size_t buffer_size,
size_t  mss_size = NPOS,
bool  ignore_empty = false 
)

Deserialize a binary multiple_string_structure.

Parameters
[in,out]duckTSDuck execution context.
[in,out]bufferAddress of the structure to deserialize. On return, it is updated to point after the structure.
[in,out]buffer_sizeSize in bytes of the data buffer. On return, it is updated to the remaining size in the buffer.
[in]mss_sizeSize of the multiple_string_structure to deserialize, possibly lower than the buffer size. If lower than buffer_size, adjust data and buffer_size to skip mss_size bytes.
[in]ignore_emptyIf true and the size is zero, then this is a valid empty multiple_string_structure.
Returns
True if the structure was successfully deserialized.

◆ lengthDeserialize()

bool ts::ATSCMultipleString::lengthDeserialize ( DuckContext duck,
const uint8_t *&  buffer,
size_t buffer_size,
size_t  length_bytes = 1 
)

Deserialize a binary multiple_string_structure with a leading length field.

Parameters
[in,out]duckTSDuck execution context.
[in,out]bufferAddress of the structure to deserialize. On return, it is updated to point after the structure.
[in,out]buffer_sizeSize in bytes of the data buffer. On return, it is updated to the remaining size in the buffer.
[in]length_bytesSize in bytes of the leading length field (1 byte by default).
Returns
True if the structure was successfully deserialized.

◆ Display()

static void ts::ATSCMultipleString::Display ( TablesDisplay display,
const UString title,
const UString margin,
const uint8_t *&  buffer,
size_t buffer_size,
size_t  mss_size = NPOS 
)
static

A static method to display a binary multiple_string_structure.

Parameters
[in,out]displayDisplay engine.
[in]titleLeading title to display. Can be empty.
[in]marginLeft margin content.
[in,out]bufferAddress of the binary structure to display. On return, it is updated to point after the structure.
[in,out]buffer_sizeSize in bytes of the data buffer. On return, it is updated to the remaining size in the buffer.
[in]mss_sizeSize of the multiple_string_structure to deserialize, possibly lower than the buffer size. If lower than buffer_size, adjust data and buffer_size to skip mss_size bytes.

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