TSDuck v3.46-4965
MPEG Transport Stream Toolkit
Loading...
Searching...
No Matches
ts::xml::Element Class Reference

#include <tsxmlElement.h>

Inheritance diagram for ts::xml::Element:
Collaboration diagram for ts::xml::Element:

Classes

class  ConstElementIterator
class  ConstElementSet

Public Member Functions

 Element (const Element &other)
 Element (Node *parent, const UString &name, bool last=true)
 Element (Report &report=(ts::NullReport::Instance()), size_t line=0)
Element * addElement (const UString &childName)
Text * addHexaText (const ByteBlock &data, bool only_not_empty=false)
Text * addHexaText (const void *data, size_t size, bool only_not_empty=false)
Text * addHexaTextChild (const UString &name, const ByteBlock &data, bool only_not_empty=false)
Text * addHexaTextChild (const UString &name, const void *data, size_t size, bool only_not_empty=false)
Text * addText (const UString &text, bool only_not_empty=false)
const Attribute & attribute (const UString &attribute_name, bool required=false) const
bool checkChildren (const UString &name, size_t min_count, size_t max_count=UNLIMITED) const
ConstElementSet children (const UString &name=UString(), bool *valid_condition=nullptr, size_t min_count=0, size_t max_count=UNLIMITED) const
size_t childrenCount () const
virtual void clear () override
virtual Node * clone () const override
UString debug () const
void deleteAttribute (const UString &name)
size_t depth () const
Document * document ()
const Document * document () const
UString escapedString (const UString &text, const UString &additional_escape, bool trim_spaces) const
virtual void expandEnvironment (bool recurse) override
Element * findFirstChild (const UString &name, bool required=false)
const Element * findFirstChild (const UString &name, bool required=false) const
Element * findNextSibling (bool required=false)
const Element * findNextSibling (bool required=false) const
Element * findNextSibling (const UString &name, bool required=false)
const Element * findNextSibling (const UString &name, bool required=false) const
Node * firstChild ()
const Node * firstChild () const
Element * firstChildElement ()
const Element * firstChildElement () const
bool getAttribute (UString &value, const UString &name, bool required=false, const UString &def_value=UString(), size_t min_size=0, size_t max_size=UNLIMITED) const
void getAttributes (std::map< UString, UString > &attr) const
size_t getAttributesCount () const
void getAttributesNames (UStringList &names) const
void getAttributesNamesInModificationOrder (UStringList &names) const
bool getBase64Attribute (ByteBlock &data, const UString &name, bool required=false, size_t min_size=0, size_t max_size=UNLIMITED) const
bool getBoolAttribute (bool &value, const UString &name, bool required=false, bool def_value=false) const
bool getBoolChild (bool &value, const UString &name, bool required=false, bool def_value=false) const
bool getChildren (ElementVector &children, const UString &name, size_t min_count=0, size_t max_count=UNLIMITED) const
template<class Rep, class Period>
bool getChronoAttribute (cn::duration< Rep, Period > &value, const UString &name, bool required=false, const cn::duration< Rep, Period > &def_value=cn::duration< Rep, Period >::zero(), const cn::duration< Rep, Period > &min_value=cn::duration< Rep, Period >::min(), const cn::duration< Rep, Period > &max_value=cn::duration< Rep, Period >::max()) const
template<typename INT, typename INT1 = INT, typename INT2 = INT>
requires ts::int_enum<INT> && ts::int_enum<INT1> && ts::int_enum<INT2>
bool getConditionalIntAttribute (std::optional< INT > &value, const UString &name, bool condition, INT1 min_value=std::numeric_limits< typename ts::underlying_type< INT >::type >::min(), INT2 max_value=std::numeric_limits< typename ts::underlying_type< INT >::type >::max()) const
bool getDateAttribute (Time &value, const UString &name, bool required=false, const Time &def_value=Time()) const
bool getDateTimeAttribute (Time &value, const UString &name, bool required=false, const Time &def_value=Time()) const
template<typename INT, typename INT1 = INT>
requires ts::int_enum<INT> && ts::int_enum<INT1>
bool getEnumAttribute (INT &value, const Names &definition, const UString &name, bool required=false, INT1 def_value=INT(0)) const
template<typename INT, typename INT1 = INT>
requires ts::int_enum<INT> && ts::int_enum<INT1>
bool getEnumAttribute (std::optional< INT > &value, const Names &definition, const UString &name, bool required=false, INT1 def_value=INT(0)) const
template<typename FLT, typename FLT1 = FLT, typename FLT2 = FLT, typename FLT3 = FLT>
requires std::floating_point<FLT> && std::is_arithmetic_v<FLT1> && std::is_arithmetic_v<FLT2> && std::is_arithmetic_v<FLT3>
bool getFloatAttribute (FLT &value, const UString &name, bool required=false, FLT1 def_value=static_cast< FLT >(0.0), FLT2 min_value=std::numeric_limits< FLT >::lowest(), FLT3 max_value=std::numeric_limits< FLT >::max()) const
template<typename FLT, typename FLT1 = FLT, typename FLT2 = FLT, typename FLT3 = FLT>
requires std::floating_point<FLT> && std::is_arithmetic_v<FLT1> && std::is_arithmetic_v<FLT2> && std::is_arithmetic_v<FLT3>
bool getFloatChild (FLT &value, const UString &name, bool required=false, FLT1 def_value=static_cast< FLT >(0.0), FLT2 min_value=std::numeric_limits< FLT >::lowest(), FLT3 max_value=std::numeric_limits< FLT >::max()) const
bool getHexaText (ByteBlock &data, size_t min_size=0, size_t max_size=UNLIMITED) const
bool getHexaTextChild (ByteBlock &data, const UString &name, bool required=false, size_t min_size=0, size_t max_size=UNLIMITED) const
template<typename INT, typename INT1 = INT, typename INT2 = INT, typename INT3 = INT>
requires ts::int_enum<INT> && ts::int_enum<INT1> && ts::int_enum<INT2> && ts::int_enum<INT3>
bool getIntAttribute (INT &value, const UString &name, bool required=false, INT1 def_value=static_cast< INT >(0), INT2 min_value=std::numeric_limits< typename ts::underlying_type< INT >::type >::min(), INT3 max_value=std::numeric_limits< typename ts::underlying_type< INT >::type >::max()) const
template<typename INT, typename INT1 = INT, typename INT2 = INT, typename INT3 = INT>
requires ts::int_enum<INT> && ts::int_enum<INT1> && ts::int_enum<INT2> && ts::int_enum<INT3>
bool getIntAttribute (std::optional< INT > &value, const UString &name, bool required=false, INT1 def_value=static_cast< INT >(0), INT2 min_value=std::numeric_limits< typename ts::underlying_type< INT >::type >::min(), INT3 max_value=std::numeric_limits< typename ts::underlying_type< INT >::type >::max()) const
template<typename INT, typename INT1 = INT, typename INT2 = INT, typename INT3 = INT>
requires ts::int_enum<INT> && ts::int_enum<INT1> && ts::int_enum<INT2> && ts::int_enum<INT3>
bool getIntChild (INT &value, const UString &name, bool required=false, INT1 def_value=static_cast< INT >(0), INT2 min_value=std::numeric_limits< typename ts::underlying_type< INT >::type >::min(), INT3 max_value=std::numeric_limits< typename ts::underlying_type< INT >::type >::max()) const
bool getIPAttribute (IPAddress &value, const UString &name, bool required=false, const IPAddress &def_value=IPAddress()) const
bool getIPChild (IPAddress &value, const UString &name, bool required=false, const IPAddress &def_value=IPAddress()) const
bool getISODateTimeAttribute (ISOTime &value, const UString &name, bool required=false, bool strict=false) const
bool getISODateTimeAttribute (Time &value, const UString &name, bool required=false, bool strict=false, const Time &def_value=Time()) const
bool getISODateTimeChild (ISOTime &value, const UString &name, bool required=false, bool strict=false) const
bool getISODateTimeChild (Time &value, const UString &name, bool required=false, bool strict=false, const Time &def_value=Time()) const
bool getISODurationAttribute (cn::milliseconds &value, const UString &name, bool required=false, bool strict=false, const cn::milliseconds &def_value=cn::milliseconds::zero(), const cn::milliseconds &min_value=cn::milliseconds::min(), const cn::milliseconds &max_value=cn::milliseconds::max()) const
bool getMACAttribute (MACAddress &value, const UString &name, bool required=false, const MACAddress &def_value=MACAddress()) const
bool getOptionalAttribute (std::optional< UString > &value, const UString &name, size_t min_size=0, size_t max_size=UNLIMITED) const
bool getOptionalBoolAttribute (std::optional< bool > &value, const UString &name) const
bool getOptionalDateAttribute (std::optional< Time > &value, const UString &name) const
bool getOptionalDateTimeAttribute (std::optional< Time > &value, const UString &name) const
template<typename INT>
requires ts::int_enum<INT>
bool getOptionalEnumAttribute (std::optional< INT > &value, const Names &definition, const UString &name) const
template<typename FLT, typename FLT1 = FLT, typename FLT2 = FLT>
requires std::floating_point<FLT> && std::is_arithmetic_v<FLT1> && std::is_arithmetic_v<FLT2>
bool getOptionalFloatAttribute (std::optional< FLT > &value, const UString &name, FLT1 min_value=std::numeric_limits< FLT >::lowest(), FLT2 max_value=std::numeric_limits< FLT >::max()) const
template<typename INT, typename INT1 = INT, typename INT2 = INT>
requires ts::int_enum<INT> && ts::int_enum<INT1> && ts::int_enum<INT2>
bool getOptionalIntAttribute (std::optional< INT > &value, const UString &name, INT1 min_value=std::numeric_limits< typename ts::underlying_type< INT >::type >::min(), INT2 max_value=std::numeric_limits< typename ts::underlying_type< INT >::type >::max()) const
template<class Rep, class Period>
bool getOptionalTimeAttribute (std::optional< cn::duration< Rep, Period > > &value, const UString &name) const
bool getText (UString &data, bool trim=false, size_t min_size=0, size_t max_size=UNLIMITED) const
bool getTextChild (UString &data, const UString &name, bool trim=false, bool required=false, const UString &def_value=UString(), size_t min_size=0, size_t max_size=UNLIMITED) const
template<class Rep, class Period>
bool getTimeAttribute (cn::duration< Rep, Period > &value, const UString &name, bool required=false) const
template<class Rep1, class Period1, class Rep2, class Period2>
bool getTimeAttribute (cn::duration< Rep1, Period1 > &value, const UString &name, bool required, const cn::duration< Rep2, Period2 > &def_value) const
bool getVariableAttribute (std::optional< UString > &value, const UString &name, bool required=false, const UString &def_value=UString(), size_t min_size=0, size_t max_size=UNLIMITED) const
template<typename FLT, typename FLT1 = FLT, typename FLT2 = FLT, typename FLT3 = FLT>
requires std::floating_point<FLT> && std::is_arithmetic_v<FLT1> && std::is_arithmetic_v<FLT2> && std::is_arithmetic_v<FLT3>
bool getVariableFloatAttribute (std::optional< FLT > &value, const UString &name, bool required=false, FLT1 def_value=static_cast< FLT >(0), FLT2 min_value=std::numeric_limits< FLT >::lowest(), FLT3 max_value=std::numeric_limits< FLT >::max()) const
bool hasAttribute (const UString &attribute_name) const
bool hasAttribute (const UString &attribute_name, const UString &value, bool similar=false) const
bool hasChildElement (const UString &name) const
bool hasChildren () const
bool ignoreNamespace () const
Node * lastChild ()
const Node * lastChild () const
size_t lineNumber () const
bool merge (Element *other, MergeAttributes attr_options=MergeAttributes::ADD)
void move (Node *new_sibling, bool before)
void moveAfter (Node *new_sibling)
void moveBefore (Node *new_sibling)
const UString & name () const
bool nameMatch (const Element *other) const
bool nameMatch (const Element *other, bool ignore_namespace) const
bool nameMatch (const UChar *str) const
bool nameMatch (const UChar *str, bool ignore_namespace) const
bool nameMatch (const UString &str) const
bool nameMatch (const UString &str, bool ignore_namespace) const
Node * nextSibling ()
const Node * nextSibling () const
Element * nextSiblingElement ()
const Element * nextSiblingElement () const
virtual UString oneLiner () const
Node * parent ()
const Node * parent () const
const UString & parentName () const
bool preserveSpace () const
Node * previousSibling ()
const Node * previousSibling () const
Element * previousSiblingElement ()
const Element * previousSiblingElement () const
virtual void print (TextFormatter &output, bool keep_node_open=false) const override
virtual void printClose (TextFormatter &output, size_t levels=std::numeric_limits< size_t >::max()) const override
void removeComments (bool recurse)
void reparent (Node *new_parent, bool last=true)
Report & report () const
bool ringAlone () const
void ringInsertAfter (RingNode *o)
void ringInsertBefore (RingNode *o)
template<typename T>
T * ringNext ()
template<typename T>
const T * ringNext () const
template<typename T>
T * ringPrevious ()
template<typename T>
const T * ringPrevious () const
void ringRemove ()
size_t ringSize () const
void ringSwap (RingNode *o)
void setAttribute (const UString &name, const UString &value, bool only_if_not_empty=false)
void setBase64Attribute (const UString &name, const ByteBlock &data, bool only_not_empty=false)
void setBase64Attribute (const UString &name, const void *data, size_t size, bool only_not_empty=false)
void setBoolAttribute (const UString &name, bool value)
template<class Rep, class Period>
void setChronoAttribute (const UString &name, cn::duration< Rep, Period > value, bool hexa=false)
void setDateAttribute (const UString &name, const Time &value)
void setDateTimeAttribute (const UString &name, const Time &value)
template<typename INT>
requires ts::int_enum<INT>
void setEnumAttribute (const Names &definition, const UString &name, INT value)
template<typename FLT>
requires std::floating_point<FLT>
void setFloatAttribute (const UString &name, FLT value, size_t width=0, size_t precision=6, bool force_sign=false)
virtual void setIignoreNamespace (bool ignore) override
template<typename INT>
requires std::integral<INT>
void setIntAttribute (const UString &name, INT value, bool hexa=false)
void setIPAttribute (const UString &name, const IPAddress &value)
void setMACAttribute (const UString &name, const MACAddress &value)
void setOptionalAttribute (const UString &name, const std::optional< UString > &value)
void setOptionalBoolAttribute (const UString &name, const std::optional< bool > &value)
void setOptionalDateAttribute (const UString &name, const std::optional< Time > &value)
void setOptionalDateTimeAttribute (const UString &name, const std::optional< Time > &value)
template<typename INT>
requires ts::int_enum<INT>
void setOptionalEnumAttribute (const Names &definition, const UString &name, const std::optional< INT > &value)
template<typename FLT>
requires std::floating_point<FLT>
void setOptionalFloatAttribute (const UString &name, const std::optional< FLT > &value, size_t width=0, size_t precision=6, bool force_sign=false)
template<typename INT>
requires std::integral<INT>
void setOptionalIntAttribute (const UString &name, const std::optional< INT > &value, bool hexa=false)
template<class Rep, class Period>
void setOptionalTimeAttribute (const UString &name, const std::optional< cn::duration< Rep, Period > > &value)
template<class Rep, class Period>
void setTimeAttribute (const UString &name, const cn::duration< Rep, Period > &value)
void setValue (const UString &value)
void sort (const UString &name=UString())
virtual bool stickyOutput () const
UString text (bool trim=false) const
virtual const Tweaks & tweaks () const
virtual UString typeName () const override
const UString & value () const

Protected Member Functions

Node * identifyNextNode (TextParser &parser)
virtual bool parseChildren (TextParser &parser, size_t max_nested)
virtual bool parseNode (TextParser &parser, const Node *parent, size_t max_nested) override
void setPreserveSpace (bool on)

Detailed Description

Structured element in an XML document.

Constructor & Destructor Documentation

◆ Element() [1/3]

ts::xml::Element::Element ( Report & report = (ts::NullReport::Instance()),
size_t line = 0 )
explicit

Constructor.

Parameters
[in,out]reportWhere to report errors.
[in]lineLine number in input document.

◆ Element() [2/3]

ts::xml::Element::Element ( Node * parent,
const UString & name,
bool last = true )

Constructor.

Parameters
[in,out]parentThe parent into which the element is added.
[in]nameName of the element.
[in]lastIf true, the child is added at the end of the list of children. If false, it is added at the beginning.

◆ Element() [3/3]

ts::xml::Element::Element ( const Element & other)

Copy constructor.

Parameters
[in]otherOther instance to copy.

Member Function Documentation

◆ name()

const UString & ts::xml::Element::name ( ) const
inline

Get the element name. This is the same as the node value.

Returns
A constant reference to the element name.

◆ parentName()

const UString & ts::xml::Element::parentName ( ) const

Get the parent name. This is the same as parent()->name() without error when there is not parent.

Returns
A constant reference to the parent name or to an empty string if there is no parent.

◆ nameMatch() [1/6]

bool ts::xml::Element::nameMatch ( const UChar * str) const
inline

Check if the name of the element matches a given value, case-insensitive.

Parameters
[in]strThe string value to compare.
Returns
True is the name of this object matches str.

◆ nameMatch() [2/6]

bool ts::xml::Element::nameMatch ( const UString & str) const
inline

Check if the name of the element matches a given value, case-insensitive.

Parameters
[in]strThe string value to compare.
Returns
True is the name of this object matches str.

◆ nameMatch() [3/6]

bool ts::xml::Element::nameMatch ( const Element * other) const
inline

Check if two XML elements have the same name, case-insensitive.

Parameters
[in]otherAnother XML element.
Returns
True is this object and other have identical names.

◆ nameMatch() [4/6]

bool ts::xml::Element::nameMatch ( const UChar * str,
bool ignore_namespace ) const

Check if the name of the element matches a given value, case-insensitive.

Parameters
[in]strThe string value to compare.
[in]ignore_namespaceIf true, ignore namespaces in the comparison.
Returns
True is the name of this object matches str.

◆ nameMatch() [5/6]

bool ts::xml::Element::nameMatch ( const UString & str,
bool ignore_namespace ) const
inline

Check if the name of the element matches a given value, case-insensitive.

Parameters
[in]strThe string value to compare.
[in]ignore_namespaceIf true, ignore namespaces in the comparison.
Returns
True is the name of this object matches str.

◆ nameMatch() [6/6]

bool ts::xml::Element::nameMatch ( const Element * other,
bool ignore_namespace ) const
inline

Check if two XML elements have the same name, case-insensitive.

Parameters
[in]otherAnother XML element.
[in]ignore_namespaceIf true, ignore namespaces in the comparison.
Returns
True is this object and other have identical names.

◆ getChildren()

bool ts::xml::Element::getChildren ( ElementVector & children,
const UString & name,
size_t min_count = 0,
size_t max_count = UNLIMITED ) const

Find all children elements by name, case-insensitive.

Parameters
[out]childrenReturned vector of all children.
[in]nameName of the child element to search.
[in]min_countMinimum required number of elements of that name.
[in]max_countMaximum allowed number of elements of that name.
Returns
True on success, false on error.

◆ checkChildren()

bool ts::xml::Element::checkChildren ( const UString & name,
size_t min_count,
size_t max_count = UNLIMITED ) const

Check that children of a given name, case-insensitive, are in a bounded number of instances.

Parameters
[in]nameName of the child element to search.
[in]min_countMinimum required number of elements of that name.
[in]max_countMaximum allowed number of elements of that name.
Returns
True on success, false if the number of elements of that name is not in the right range.

◆ hasChildElement()

bool ts::xml::Element::hasChildElement ( const UString & name) const

Check if the element contains at least 1 named child element, case-insensitive.

Parameters
[in]nameName of the child element to search.
Returns
True if present, false if not present.

◆ findFirstChild() [1/2]

const Element * ts::xml::Element::findFirstChild ( const UString & name,
bool required = false ) const
inline

Find the first child element by name, case-insensitive.

Parameters
[in]nameName of the child element to search. If empty, get the first element.
[in]requiredIf true, generate an error if the attribute is not found.
Returns
Child element address or zero if not found.

◆ findFirstChild() [2/2]

Element * ts::xml::Element::findFirstChild ( const UString & name,
bool required = false )

Find the first child element by name, case-insensitive.

Parameters
[in]nameName of the child element to search. If empty, get the first element.
[in]requiredIf true, generate an error if the attribute is not found.
Returns
Child element address or zero if not found.

◆ findNextSibling() [1/4]

const Element * ts::xml::Element::findNextSibling ( const UString & name,
bool required = false ) const
inline

Find the next sibling element by name, case-insensitive.

Parameters
[in]nameName of the sibling element to search. If empty, get the next element.
[in]requiredIf true, generate an error if the attribute is not found.
Returns
Child element address or zero if not found.

◆ findNextSibling() [2/4]

Element * ts::xml::Element::findNextSibling ( const UString & name,
bool required = false )

Find the next sibling element by name, case-insensitive.

Parameters
[in]nameName of the sibling element to search. If empty, get the next element.
[in]requiredIf true, generate an error if the attribute is not found.
Returns
Child element address or zero if not found.

◆ findNextSibling() [3/4]

const Element * ts::xml::Element::findNextSibling ( bool required = false) const
inline

Find the next sibling element with same name as this element.

Parameters
[in]requiredIf true, generate an error if the attribute is not found.
Returns
Child element address or zero if not found.

◆ findNextSibling() [4/4]

Element * ts::xml::Element::findNextSibling ( bool required = false)
inline

Find the next sibling element with same name as this element.

Parameters
[in]requiredIf true, generate an error if the attribute is not found.
Returns
Child element address or zero if not found.

◆ children()

ConstElementSet ts::xml::Element::children ( const UString & name = UString(),
bool * valid_condition = nullptr,
size_t min_count = 0,
size_t max_count = UNLIMITED ) const

Get an iterable set of all children elements of a given name and iteration conditions.

Parameters
[in]nameName of the children elements to iterate over. If empty, iterate over all children elements.
[in,out]valid_conditionOptional pointer to a "validity" condition. This is typically an external boolean variable which is used all along the parsing of the XML structure. Whenever this variable becomes false, iteration will stop (all operations on iterators will return the end() iterator value).
[in]min_countMinimum number of required children. If there are less children, an error is reported, valid_condition is set to false (if not nullptr), the set of iterable elements is empty.
[in]max_countMaximum number of required children. If there are more children, an error is reported, valid_condition is set to false (if not nullptr), the set of iterable elements is empty.
Returns
A iterable set of elements.

Sample code:

// Iterate over all children elements:
for (auto& e : root->children()) {
e.getIntAttribute(...);
}
// Iterate over all "a" children elements with error and cardinality check:
bool valid = true;
for (auto& e : root->children(u"a", &valid, 1, 5)) {
valid = e.getIntAttribute(...);
}

◆ getAttributesNames()

void ts::xml::Element::getAttributesNames ( UStringList & names) const

Get the list of all attribute names.

Parameters
[out]namesReturned list of all attribute names.

◆ getAttributes()

void ts::xml::Element::getAttributes ( std::map< UString, UString > & attr) const

Get the list of all attributes.

Parameters
[out]attrReturned map of all attribute names (index in the map) and corresponding values.

◆ getAttributesNamesInModificationOrder()

void ts::xml::Element::getAttributesNamesInModificationOrder ( UStringList & names) const

Get the list of all attribute names, sorted by modification order. The method is slower than getAttributesNames().

Parameters
[out]namesReturned list of all attribute names.

◆ getAttributesCount()

size_t ts::xml::Element::getAttributesCount ( ) const
inline

Get the number of attributes in the element.

Returns
The number of attributes in the element.

◆ hasAttribute() [1/2]

bool ts::xml::Element::hasAttribute ( const UString & attribute_name) const

Check if an attribute exists in the element.

Parameters
[in]attribute_nameAttribute name.
Returns
True if the attribute exists.

◆ hasAttribute() [2/2]

bool ts::xml::Element::hasAttribute ( const UString & attribute_name,
const UString & value,
bool similar = false ) const

Check if an attribute exists in the element and has the specified value.

Parameters
[in]attribute_nameAttribute name.
[in]valueExpected value.
[in]similarIf true, the comparison between the actual and expected values is performed case-insensitive and ignoring blanks. Additionally, if the values are integers, the integer values are compared (otherwise, identical values in decimal and hexadecimal wouldn't match). If similar is false, a strict comparison is performed.
Returns
True if the attribute exists and has the expected value.

◆ attribute()

const Attribute & ts::xml::Element::attribute ( const UString & attribute_name,
bool required = false ) const

Get an attribute.

Parameters
[in]attribute_nameAttribute name.
[in]requiredIf true, generate an error if the attribute is not found.
Returns
A constant reference to an attribute. If the argument does not exist, the referenced object is marked invalid. The reference is valid as long as the Element object is not modified.

◆ deleteAttribute()

void ts::xml::Element::deleteAttribute ( const UString & name)

Delete an attribute.

Parameters
[in]nameAttribute name to delete.

◆ getTextChild()

bool ts::xml::Element::getTextChild ( UString & data,
const UString & name,
bool trim = false,
bool required = false,
const UString & def_value = UString(),
size_t min_size = 0,
size_t max_size = UNLIMITED ) const

Get text in a child of the element.

Parameters
[out]dataThe content of the text in the child element.
[in]nameName of the child element to search.
[in]trimIf true, remove leading and trailing spaces.
[in]requiredIf true, generate an error if the child element is not found.
[in]def_valueDefault value to return if the child element is not present.
[in]min_sizeMinimum allowed size for the value string.
[in]max_sizeMaximum allowed size for the value string.
Returns
True on success, false on error.

◆ getText()

bool ts::xml::Element::getText ( UString & data,
bool trim = false,
size_t min_size = 0,
size_t max_size = UNLIMITED ) const

Get text inside an element. In practice, concatenate the content of all Text children inside the element.

Parameters
[out]dataThe content of the text children.
[in]trimIf true, remove leading and trailing spaces.
[in]min_sizeMinimum allowed size for the value string.
[in]max_sizeMaximum allowed size for the value string.
Returns
True on success, false on error.

◆ text()

UString ts::xml::Element::text ( bool trim = false) const

Get text inside an element. In practice, concatenate the content of all Text children inside the element.

Parameters
[in]trimIf true, remove leading and trailing spaces.
Returns
The content of the text children, empty if non-existent.

◆ getHexaTextChild()

bool ts::xml::Element::getHexaTextChild ( ByteBlock & data,
const UString & name,
bool required = false,
size_t min_size = 0,
size_t max_size = UNLIMITED ) const

Get text in a child containing hexadecimal data.

Parameters
[out]dataThe content of the text in the child element.
[in]nameName of the child element to search.
[in]requiredIf true, generate an error if the child element is not found.
[in]min_sizeMinimum allowed size for the returned binary data.
[in]max_sizeMaximum allowed size for the returned binary data.
Returns
True on success, false on error.

◆ getHexaText()

bool ts::xml::Element::getHexaText ( ByteBlock & data,
size_t min_size = 0,
size_t max_size = UNLIMITED ) const

Get and interpret the hexadecimal data inside the element. In practice, concatenate the content of all Text children inside the element and interpret the result as hexadecimal data.

Parameters
[out]dataBuffer receiving the decoded hexadecimal data.
[in]min_sizeMinimum size of the returned binary data.
[in]max_sizeMaximum size of the returned binary data.
Returns
True on success, false on error.

◆ addElement()

Element * ts::xml::Element::addElement ( const UString & childName)

Add a new child element at the end of children.

Parameters
[in]childNameName of new child element to create.
Returns
New child element or null on error.

◆ addText()

Text * ts::xml::Element::addText ( const UString & text,
bool only_not_empty = false )

Add a new text inside this node.

Parameters
[in]textText string to add.
[in]only_not_emptyWhen true, do not add the text if the string is empty.
Returns
New child element or null on error.

◆ addHexaText() [1/2]

Text * ts::xml::Element::addHexaText ( const void * data,
size_t size,
bool only_not_empty = false )

Add a new text containing hexadecimal data inside this node.

Parameters
[in]dataAddress of binary data.
[in]sizeSize in bytes of binary data.
[in]only_not_emptyWhen true, do not add the child element if the data is empty.
Returns
New child element or null on error or empty data.

◆ addHexaText() [2/2]

Text * ts::xml::Element::addHexaText ( const ByteBlock & data,
bool only_not_empty = false )
inline

Add a new text containing hexadecimal data inside this node.

Parameters
[in]dataBinary data.
[in]only_not_emptyWhen true, do not add the child element if the data is empty.
Returns
New child element or null on error or empty data.

◆ addHexaTextChild() [1/2]

Text * ts::xml::Element::addHexaTextChild ( const UString & name,
const void * data,
size_t size,
bool only_not_empty = false )

Add a new child element containing an hexadecimal data text.

Parameters
[in]nameName of the child element to search.
[in]dataAddress of binary data.
[in]sizeSize in bytes of binary data.
[in]only_not_emptyWhen true, do not add the child element if the data is empty.
Returns
New child element or null on error or empty data.

◆ addHexaTextChild() [2/2]

Text * ts::xml::Element::addHexaTextChild ( const UString & name,
const ByteBlock & data,
bool only_not_empty = false )

Add a new child element containing an hexadecimal data text.

Parameters
[in]nameName of the child element to search.
[in]dataBinary data.
[in]only_not_emptyWhen true, do not add the child element if the data is empty.
Returns
New child element or null on error or empty data.

◆ setAttribute()

void ts::xml::Element::setAttribute ( const UString & name,
const UString & value,
bool only_if_not_empty = false )

Set an attribute.

Parameters
[in]nameAttribute name.
[in]valueAttribute value.
[in]only_if_not_emptyWhen true, do not insert the attribute if value is empty.

◆ getAttribute()

bool ts::xml::Element::getAttribute ( UString & value,
const UString & name,
bool required = false,
const UString & def_value = UString(),
size_t min_size = 0,
size_t max_size = UNLIMITED ) const

Get a string attribute of an XML element.

Parameters
[out]valueReturned value of the attribute.
[in]nameName of the attribute.
[in]requiredIf true, generate an error if the attribute is not found.
[in]def_valueDefault value to return if the attribute is not present.
[in]min_sizeMinimum allowed size for the value string.
[in]max_sizeMaximum allowed size for the value string.
Returns
True on success, false on error.

◆ setOptionalAttribute()

void ts::xml::Element::setOptionalAttribute ( const UString & name,
const std::optional< UString > & value )
inline

Set an optional attribute to a node.

Parameters
[in]nameAttribute name.
[in]valueAttribute value.

◆ getOptionalAttribute()

bool ts::xml::Element::getOptionalAttribute ( std::optional< UString > & value,
const UString & name,
size_t min_size = 0,
size_t max_size = UNLIMITED ) const

Get an optional string attribute of an XML element.

Parameters
[out]valueReturned value of the attribute. If the attribute is not present, the variable is reset.
[in]nameName of the attribute.
[in]min_sizeMinimum allowed size for the value string.
[in]max_sizeMaximum allowed size for the value string.
Returns
True on success, false on error.

◆ getVariableAttribute()

bool ts::xml::Element::getVariableAttribute ( std::optional< UString > & value,
const UString & name,
bool required = false,
const UString & def_value = UString(),
size_t min_size = 0,
size_t max_size = UNLIMITED ) const
inline

Get an optional attribute of an XML element. getVariableAttribute() is different from getOptionalAttribute() in the result. With getOptionalAttribute(), if the attribute is missing, the std::optional is unset. With getVariableAttribute(), if the attribute is missing, the std::optional is set with the default value.

Parameters
[out]valueReturned value of the attribute. If the attribute is not present, the variable is reset.
[in]nameName of the attribute.
[in]requiredIf true, generate an error if the attribute is not found.
[in]def_valueDefault value to return if the attribute is not present.
[in]min_sizeMinimum allowed size for the value string.
[in]max_sizeMaximum allowed size for the value string.
Returns
True on success, false on error.

◆ setBase64Attribute() [1/2]

void ts::xml::Element::setBase64Attribute ( const UString & name,
const void * data,
size_t size,
bool only_not_empty = false )

Set a Base64-encoded attribute.

Parameters
[in]nameName of the child element to search.
[in]dataAddress of binary data.
[in]sizeSize in bytes of binary data.
[in]only_not_emptyWhen true, do not add the attribute if the data is empty.

◆ setBase64Attribute() [2/2]

void ts::xml::Element::setBase64Attribute ( const UString & name,
const ByteBlock & data,
bool only_not_empty = false )
inline

Set a Base64-encoded attribute.

Parameters
[in]nameName of the child element to search.
[in]dataBinary data.
[in]only_not_emptyWhen true, do not add the attribute if the data is empty.

◆ getBase64Attribute()

bool ts::xml::Element::getBase64Attribute ( ByteBlock & data,
const UString & name,
bool required = false,
size_t min_size = 0,
size_t max_size = UNLIMITED ) const

Get a Base64-encoded attribute.

Parameters
[out]dataThe decoded content of the attribute.
[in]nameName of the attribute.
[in]requiredIf true, generate an error if the attribute is not found.
[in]min_sizeMinimum allowed size for the returned binary data.
[in]max_sizeMaximum allowed size for the returned binary data.
Returns
True on success, false on error.

◆ setBoolAttribute()

void ts::xml::Element::setBoolAttribute ( const UString & name,
bool value )
inline

Set a bool attribute to a node.

Parameters
[in]nameAttribute name.
[in]valueAttribute value.

◆ getBoolAttribute()

bool ts::xml::Element::getBoolAttribute ( bool & value,
const UString & name,
bool required = false,
bool def_value = false ) const

Get a boolean attribute of an XML element.

Parameters
[out]valueReturned value of the attribute.
[in]nameName of the attribute.
[in]requiredIf true, generate an error if the attribute is not found.
[in]def_valueDefault value to return if the attribute is not present.
Returns
True on success, false on error.

◆ getBoolChild()

bool ts::xml::Element::getBoolChild ( bool & value,
const UString & name,
bool required = false,
bool def_value = false ) const

Get a boolean value from a child of an XML element.

Parameters
[out]valueReturned value of the attribute.
[in]nameName of the attribute.
[in]requiredIf true, generate an error if the attribute is not found.
[in]def_valueDefault value to return if the attribute is not present.
Returns
True on success, false on error.

◆ setOptionalBoolAttribute()

void ts::xml::Element::setOptionalBoolAttribute ( const UString & name,
const std::optional< bool > & value )
inline

Set an optional bool attribute to a node.

Parameters
[in]nameAttribute name.
[in]valueAttribute value.

◆ getOptionalBoolAttribute()

bool ts::xml::Element::getOptionalBoolAttribute ( std::optional< bool > & value,
const UString & name ) const

Get an optional boolean attribute of an XML element.

Parameters
[out]valueReturned value of the attribute.
[in]nameName of the attribute.
Returns
True on success, false on error.

◆ setIntAttribute()

template<typename INT>
requires std::integral<INT>
void ts::xml::Element::setIntAttribute ( const UString & name,
INT value,
bool hexa = false )
inline

Set an attribute with an integer value to a node.

Template Parameters
INTAn integer type.
Parameters
[in]nameAttribute name.
[in]valueAttribute value.
[in]hexaIf true, use an hexadecimal representation (0x...).

◆ getIntAttribute() [1/2]

template<typename INT, typename INT1, typename INT2, typename INT3>
requires ts::int_enum<INT> && ts::int_enum<INT1> && ts::int_enum<INT2> && ts::int_enum<INT3>
bool ts::xml::Element::getIntAttribute ( INT & value,
const UString & name,
bool required = false,
INT1 def_value = static_cast<INT>(0),
INT2 min_value = std::numeric_limits<typename ts::underlying_type<INT>::type>::min(),
INT3 max_value = std::numeric_limits<typename ts::underlying_type<INT>::type>::max() ) const

Get an integer or enum attribute of an XML element.

Template Parameters
INTAn integer or enum type.
Parameters
[out]valueReturned value of the attribute.
[in]nameName of the attribute.
[in]requiredIf true, generate an error if the attribute is not found.
[in]def_valueDefault value to return if the attribute is not present.
[in]min_valueMinimum allowed value for the attribute.
[in]max_valueMaximum allowed value for the attribute.
Returns
True on success, false on error.

◆ getIntChild()

template<typename INT, typename INT1, typename INT2, typename INT3>
requires ts::int_enum<INT> && ts::int_enum<INT1> && ts::int_enum<INT2> && ts::int_enum<INT3>
bool ts::xml::Element::getIntChild ( INT & value,
const UString & name,
bool required = false,
INT1 def_value = static_cast<INT>(0),
INT2 min_value = std::numeric_limits<typename ts::underlying_type<INT>::type>::min(),
INT3 max_value = std::numeric_limits<typename ts::underlying_type<INT>::type>::max() ) const

Get an integer or enum in a child of the element.

Template Parameters
INTAn integer or enum type.
Parameters
[out]valueReturned value of the attribute.
[in]nameName of the child to search.
[in]requiredIf true, generate an error if the child is not found.
[in]def_valueDefault value to return if the attribute is not present.
[in]min_valueMinimum allowed value for the attribute.
[in]max_valueMaximum allowed value for the attribute.
Returns
True on success, false on error.

◆ getIntAttribute() [2/2]

template<typename INT, typename INT1 = INT, typename INT2 = INT, typename INT3 = INT>
requires ts::int_enum<INT> && ts::int_enum<INT1> && ts::int_enum<INT2> && ts::int_enum<INT3>
bool ts::xml::Element::getIntAttribute ( std::optional< INT > & value,
const UString & name,
bool required = false,
INT1 def_value = static_cast<INT>(0),
INT2 min_value = std::numeric_limits<typename ts::underlying_type<INT>::type>::min(),
INT3 max_value = std::numeric_limits<typename ts::underlying_type<INT>::type>::max() ) const
inline

Get an integer or enum attribute of an XML element.

Template Parameters
INTAn integer type.
Parameters
[out]valueReturned value of the attribute. Always set, possibly to the default value.
[in]nameName of the attribute.
[in]requiredIf true, generate an error if the attribute is not found.
[in]def_valueDefault value to return if the attribute is not present.
[in]min_valueMinimum allowed value for the attribute.
[in]max_valueMaximum allowed value for the attribute.
Returns
True on success, false on error.

◆ setOptionalIntAttribute()

template<typename INT>
requires std::integral<INT>
void ts::xml::Element::setOptionalIntAttribute ( const UString & name,
const std::optional< INT > & value,
bool hexa = false )
inline

Set an optional attribute with an integer value to a node.

Template Parameters
INTAn integer type.
Parameters
[in]nameAttribute name.
[in]valueAttribute optional value. If the variable is not set, no attribute is set.
[in]hexaIf true, use an hexadecimal representation (0x...).

◆ getOptionalIntAttribute()

template<typename INT, typename INT1, typename INT2>
requires ts::int_enum<INT> && ts::int_enum<INT1> && ts::int_enum<INT2>
bool ts::xml::Element::getOptionalIntAttribute ( std::optional< INT > & value,
const UString & name,
INT1 min_value = std::numeric_limits<typename ts::underlying_type<INT>::type>::min(),
INT2 max_value = std::numeric_limits<typename ts::underlying_type<INT>::type>::max() ) const

Get an optional integer or enum attribute of an XML element.

Template Parameters
INTAn integer or enum type.
Parameters
[out]valueReturned value of the attribute. If the attribute is not present, the variable is reset.
[in]nameName of the attribute.
[in]min_valueMinimum allowed value for the attribute.
[in]max_valueMaximum allowed value for the attribute.
Returns
True on success, false on error.

◆ getConditionalIntAttribute()

template<typename INT, typename INT1, typename INT2>
requires ts::int_enum<INT> && ts::int_enum<INT1> && ts::int_enum<INT2>
bool ts::xml::Element::getConditionalIntAttribute ( std::optional< INT > & value,
const UString & name,
bool condition,
INT1 min_value = std::numeric_limits<typename ts::underlying_type<INT>::type>::min(),
INT2 max_value = std::numeric_limits<typename ts::underlying_type<INT>::type>::max() ) const

Get an integer or enum attribute of an XML element, based on a condition.

Template Parameters
INTAn integer or enum type.
Parameters
[out]valueReturned value of the attribute. If the attribute is not present, the variable is reset.
[in]nameName of the attribute.
[in]conditionIf true, the attribute must be present. If false, the attribute must nbot be present.
[in]min_valueMinimum allowed value for the attribute.
[in]max_valueMaximum allowed value for the attribute.
Returns
True on success, false on error.

◆ setEnumAttribute()

template<typename INT>
requires ts::int_enum<INT>
void ts::xml::Element::setEnumAttribute ( const Names & definition,
const UString & name,
INT value )
inline

Set an enumeration attribute of a node.

Template Parameters
INTAn integer or enum type.
Parameters
[in]definitionThe definition of enumeration values.
[in]nameAttribute name.
[in]valueAttribute value.

◆ getEnumAttribute() [1/2]

template<typename INT, typename INT1>
requires ts::int_enum<INT> && ts::int_enum<INT1>
bool ts::xml::Element::getEnumAttribute ( INT & value,
const Names & definition,
const UString & name,
bool required = false,
INT1 def_value = INT(0) ) const

Get an enumeration attribute of an XML element. Integer literals and integer values are accepted in the attribute.

Template Parameters
INTAn integer or enum type.
Parameters
[out]valueReturned value of the attribute.
[in]definitionThe definition of enumeration values.
[in]nameName of the attribute.
[in]requiredIf true, generate an error if the attribute is not found.
[in]def_valueDefault value to return if the attribute is not present.
Returns
True on success, false on error.

◆ getEnumAttribute() [2/2]

template<typename INT, typename INT1 = INT>
requires ts::int_enum<INT> && ts::int_enum<INT1>
bool ts::xml::Element::getEnumAttribute ( std::optional< INT > & value,
const Names & definition,
const UString & name,
bool required = false,
INT1 def_value = INT(0) ) const
inline

Get an enumeration attribute of an XML element.

Template Parameters
INTAn integer or enum type.
Parameters
[out]valueReturned value of the attribute. Always set, possibly to the default value.
[in]definitionThe definition of enumeration values.
[in]nameName of the attribute.
[in]requiredIf true, generate an error if the attribute is not found.
[in]def_valueDefault value to return if the attribute is not present.
Returns
True on success, false on error.

◆ setOptionalEnumAttribute()

template<typename INT>
requires ts::int_enum<INT>
void ts::xml::Element::setOptionalEnumAttribute ( const Names & definition,
const UString & name,
const std::optional< INT > & value )
inline

Set an optional attribute with an enumeration attribute to a node.

Template Parameters
INTAn integer or enum type.
Parameters
[in]definitionThe definition of enumeration values.
[in]nameAttribute name.
[in]valueAttribute optional value. If the variable is not set, no attribute is set.

◆ getOptionalEnumAttribute()

template<typename INT>
requires ts::int_enum<INT>
bool ts::xml::Element::getOptionalEnumAttribute ( std::optional< INT > & value,
const Names & definition,
const UString & name ) const

Get an optional enumeration attribute of an XML element. Integer literals and integer values are accepted in the attribute.

Template Parameters
INTAn integer or enum type.
Parameters
[out]valueReturned value of the attribute. If the attribute is not present, the variable is reset.
[in]definitionThe definition of enumeration values.
[in]nameName of the attribute.
Returns
True on success, false on error.

◆ setFloatAttribute()

template<typename FLT>
requires std::floating_point<FLT>
void ts::xml::Element::setFloatAttribute ( const UString & name,
FLT value,
size_t width = 0,
size_t precision = 6,
bool force_sign = false )
inline

Set an attribute with a floating-point value to a node.

Template Parameters
FLTA floating-point type.
Parameters
[in]nameAttribute name.
[in]valueAttribute value.
[in]widthWidth of the formatted number, not including the optional prefix and separator.
[in]precisionPrecision to use after the decimal point. Default is 6 digits.
[in]force_signIf true, force a '+' sign for positive values.

◆ getFloatAttribute()

template<typename FLT, typename FLT1, typename FLT2, typename FLT3>
requires std::floating_point<FLT> && std::is_arithmetic_v<FLT1> && std::is_arithmetic_v<FLT2> && std::is_arithmetic_v<FLT3>
bool ts::xml::Element::getFloatAttribute ( FLT & value,
const UString & name,
bool required = false,
FLT1 def_value = static_cast<FLT>(0.0),
FLT2 min_value = std::numeric_limits<FLT>::lowest(),
FLT3 max_value = std::numeric_limits<FLT>::max() ) const

Get a floating-point attribute of an XML element.

Template Parameters
FLTA floating-point type.
Parameters
[out]valueReturned value of the attribute.
[in]nameName of the attribute.
[in]requiredIf true, generate an error if the attribute is not found.
[in]def_valueDefault value to return if the attribute is not present.
[in]min_valueMinimum allowed value for the attribute.
[in]max_valueMaximum allowed value for the attribute.
Returns
True on success, false on error.

◆ getFloatChild()

template<typename FLT, typename FLT1, typename FLT2, typename FLT3>
requires std::floating_point<FLT> && std::is_arithmetic_v<FLT1> && std::is_arithmetic_v<FLT2> && std::is_arithmetic_v<FLT3>
bool ts::xml::Element::getFloatChild ( FLT & value,
const UString & name,
bool required = false,
FLT1 def_value = static_cast<FLT>(0.0),
FLT2 min_value = std::numeric_limits<FLT>::lowest(),
FLT3 max_value = std::numeric_limits<FLT>::max() ) const

Get a floating-point value in a child of the element.

Template Parameters
FLTA floating-point type.
Parameters
[out]valueReturned value of the child.
[in]nameName of the child to search.
[in]requiredIf true, generate an error if the child is not found.
[in]def_valueDefault value to return if the child is not present.
[in]min_valueMinimum allowed value for the child.
[in]max_valueMaximum allowed value for the child.
Returns
True on success, false on error.

◆ setOptionalFloatAttribute()

template<typename FLT>
requires std::floating_point<FLT>
void ts::xml::Element::setOptionalFloatAttribute ( const UString & name,
const std::optional< FLT > & value,
size_t width = 0,
size_t precision = 6,
bool force_sign = false )
inline

Set an optional attribute with a floating-point value to a node.

Template Parameters
FLTA floating-point type.
Parameters
[in]nameAttribute name.
[in]valueAttribute optional value. If the variable is not set, no attribute is set.
[in]widthWidth of the formatted number, not including the optional prefix and separator.
[in]precisionPrecision to use after the decimal point. Default is 6 digits.
[in]force_signIf true, force a '+' sign for positive values.

◆ getOptionalFloatAttribute()

template<typename FLT, typename FLT1, typename FLT2>
requires std::floating_point<FLT> && std::is_arithmetic_v<FLT1> && std::is_arithmetic_v<FLT2>
bool ts::xml::Element::getOptionalFloatAttribute ( std::optional< FLT > & value,
const UString & name,
FLT1 min_value = std::numeric_limits<FLT>::lowest(),
FLT2 max_value = std::numeric_limits<FLT>::max() ) const

Get an optional floating-point attribute of an XML element.

Template Parameters
FLTA floating-point type.
Parameters
[out]valueReturned value of the attribute. If the attribute is not present, the variable is reset.
[in]nameName of the attribute.
[in]min_valueMinimum allowed value for the attribute.
[in]max_valueMaximum allowed value for the attribute.
Returns
True on success, false on error.

◆ getVariableFloatAttribute()

template<typename FLT, typename FLT1 = FLT, typename FLT2 = FLT, typename FLT3 = FLT>
requires std::floating_point<FLT> && std::is_arithmetic_v<FLT1> && std::is_arithmetic_v<FLT2> && std::is_arithmetic_v<FLT3>
bool ts::xml::Element::getVariableFloatAttribute ( std::optional< FLT > & value,
const UString & name,
bool required = false,
FLT1 def_value = static_cast<FLT>(0),
FLT2 min_value = std::numeric_limits<FLT>::lowest(),
FLT3 max_value = std::numeric_limits<FLT>::max() ) const
inline

Get an optional floating-point attribute of an XML element. getVariableFloatAttribute() is different from getOptionalFloatAttribute() in the result. With getOptionalFloatAttribute(), if the attribute is missing, the std::optional is unset. With getVariableFloatAttribute(), if the attribute is missing, the std::optional is set with the default value.

Template Parameters
FLTA floating-point type.
Parameters
[out]valueReturned value of the attribute.
[in]nameName of the attribute.
[in]requiredIf true, generate an error if the attribute is not found.
[in]def_valueDefault value to return if the attribute is not present.
[in]min_valueMinimum allowed value for the attribute.
[in]max_valueMaximum allowed value for the attribute.
Returns
True on success, false on error.

◆ setChronoAttribute()

template<class Rep, class Period>
void ts::xml::Element::setChronoAttribute ( const UString & name,
cn::duration< Rep, Period > value,
bool hexa = false )
inline

Set an attribute with a std::chrono::duration value to a node.

Parameters
[in]nameAttribute name.
[in]valueAttribute value.
[in]hexaIf true, use an hexadecimal representation (0x...).

◆ getChronoAttribute()

template<class Rep, class Period>
bool ts::xml::Element::getChronoAttribute ( cn::duration< Rep, Period > & value,
const UString & name,
bool required = false,
const cn::duration< Rep, Period > & def_value = cn::duration<Rep, Period>::zero(),
const cn::duration< Rep, Period > & min_value = cn::duration<Rep, Period>::min(),
const cn::duration< Rep, Period > & max_value = cn::duration<Rep, Period>::max() ) const

Get a std::chrono::duration attribute of an XML element.

Parameters
[out]valueReturned value of the attribute.
[in]nameName of the attribute.
[in]requiredIf true, generate an error if the attribute is not found.
[in]def_valueDefault value to return if the attribute is not present.
[in]min_valueMinimum allowed value for the attribute.
[in]max_valueMaximum allowed value for the attribute.
Returns
True on success, false on error.

◆ getISODurationAttribute()

bool ts::xml::Element::getISODurationAttribute ( cn::milliseconds & value,
const UString & name,
bool required = false,
bool strict = false,
const cn::milliseconds & def_value = cn::milliseconds::zero(),
const cn::milliseconds & min_value = cn::milliseconds::min(),
const cn::milliseconds & max_value = cn::milliseconds::max() ) const

Get a std::chrono::milliseconds attribute in ISO 8601 representation of an XML element.

Parameters
[out]valueReturned value of the attribute.
[in]nameName of the attribute.
[in]requiredIf true, generate an error if the attribute is not found.
[in]strictIf true, generate an error if the value of the attribute is invalid. When false, an invalid value is silently transformed in the default value.
[in]def_valueDefault value to return if the attribute is not present.
[in]min_valueMinimum allowed value for the attribute.
[in]max_valueMaximum allowed value for the attribute.
Returns
True on success, false on error.

◆ setDateTimeAttribute()

void ts::xml::Element::setDateTimeAttribute ( const UString & name,
const Time & value )
inline

Set a date/time attribute of an XML element.

Parameters
[in]nameAttribute name.
[in]valueAttribute value.

◆ getDateTimeAttribute()

bool ts::xml::Element::getDateTimeAttribute ( Time & value,
const UString & name,
bool required = false,
const Time & def_value = Time() ) const

Get a date/time attribute of an XML element.

Parameters
[out]valueReturned value of the attribute.
[in]nameName of the attribute.
[in]requiredIf true, generate an error if the attribute is not found.
[in]def_valueDefault value to return if the attribute is not present.
Returns
True on success, false on error.

◆ getISODateTimeAttribute() [1/2]

bool ts::xml::Element::getISODateTimeAttribute ( Time & value,
const UString & name,
bool required = false,
bool strict = false,
const Time & def_value = Time() ) const

Get a date/time attribute in ISO 8601 representation of an XML element.

Parameters
[out]valueReturned value of the attribute.
[in]nameName of the attribute.
[in]requiredIf true, generate an error if the attribute is not found.
[in]strictIf true, generate an error if the value of the attribute is invalid. When false, an invalid value is silently transformed in the default value.
[in]def_valueDefault value to return if the attribute is not present.
Returns
True on success, false on error.

◆ getISODateTimeAttribute() [2/2]

bool ts::xml::Element::getISODateTimeAttribute ( ISOTime & value,
const UString & name,
bool required = false,
bool strict = false ) const

Get a date/time attribute in ISO 8601 representation of an XML element. This version is more generic than the one returning a simple Time value. It can receive any form of ISO 8601 data, include time intervals. There is no default value, it returns an invalid ISOTime as default value.

Parameters
[out]valueReturned value of the attribute.
[in]nameName of the attribute.
[in]requiredIf true, generate an error if the attribute is not found.
[in]strictIf true, generate an error if the value of the attribute is invalid. When false, an invalid value is silently transformed in the default value.
Returns
True on success, false on error.

◆ getISODateTimeChild() [1/2]

bool ts::xml::Element::getISODateTimeChild ( Time & value,
const UString & name,
bool required = false,
bool strict = false,
const Time & def_value = Time() ) const

Get a date/time child element in ISO 8601 representation.

Parameters
[out]valueReturned value of the attribute.
[in]nameName of the child to search.
[in]requiredIf true, generate an error if the child is not found.
[in]strictIf true, generate an error if the value of the attribute is invalid. When false, an invalid value is silently transformed in the default value.
[in]def_valueDefault value to return if the attribute is not present.
Returns
True on success, false on error.

◆ getISODateTimeChild() [2/2]

bool ts::xml::Element::getISODateTimeChild ( ISOTime & value,
const UString & name,
bool required = false,
bool strict = false ) const

Get a date/time child element in ISO 8601 representation. This version is more generic than the one returning a simple Time value. It can receive any form of ISO 8601 data, include time intervals. There is no default value, it returns an invalid ISOTime as default value.

Parameters
[out]valueReturned value of the attribute.
[in]nameName of the child to search.
[in]requiredIf true, generate an error if the child is not found.
[in]strictIf true, generate an error if the value of the attribute is invalid. When false, an invalid value is silently transformed in the default value.
Returns
True on success, false on error.

◆ setOptionalDateTimeAttribute()

void ts::xml::Element::setOptionalDateTimeAttribute ( const UString & name,
const std::optional< Time > & value )
inline

Set an optional date/time attribute of an XML element.

Parameters
[in]nameAttribute name.
[in]valueAttribute value.

◆ getOptionalDateTimeAttribute()

bool ts::xml::Element::getOptionalDateTimeAttribute ( std::optional< Time > & value,
const UString & name ) const

Get an optional date/time attribute of an XML element.

Parameters
[out]valueReturned value of the attribute.
[in]nameName of the attribute.
Returns
True on success, false on error.

◆ setDateAttribute()

void ts::xml::Element::setDateAttribute ( const UString & name,
const Time & value )
inline

Set a date (without hours) attribute of an XML element.

Parameters
[in]nameAttribute name.
[in]valueAttribute value.

◆ getDateAttribute()

bool ts::xml::Element::getDateAttribute ( Time & value,
const UString & name,
bool required = false,
const Time & def_value = Time() ) const

Get a date (without hours) attribute of an XML element.

Parameters
[out]valueReturned value of the attribute.
[in]nameName of the attribute.
[in]requiredIf true, generate an error if the attribute is not found.
[in]def_valueDefault value to return if the attribute is not present.
Returns
True on success, false on error.

◆ setOptionalDateAttribute()

void ts::xml::Element::setOptionalDateAttribute ( const UString & name,
const std::optional< Time > & value )
inline

Set an optional date (xithout hours) attribute of an XML element.

Parameters
[in]nameAttribute name.
[in]valueAttribute value.

◆ getOptionalDateAttribute()

bool ts::xml::Element::getOptionalDateAttribute ( std::optional< Time > & value,
const UString & name ) const

Get an optional date (without hours) attribute of an XML element.

Parameters
[out]valueReturned value of the attribute.
[in]nameName of the attribute.
Returns
True on success, false on error.

◆ setTimeAttribute()

template<class Rep, class Period>
void ts::xml::Element::setTimeAttribute ( const UString & name,
const cn::duration< Rep, Period > & value )
inline

Set a time attribute of an XML element in "hh:mm:ss" format.

Parameters
[in]nameAttribute name.
[in]valueAttribute value.

◆ getTimeAttribute() [1/2]

template<class Rep, class Period>
bool ts::xml::Element::getTimeAttribute ( cn::duration< Rep, Period > & value,
const UString & name,
bool required = false ) const
inline

Get a time attribute of an XML element in "hh:mm:ss" format.

Parameters
[out]valueReturned value of the attribute.
[in]nameName of the attribute.
[in]requiredIf true, generate an error if the attribute is not found.
Returns
True on success, false on error.

◆ getTimeAttribute() [2/2]

template<class Rep1, class Period1, class Rep2, class Period2>
bool ts::xml::Element::getTimeAttribute ( cn::duration< Rep1, Period1 > & value,
const UString & name,
bool required,
const cn::duration< Rep2, Period2 > & def_value ) const

Get a time attribute of an XML element in "hh:mm:ss" format.

Parameters
[out]valueReturned value of the attribute.
[in]nameName of the attribute.
[in]requiredIf true, generate an error if the attribute is not found.
[in]def_valueDefault value to return if the attribute is not present.
Returns
True on success, false on error.

◆ setOptionalTimeAttribute()

template<class Rep, class Period>
void ts::xml::Element::setOptionalTimeAttribute ( const UString & name,
const std::optional< cn::duration< Rep, Period > > & value )
inline

Set an optional time attribute of an XML element in "hh:mm:ss" format.

Parameters
[in]nameAttribute name.
[in]valueAttribute value.

◆ getOptionalTimeAttribute()

template<class Rep, class Period>
bool ts::xml::Element::getOptionalTimeAttribute ( std::optional< cn::duration< Rep, Period > > & value,
const UString & name ) const

Get an optional time attribute of an XML element in "hh:mm:ss" format.

Parameters
[out]valueReturned value of the attribute.
[in]nameName of the attribute.
Returns
True on success, false on error.

◆ setIPAttribute()

void ts::xml::Element::setIPAttribute ( const UString & name,
const IPAddress & value )
inline

Set an IPv4 or IPv6 address attribute of an XML element.

Parameters
[in]nameAttribute name.
[in]valueAttribute value.

◆ getIPAttribute()

bool ts::xml::Element::getIPAttribute ( IPAddress & value,
const UString & name,
bool required = false,
const IPAddress & def_value = IPAddress() ) const

Get an IPv4 or IPv6 address attribute of an XML element in numerical format or host name.

Parameters
[out]valueReturned value of the attribute.
[in]nameName of the attribute.
[in]requiredIf true, generate an error if the attribute is not found.
[in]def_valueDefault value to return if the attribute is not present.
Returns
True on success, false on error.

◆ getIPChild()

bool ts::xml::Element::getIPChild ( IPAddress & value,
const UString & name,
bool required = false,
const IPAddress & def_value = IPAddress() ) const

Get an IPv4 or IPv6 address in a child of the element, in numerical format or host name.

Parameters
[out]valueReturned value of the child elements.
[in]nameName of the child element to search.
[in]requiredIf true, generate an error if the attribute is not found.
[in]def_valueDefault value to return if the attribute is not present.
Returns
True on success, false on error.

◆ setMACAttribute()

void ts::xml::Element::setMACAttribute ( const UString & name,
const MACAddress & value )
inline

Set a MAC address attribute of an XML element in "x:x:x:x:x:x" format.

Parameters
[in]nameAttribute name.
[in]valueAttribute value.

◆ getMACAttribute()

bool ts::xml::Element::getMACAttribute ( MACAddress & value,
const UString & name,
bool required = false,
const MACAddress & def_value = MACAddress() ) const

Get a MAC address attribute of an XML element in "x:x:x:x:x:x" format.

Parameters
[out]valueReturned value of the attribute.
[in]nameName of the attribute.
[in]requiredIf true, generate an error if the attribute is not found.
[in]def_valueDefault value to return if the attribute is not present.
Returns
True on success, false on error.

◆ merge()

bool ts::xml::Element::merge ( Element * other,
MergeAttributes attr_options = MergeAttributes::ADD )

Recursively merge another element into this one.

Parameters
[in,out]otherAnother element to merge. The other object is destroyed, some of its nodes are reparented into the main object.
[in]attr_optionsWhat to do with attributes when merging nodes with identical tags.
Returns
True on success, false on error.

◆ sort()

void ts::xml::Element::sort ( const UString & name = UString())

Sort children elements by alphabetical order of tag name.

Parameters
[in]nameWhen this parameter is not empty, recursively search for elements with that tag name and sort their children elements.

◆ clone()

virtual Node * ts::xml::Element::clone ( ) const
overridevirtual

Clone the content of the node in a dynamically allocated object. This virtual method must be implemented by subclasses to allocate a object of the right class.

Returns
The address of a new XML node of the same class as this object, same content, same structure.

Implements ts::xml::Node.

◆ clear()

virtual void ts::xml::Element::clear ( )
overridevirtual

Clear the content of the node. The node becomes empty but remains attached to its parent.

Reimplemented from ts::xml::Node.

◆ expandEnvironment()

virtual void ts::xml::Element::expandEnvironment ( bool recurse)
overridevirtual

Expand all environment variables in the XML node. Environment variables are referenced using '${varname}' in text, attributes, names.

Parameters
[in]recurseIf true, apply recursively to all children nodes.

Reimplemented from ts::xml::Node.

◆ typeName()

virtual UString ts::xml::Element::typeName ( ) const
overridevirtual

Return a node type name, mainly for debug purpose.

Returns
Node type name.

Implements ts::xml::Node.

◆ setIignoreNamespace()

virtual void ts::xml::Element::setIignoreNamespace ( bool ignore)
overridevirtual

Specify if namespace is ignored by default when comparing element and attribute names in this node's hierarchy.

Parameters
[in]ignoreIt true, namespace is ignored by default.

Reimplemented from ts::xml::Node.

◆ print()

virtual void ts::xml::Element::print ( TextFormatter & output,
bool keep_node_open = false ) const
overridevirtual

Format the node for an output XML document.

Parameters
[in,out]outputThe output object to format the XML document.
[in]keep_node_openIf true, keep the node open so that children may be printed later.

Implements ts::xml::Node.

◆ printClose()

virtual void ts::xml::Element::printClose ( TextFormatter & output,
size_t levels = std::numeric_limits< size_t >::max() ) const
overridevirtual

Print the closing tags for the node. Typically used after print() when keep_node_open was true. The default implementation is to do nothing. Subclasses may replace this.

Parameters
[in,out]outputThe output object to format the XML document.
[in]levelsNumber of levels to close. By default, close the complete document. If zero, no output is produced.

Reimplemented from ts::xml::Node.

◆ parseNode()

virtual bool ts::xml::Element::parseNode ( TextParser & parser,
const Node * parent,
size_t max_nested )
overrideprotectedvirtual

Parse the node.

Parameters
[in,out]parserThe document parser. On input, the current position of the parser after the tag which identified the node ("<?", "<!- -", etc.) On output, it must be after the last character of the node.
[in]parentCandidate parent node, for information only, do not modify. Can be null.
[in]max_nestedMaximum number of nested levels to explore.
Returns
True on success, false on error.

Implements ts::xml::Node.

◆ lineNumber()

size_t ts::xml::Node::lineNumber ( ) const
inlineinherited

Get the line number in input document.

Returns
The line number in input document, zero if the node was built programmatically.

◆ reparent()

void ts::xml::Node::reparent ( Node * new_parent,
bool last = true )
inherited

Attach the node to a new parent. The node is first detached from its previous parent.

Parameters
[in,out]new_parentNew parent. If zero, the node becomes orphan. In that case, the node will no longer be freed by its parent and must be explicitly deleted.
[in]lastIf true, the child is added at the end of the list of children. If false, it is added at the beginning.

◆ moveBefore()

void ts::xml::Node::moveBefore ( Node * new_sibling)
inlineinherited

Move the node before another node, potentially to a new parent.

Parameters
[in,out]new_siblingA new sibling. The node will be moved before this one.

◆ moveAfter()

void ts::xml::Node::moveAfter ( Node * new_sibling)
inlineinherited

Move the node after another node, potentially to a new parent.

Parameters
[in,out]new_siblingA new sibling. The node will be moved after this one.

◆ move()

void ts::xml::Node::move ( Node * new_sibling,
bool before )
inherited

Move the node before or after another node, potentially to a new parent.

Parameters
[in,out]new_siblingA new sibling. The node will be moved before or after this one.
[in]beforeIf true, move the node before new_sibling, after it otherwise.

◆ parent() [1/2]

const Node * ts::xml::Node::parent ( ) const
inlineinherited

Get the parent's node.

Returns
The parent's node or a null pointer if this is a top-level document.

◆ parent() [2/2]

Node * ts::xml::Node::parent ( )
inlineinherited

Get the parent's node.

Returns
The parent's node or zero if this is a top-level document.

◆ document() [1/2]

const Document * ts::xml::Node::document ( ) const
inlineinherited

Get the document into which the node is located.

Returns
The node's document or zero if there is no document.

◆ document() [2/2]

Document * ts::xml::Node::document ( )
inherited

Get the document into which the node is located.

Returns
The node's document or zero if there is no document.

◆ tweaks()

virtual const Tweaks & ts::xml::Node::tweaks ( ) const
virtualinherited

Get a constant reference to the current XML parsing and formatting tweaks for this node.

Returns
A constant reference to the XML tweaks to apply. When the node is part of a document, get the global tweaks of the document. Otherwise, get the default tweaks.

Reimplemented in ts::xml::Document.

◆ depth()

size_t ts::xml::Node::depth ( ) const
inherited

Get the depth of an XML element.

Returns
The depth of the element, ie. the number of ancestors.

◆ preserveSpace()

bool ts::xml::Node::preserveSpace ( ) const
inherited

Check if the node or one of its ancestors has attribute xml:space="preserve".

Returns
True if spaces shall be preserved.

◆ ignoreNamespace()

bool ts::xml::Node::ignoreNamespace ( ) const
inlineinherited

Check if namespace is ignored by default when comparing element and attribute names in this node's hierarchy.

Returns
True if namespace is ignored by default.

◆ hasChildren()

bool ts::xml::Node::hasChildren ( ) const
inlineinherited

Check if the node has children.

Returns
True if the node has children.

◆ childrenCount()

size_t ts::xml::Node::childrenCount ( ) const
inlineinherited

Get the number of children.

Returns
The number of children.

◆ firstChild() [1/2]

const Node * ts::xml::Node::firstChild ( ) const
inlineinherited

Get the first child of a node.

Returns
The first child of the node or zero if there is no children.

◆ firstChild() [2/2]

Node * ts::xml::Node::firstChild ( )
inlineinherited

Get the first child of a node.

Returns
The first child of the node or zero if there is no children.

◆ lastChild() [1/2]

const Node * ts::xml::Node::lastChild ( ) const
inlineinherited

Get the last child.

Returns
The last child or zero if there is none.

◆ lastChild() [2/2]

Node * ts::xml::Node::lastChild ( )
inlineinherited

Get the last child.

Returns
The last child or nullptr if there is none.

◆ nextSibling() [1/2]

const Node * ts::xml::Node::nextSibling ( ) const
inlineinherited

Get the next sibling node.

Returns
The next sibling node or zero if the node is the last child.

◆ nextSibling() [2/2]

Node * ts::xml::Node::nextSibling ( )
inherited

Get the next sibling node.

Returns
The next sibling node or zero if the node is the last child.

◆ previousSibling() [1/2]

const Node * ts::xml::Node::previousSibling ( ) const
inlineinherited

Get the previous sibling node.

Returns
The previous sibling node or zero if the node is the first child.

◆ previousSibling() [2/2]

Node * ts::xml::Node::previousSibling ( )
inherited

Get the previous sibling node.

Returns
The previous sibling node or zero if the node is the first child.

◆ firstChildElement() [1/2]

const Element * ts::xml::Node::firstChildElement ( ) const
inlineinherited

Get the first child Element of a node.

Returns
The first child Element of the node or zero if there is no child Element.

◆ firstChildElement() [2/2]

Element * ts::xml::Node::firstChildElement ( )
inherited

Get the first child Element of a node.

Returns
The first child Element of the node or zero if there is no child Element.

◆ nextSiblingElement() [1/2]

const Element * ts::xml::Node::nextSiblingElement ( ) const
inlineinherited

Find the next sibling element.

Returns
Element address or zero if not found.

◆ nextSiblingElement() [2/2]

Element * ts::xml::Node::nextSiblingElement ( )
inherited

Find the next sibling element.

Returns
Element address or zero if not found.

◆ previousSiblingElement() [1/2]

const Element * ts::xml::Node::previousSiblingElement ( ) const
inlineinherited

Find the previous sibling element.

Returns
Element address or zero if not found.

◆ previousSiblingElement() [2/2]

Element * ts::xml::Node::previousSiblingElement ( )
inherited

Find the previous sibling element.

Returns
Element address or zero if not found.

◆ value()

const UString & ts::xml::Node::value ( ) const
inlineinherited

Get the value of the node.

The semantic of the value depends on the node subclass:

  • Comment: Content of the comment, without "<!--" and "-->".
  • Declaration: Content of the declaration, without "<?" and "?>".
  • Document: Empty.
  • Element: Name of the element.
  • Text: Text content of the element, including spaces and new-lines.
  • Unknown: Content of the tag, probably an uninterpreted DTD.
Returns
A constant reference to the node value, as a string.

◆ setValue()

void ts::xml::Node::setValue ( const UString & value)
inlineinherited

Set the value of the node.

Parameters
[in]valueNew value to set.
See also
value()

◆ removeComments()

void ts::xml::Node::removeComments ( bool recurse)
inherited

Remove all comments in the XML node.

Parameters
[in]recurseIf true, apply recursively to all children nodes.

◆ oneLiner()

virtual UString ts::xml::Node::oneLiner ( ) const
virtualinherited

Format the value as a one-liner XML text.

Returns
The formatted one-line XML text.

◆ stickyOutput()

virtual bool ts::xml::Node::stickyOutput ( ) const
virtualinherited

Check if the text shall be stuck to other elements in XML output.

Returns
True if the text shall be stuck to other elements. False by default.

Reimplemented in ts::xml::Text.

◆ escapedString()

UString ts::xml::Node::escapedString ( const UString & text,
const UString & additional_escape,
bool trim_spaces ) const
inherited

Convert a string into HTML-escaped characters, according to the current XML tweaks for the node.

Parameters
[in]textThe text to escape.
[in]additional_escapeAdditional characters to escape (useful for CDATA).
[in]trim_spacesTrim spaces first.
Returns
The transformed string, ready to output.

◆ debug()

UString ts::xml::Node::debug ( ) const
inherited

Build a debug string for the node.

Returns
A debug string for the node.

◆ report()

Report & ts::xml::Node::report ( ) const
inlineinherited

Get a reference to the report object for the XML node.

Returns
A reference to the report object for the XML node.

◆ identifyNextNode()

Node * ts::xml::Node::identifyNextNode ( TextParser & parser)
protectedinherited

Identify the next token in the document.

Parameters
[in,out]parserThe document parser.
Returns
A new node or zero either at end of document or before a "</" sequence. The returned node, when not zero, is not yet linked to its parent and siblings. When the returned node is not zero, the parser is located after the tag which identified the node ("<?", "<!- -", etc.)

◆ parseChildren()

virtual bool ts::xml::Node::parseChildren ( TextParser & parser,
size_t max_nested )
protectedvirtualinherited

Parse children nodes and add them to the node. Stop either at end of document or before a "</" sequence or on error.

Parameters
[in,out]parserThe document parser.
[in]max_nestedMaximum number of nested levels to explore.
Returns
True on success, false on error.

◆ setPreserveSpace()

void ts::xml::Node::setPreserveSpace ( bool on)
inlineprotectedinherited

Called by the subclass when its spaces shall be preserved. Typically called when xml:space="preserve" is encountered.

Parameters
[in]onTrue is spaces shall be preserved.

◆ ringAlone()

bool ts::RingNode::ringAlone ( ) const
inlineinherited

Check if the node is alone in its own ring.

Returns
True if the node is alone in its own ring.

◆ ringRemove()

void ts::RingNode::ringRemove ( )
inherited

Remove the node from the ring it belongs to and creates its own ring.

◆ ringInsertAfter()

void ts::RingNode::ringInsertAfter ( RingNode * o)
inherited

Insert this object in a ring after the specified node.

Parameters
[in]oA node of a ring. This object is inserted after o in the ring.

◆ ringInsertBefore()

void ts::RingNode::ringInsertBefore ( RingNode * o)
inherited

Insert this object in a ring before the specified node.

Parameters
[in]oA node of a ring. This object is inserted before o in the ring.

◆ ringSwap()

void ts::RingNode::ringSwap ( RingNode * o)
inherited

Swap this object and another one in their rings. If the two objects belong to the same ring, their positions are swapped. If they belong to distinct rings, they also move to each other's ring.

Parameters
[in]oThe node to swap with.

◆ ringNext() [1/2]

template<typename T>
T * ts::RingNode::ringNext ( )
inlineinherited

Get the next node in the ring.

Template Parameters
TA superclass of RingNode, the expected type of the next object in the ring.
Returns
Address of the next node in the ring or zero if the next node is not a subclass of T.

◆ ringNext() [2/2]

template<typename T>
const T * ts::RingNode::ringNext ( ) const
inlineinherited

Get the next node in the ring.

Template Parameters
TA superclass of RingNode, the expected type of the next object in the ring.
Returns
Address of the next node in the ring or zero if the next node is not a subclass of T.

◆ ringPrevious() [1/2]

template<typename T>
T * ts::RingNode::ringPrevious ( )
inlineinherited

Get the previous node in the ring.

Template Parameters
TA superclass of RingNode, the expected type of the previous object in the ring.
Returns
Address of the previous node in the ring or zero if the previous node is not a subclass of T.

◆ ringPrevious() [2/2]

template<typename T>
const T * ts::RingNode::ringPrevious ( ) const
inlineinherited

Get the previous node in the ring.

Template Parameters
TA superclass of RingNode, the expected type of the previous object in the ring.
Returns
Address of the previous node in the ring or zero if the previous node is not a subclass of T.

◆ ringSize()

size_t ts::RingNode::ringSize ( ) const
inherited

Count the number of element in the ring. Warning: This method has a linear response time, avoid using it when possible.

Returns
The number of nodes in the ring.

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