Structured element in an XML document. More...

#include <tsxmlElement.h>

Inheritance diagram for ts::xml::Element:

[legend]

Collaboration diagram for ts::xml::Element:

[legend]

Public Member Functions
	Element (const Element &other)
	Copy constructor.

	Element (Node *parent, const UString &name, CaseSensitivity attributeCase=CASE_INSENSITIVE, bool last=true)
	Constructor.

	Element (Report &report=(ts::NullReport::Instance()), size_t line=0, CaseSensitivity attributeCase=CASE_INSENSITIVE)
	Constructor.

Element *	addElement (const UString &childName)
	Add a new child element at the end of children.

Text *	addHexaText (const ByteBlock &data, bool onlyNotEmpty=false)
	Add a new text containing hexadecimal data inside this node.

Text *	addHexaText (const void *data, size_t size, bool onlyNotEmpty=false)
	Add a new text containing hexadecimal data inside this node.

Text *	addHexaTextChild (const UString &name, const ByteBlock &data, bool onlyNotEmpty=false)
	Add a new child element containing an hexadecimal data text.

Text *	addHexaTextChild (const UString &name, const void *data, size_t size, bool onlyNotEmpty=false)
	Add a new child element containing an hexadecimal data text.

Text *	addText (const UString &text, bool onlyNotEmpty=false)
	Add a new text inside this node.

const Attribute &	attribute (const UString &attributeName, bool silent=false) const
	Get an attribute.

size_t	childrenCount () const
	Get the number of children.

virtual void	clear () override
	Clear the content of the node.

virtual Node *	clone () const override
	Clone the content of the node in a dynamically allocated object.

UString	debug () const
	Build a debug string for the node.

void	deleteAttribute (const UString &name)
	Delete an attribute.

size_t	depth () const
	Get the depth of an XML element.

Document *	document ()
	Get the document into which the node is located.

const Document *	document () const
	Get the document into which the node is located.

Element *	findFirstChild (const UString &name, bool silent=false)
	Find the first child element by name, case-insensitive.

const Element *	findFirstChild (const UString &name, bool silent=false) const
	Find the first child element by name, case-insensitive.

Node *	firstChild ()
	Get the first child of a node.

const Node *	firstChild () const
	Get the first child of a node.

Element *	firstChildElement ()
	Get the first child Element of a node.

const Element *	firstChildElement () const
	Get the first child Element of a node.

bool	getAttribute (UString &value, const UString &name, bool required=false, const UString &defValue=UString(), size_t minSize=0, size_t maxSize=UNLIMITED) const
	Get a string attribute of an XML element.

void	getAttributes (std::map< UString, UString > &attr) const
	Get the list of all attributes.

size_t	getAttributesCount () const
	Get the number of attributes in the element.

void	getAttributesNames (UStringList &names) const
	Get the list of all attribute names.

void	getAttributesNamesInModificationOrder (UStringList &names) const
	Get the list of all attribute names, sorted by modification order.

bool	getBoolAttribute (bool &value, const UString &name, bool required=false, bool defValue=false) const
	Get a boolean attribute of an XML element.

bool	getChildren (ElementVector &children, const UString &name, size_t minCount=0, size_t maxCount=UNLIMITED) const
	Find all children elements by name, case-insensitive.

template<class Rep , class Period >
bool	getChronoAttribute (cn::duration< Rep, Period > &value, const UString &name, bool required=false, const cn::duration< Rep, Period > &defValue=cn::duration< Rep, Period >::zero(), const cn::duration< Rep, Period > &minValue=cn::duration< Rep, Period >::min(), const cn::duration< Rep, Period > &maxValue=cn::duration< Rep, Period >::max()) const
	Get a std::chrono::duration attribute of an XML element.

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 minValue=std::numeric_limits< typename ts::underlying_type< INT >::type >::min(), INT2 maxValue=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.

bool	getDateAttribute (Time &value, const UString &name, bool required=false, const Time &defValue=Time()) const
	Get a date (without hours) attribute of an XML element.

bool	getDateTimeAttribute (Time &value, const UString &name, bool required=false, const Time &defValue=Time()) const
	Get a date/time attribute of an XML element.

template<typename INT , typename INT1 = INT> requires ts::int_enum<INT> && ts::int_enum<INT1>
bool	getEnumAttribute (INT &value, const Enumeration &definition, const UString &name, bool required=false, INT1 defValue=INT(0)) const
	Get an enumeration attribute of an XML element.

template<typename INT , typename INT1 = INT> requires ts::int_enum<INT> && ts::int_enum<INT1>
bool	getEnumAttribute (std::optional< INT > &value, const Enumeration &definition, const UString &name, bool required=false, INT1 defValue=INT(0)) const
	Get an enumeration attribute of an XML element.

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 defValue=static_cast< FLT >(0.0), FLT2 minValue=std::numeric_limits< FLT >::lowest(), FLT3 maxValue=std::numeric_limits< FLT >::max()) const
	Get a floating-point attribute of an XML element.

bool	getHexaText (ByteBlock &data, size_t minSize=0, size_t maxSize=UNLIMITED) const
	Get and interpret the hexadecimal data inside the element.

bool	getHexaTextChild (ByteBlock &data, const UString &name, bool required=false, size_t minSize=0, size_t maxSize=UNLIMITED) const
	Get text in a child containing hexadecimal data.

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 defValue=static_cast< INT >(0), INT2 minValue=std::numeric_limits< typename ts::underlying_type< INT >::type >::min(), INT3 maxValue=std::numeric_limits< typename ts::underlying_type< INT >::type >::max()) const
	Get an integer or enum attribute of an XML element.

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 defValue=static_cast< INT >(0), INT2 minValue=std::numeric_limits< typename ts::underlying_type< INT >::type >::min(), INT3 maxValue=std::numeric_limits< typename ts::underlying_type< INT >::type >::max()) const
	Get an integer or enum attribute of an XML element.

bool	getIPAttribute (IPAddress &value, const UString &name, bool required=false, const IPAddress &defValue=IPAddress()) const
	Get an IPv4 or IPv6 address attribute of an XML element in numerical format or host name.

bool	getMACAttribute (MACAddress &value, const UString &name, bool required=false, const MACAddress &defValue=MACAddress()) const
	Get a MAC address attribute of an XML element in "x:x:x:x:x:x" format.

bool	getOptionalAttribute (std::optional< UString > &value, const UString &name, size_t minSize=0, size_t maxSize=UNLIMITED) const
	Get an optional string attribute of an XML element.

bool	getOptionalBoolAttribute (std::optional< bool > &value, const UString &name) const
	Get an optional boolean attribute of an XML element.

bool	getOptionalDateAttribute (std::optional< Time > &value, const UString &name) const
	Get an optional date (without hours) attribute of an XML element.

bool	getOptionalDateTimeAttribute (std::optional< Time > &value, const UString &name) const
	Get an optional date/time attribute of an XML element.

template<typename INT > requires ts::int_enum<INT>
bool	getOptionalEnumAttribute (std::optional< INT > &value, const Enumeration &definition, const UString &name) const
	Get an optional enumeration attribute of an XML element.

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 minValue=std::numeric_limits< FLT >::lowest(), FLT2 maxValue=std::numeric_limits< FLT >::max()) const
	Get an optional floating-point attribute of an XML element.

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 minValue=std::numeric_limits< typename ts::underlying_type< INT >::type >::min(), INT2 maxValue=std::numeric_limits< typename ts::underlying_type< INT >::type >::max()) const
	Get an optional integer or enum attribute of an XML element.

template<class Rep , class Period >
bool	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.

bool	getText (UString &data, bool trim=false, size_t minSize=0, size_t maxSize=UNLIMITED) const
	Get text inside an element.

bool	getTextChild (UString &data, const UString &name, bool trim=false, bool required=false, const UString &defValue=UString(), size_t minSize=0, size_t maxSize=UNLIMITED) const
	Get text in a child of an element.

template<class Rep , class Period >
bool	getTimeAttribute (cn::duration< Rep, Period > &value, const UString &name, bool required=false) const
	Get a time attribute of an XML element in "hh:mm:ss" format.

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 > &defValue) const
	Get a time attribute of an XML element in "hh:mm:ss" format.

bool	getVariableAttribute (std::optional< UString > &value, const UString &name, bool required=false, const UString &defValue=UString(), size_t minSize=0, size_t maxSize=UNLIMITED) const
	Get an optional attribute of an XML element.

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 defValue=static_cast< FLT >(0), FLT2 minValue=std::numeric_limits< FLT >::lowest(), FLT3 maxValue=std::numeric_limits< FLT >::max()) const
	Get an optional floating-point attribute of an XML element.

bool	hasAttribute (const UString &attributeName) const
	Check if an attribute exists in the element.

bool	hasAttribute (const UString &attributeName, const UString &value, bool similar=false) const
	Check if an attribute exists in the element and has the specified value.

bool	hasChildElement (const UString &name) const
	Check if the element contains at least 1 named child element, case-insensitive.

bool	hasChildren () const
	Check if the node has children.

bool	haveSameName (const Element *other) const
	Check if two XML elements have the same name, case-insensitive.

Node *	lastChild ()
	Get the last child.

const Node *	lastChild () const
	Get the last child.

size_t	lineNumber () const
	Get the line number in input document.

bool	merge (Element *other, MergeAttributes attrOptions=MergeAttributes::ADD)
	Recursively merge another element into this one.

void	move (Node *newSibling, bool before)
	Move the node before or after another node, potentially to a new parent.

void	moveAfter (Node *newSibling)
	Move the node after another node, potentially to a new parent.

void	moveBefore (Node *newSibling)
	Move the node before another node, potentially to a new parent.

const UString &	name () const
	Get the element name.

Node *	nextSibling ()
	Get the next sibling node.

const Node *	nextSibling () const
	Get the next sibling node.

Element *	nextSiblingElement ()
	Find the next sibling element.

const Element *	nextSiblingElement () const
	Find the next sibling element.

virtual UString	oneLiner () const
	Format the value as a one-liner XML text.

Node *	parent ()
	Get the parent's node.

const Node *	parent () const
	Get the parent's node.

const UString &	parentName () const
	Get the parent name.

bool	preserveSpace () const
	Check if the node or one of its ancestors has attribute xml:space="preserve".

Node *	previousSibling ()
	Get the previous sibling node.

const Node *	previousSibling () const
	Get the previous sibling node.

Element *	previousSiblingElement ()
	Find the previous sibling element.

const Element *	previousSiblingElement () const
	Find the previous sibling element.

virtual void	print (TextFormatter &output, bool keepNodeOpen=false) const override
	Format the node for an output XML document.

virtual void	printClose (TextFormatter &output, size_t levels=std::numeric_limits< size_t >::max()) const override
	Print the closing tags for the node.

void	removeComments (bool recurse)
	Remove all comments in the XML node.

void	reparent (Node *newParent, bool last=true)
	Attach the node to a new parent.

Report &	report () const
	Get a reference to the report object for the XML node.

bool	ringAlone () const
	Check if the node is alone in its own ring.

void	ringInsertAfter (RingNode *o)
	Insert this object in a ring after the specified node.

void	ringInsertBefore (RingNode *o)
	Insert this object in a ring before the specified node.

template<typename T >
T *	ringNext ()
	Get the next node in the ring.

template<typename T >
const T *	ringNext () const
	Get the next node in the ring.

template<typename T >
T *	ringPrevious ()
	Get the previous node in the ring.

template<typename T >
const T *	ringPrevious () const
	Get the previous node in the ring.

void	ringRemove ()
	Remove the node from the ring it belongs to and creates its own ring.

size_t	ringSize () const
	Count the number of element in the ring.

void	ringSwap (RingNode *o)
	Swap this object and another one in their rings.

void	setAttribute (const UString &name, const UString &value, bool onlyIfNotEmpty=false)
	Set an attribute.

void	setBoolAttribute (const UString &name, bool value)
	Set a bool attribute to a node.

template<class Rep , class Period >
void	setChronoAttribute (const UString &name, cn::duration< Rep, Period > value, bool hexa=false)
	Set an attribute with a std::chrono::duration value to a node.

void	setDateAttribute (const UString &name, const Time &value)
	Set a date (xithout hours) attribute of an XML element.

void	setDateTimeAttribute (const UString &name, const Time &value)
	Set a date/time attribute of an XML element.

template<typename INT > requires ts::int_enum<INT>
void	setEnumAttribute (const Enumeration &definition, const UString &name, INT value)
	Set an enumeration attribute of a node.

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)
	Set an attribute with a floating-point value to a node.

template<typename INT > requires std::integral<INT>
void	setIntAttribute (const UString &name, INT value, bool hexa=false)
	Set an attribute with an integer value to a node.

void	setIPAttribute (const UString &name, const IPAddress &value)
	Set an IPv4 or IPv6 address attribute of an XML element.

void	setMACAttribute (const UString &name, const MACAddress &value)
	Set a MAC address attribute of an XML element in "x:x:x:x:x:x" format.

void	setOptionalAttribute (const UString &name, const std::optional< UString > &value)
	Set an optional attribute to a node.

void	setOptionalBoolAttribute (const UString &name, const std::optional< bool > &value)
	Set an optional bool attribute to a node.

void	setOptionalDateAttribute (const UString &name, const std::optional< Time > &value)
	Set an optional date (xithout hours) attribute of an XML element.

void	setOptionalDateTimeAttribute (const UString &name, const std::optional< Time > &value)
	Set an optional date/time attribute of an XML element.

template<typename INT > requires ts::int_enum<INT>
void	setOptionalEnumAttribute (const Enumeration &definition, const UString &name, const std::optional< INT > &value)
	Set an optional attribute with an enumeration attribute to a node.

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)
	Set an optional attribute with a floating-point value to a node.

template<typename INT > requires std::integral<INT>
void	setOptionalIntAttribute (const UString &name, const std::optional< INT > &value, bool hexa=false)
	Set an optional attribute with an integer value to a node.

template<class Rep , class Period >
void	setOptionalTimeAttribute (const UString &name, const std::optional< cn::duration< Rep, Period > > &value)
	Set an optional time attribute of an XML element in "hh:mm:ss" format.

template<class Rep , class Period >
void	setTimeAttribute (const UString &name, const cn::duration< Rep, Period > &value)
	Set a time attribute of an XML element in "hh:mm:ss" format.

void	setValue (const UString &value)
	Set the value of the node.

void	sort (const UString &name=UString())
	Sort children elements by alphabetical order of tag name.

virtual bool	stickyOutput () const
	Check if the text shall be stuck to other elements in XML output.

UString	text (bool trim=false) const
	Get text inside an element.

virtual const Tweaks &	tweaks () const
	Get a constant reference to the current XML parsing and formatting tweaks for this node.

virtual UString	typeName () const override
	Return a node type name, mainly for debug purpose.

const UString &	value () const
	Get the value of the node.

Protected Member Functions
Node *	identifyNextNode (TextParser &parser)
	Identify the next token in the document.

virtual bool	parseChildren (TextParser &parser)
	Parse children nodes and add them to the node.

virtual bool	parseNode (TextParser &parser, const Node *parent) override
	Parse the node.

void	setPreserveSpace (bool on)
	Called by the subclass when its spaces shall be preserved.

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`,
		CaseSensitivity	attributeCase = `CASE_INSENSITIVE`
	)

explicit

Constructor.

Parameters

[in,out]	report	Where to report errors.
[in]	line	Line number in input document.
[in]	attributeCase	State if attribute names are stored with case sensitivity.

◆ Element() [2/3]

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

Constructor.

Parameters

[in,out]	parent	The parent into which the element is added.
[in]	name	Name of the element.
[in]	attributeCase	State if attribute names are stored wit case sensitivity.
[in]	last	If 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] other Other 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.

◆ haveSameName()

bool ts::xml::Element::haveSameName ( const Element * other ) const

inline

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

Parameters

[in] other Another XML element.

Returns: True is this object and other have identical names.

◆ findFirstChild() [1/2]

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

inline

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

Parameters

[in]	name	Name of the child element to search. If empty, get the first element.
[in]	silent	If true, do not report error.

Returns: Child element address or zero if not found.

◆ findFirstChild() [2/2]

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

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

Parameters

[in]	name	Name of the child element to search. If empty, get the first element.
[in]	silent	If true, do not report error.

Returns: Child element address or zero if not found.

◆ getChildren()

bool ts::xml::Element::getChildren	(	ElementVector &	children,
		const UString &	name,
		size_t	minCount = `0`,
		size_t	maxCount = `UNLIMITED`
	)		const

Find all children elements by name, case-insensitive.

Parameters

[out]	children	Returned vector of all children.
[in]	name	Name of the child element to search.
[in]	minCount	Minimum required number of elements of that name.
[in]	maxCount	Maximum allowed number of elements of that name.

Returns: True on success, false on error.

◆ 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] name Name of the child element to search.

Returns: True if present, false if not present.

◆ getTextChild()

bool ts::xml::Element::getTextChild	(	UString &	data,
		const UString &	name,
		bool	trim = `false`,
		bool	required = `false`,
		const UString &	defValue = `UString()`,
		size_t	minSize = `0`,
		size_t	maxSize = `UNLIMITED`
	)		const

Get text in a child of an element.

Parameters

[out]	data	The content of the text in the child element.
[in]	name	Name of the child element to search.
[in]	trim	If true, remove leading and trailing spaces.
[in]	required	If true, generate an error if the child element is not found.
[in]	defValue	Default value to return if the child element is not present.
[in]	minSize	Minimum allowed size for the value string.
[in]	maxSize	Maximum 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	minSize = `0`,
		size_t	maxSize = `UNLIMITED`
	)		const

Get text inside an element.

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

Parameters

[out]	data	The content of the text children.
[in]	trim	If true, remove leading and trailing spaces.
[in]	minSize	Minimum allowed size for the value string.
[in]	maxSize	Maximum 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] trim If 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	minSize = `0`,
		size_t	maxSize = `UNLIMITED`
	)		const

Get text in a child containing hexadecimal data.

Parameters

[out]	data	The content of the text in the child element.
[in]	name	Name of the child element to search.
[in]	required	If true, generate an error if the child element is not found.
[in]	minSize	Minimum allowed size for the value string.
[in]	maxSize	Maximum allowed size for the value string.

Returns: True on success, false on error.

◆ getHexaText()

bool ts::xml::Element::getHexaText	(	ByteBlock &	data,
		size_t	minSize = `0`,
		size_t	maxSize = `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]	data	Buffer receiving the decoded hexadecimal data.
[in]	minSize	Minimum size of the returned data.
[in]	maxSize	Maximum size of the returned 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] childName Name of new child element to create.

Returns: New child element or null on error.

◆ addText()

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

Add a new text inside this node.

Parameters

[in]	text	Text string to add.
[in]	onlyNotEmpty	When 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	onlyNotEmpty = `false`
	)

Add a new text containing hexadecimal data inside this node.

Parameters

[in]	data	Address of binary data.
[in]	size	Size in bytes of binary data.
[in]	onlyNotEmpty	When 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	onlyNotEmpty = `false`
	)

inline

Add a new text containing hexadecimal data inside this node.

Parameters

[in]	data	Binary data.
[in]	onlyNotEmpty	When 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	onlyNotEmpty = `false`
	)

Add a new child element containing an hexadecimal data text.

Parameters

[in]	name	Name of the child element to search.
[in]	data	Address of binary data.
[in]	size	Size in bytes of binary data.
[in]	onlyNotEmpty	When 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	onlyNotEmpty = `false`
	)

Add a new child element containing an hexadecimal data text.

Parameters

[in]	name	Name of the child element to search.
[in]	data	Binary data.
[in]	onlyNotEmpty	When true, do not add the child element if the data is empty.

Returns: New child element or null on error or empty data.

◆ hasAttribute() [1/2]

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

Check if an attribute exists in the element.

Parameters

[in] attributeName Attribute name.

Returns: True if the attribute exists.

◆ hasAttribute() [2/2]

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

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

Parameters

[in]	attributeName	Attribute name.
[in]	value	Expected value.
[in]	similar	If true, the comparison between the actual and expected values is performed case-insensitive and ignoring blanks. If 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 &	attributeName,
		bool	silent = `false`
	)		const

Get an attribute.

Parameters

[in]	attributeName	Attribute name.
[in]	silent	If true, do not report error.

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] name Attribute name to delete.

◆ setAttribute()

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

Set an attribute.

Parameters

[in]	name	Attribute name.
[in]	value	Attribute value.
[in]	onlyIfNotEmpty	When true, do not insert the attribute if value is empty.

◆ setOptionalAttribute()

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

inline

Set an optional attribute to a node.

Parameters

[in]	name	Attribute name.
[in]	value	Attribute value.

◆ setBoolAttribute()

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

inline

Set a bool attribute to a node.

Parameters

[in]	name	Attribute name.
[in]	value	Attribute value.

◆ 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]	name	Attribute name.
[in]	value	Attribute value.

◆ 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

INT	An integer type.

Parameters

[in]	name	Attribute name.
[in]	value	Attribute value.
[in]	hexa	If true, use an hexadecimal representation (0x...).

◆ 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

INT	An integer type.

Parameters

[in]	name	Attribute name.
[in]	value	Attribute optional value. If the variable is not set, no attribute is set.
[in]	hexa	If true, use an hexadecimal representation (0x...).

◆ 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]	name	Attribute name.
[in]	value	Attribute value.
[in]	hexa	If true, use an hexadecimal representation (0x...).

◆ 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

FLT	A floating-point type.

Parameters

[in]	name	Attribute name.
[in]	value	Attribute value.
[in]	width	Width of the formatted number, not including the optional prefix and separator.
[in]	precision	Precision to use after the decimal point. Default is 6 digits.
[in]	force_sign	If true, force a '+' sign for positive values.

◆ 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

FLT	A floating-point type.

Parameters

[in]	name	Attribute name.
[in]	value	Attribute optional value. If the variable is not set, no attribute is set.
[in]	width	Width of the formatted number, not including the optional prefix and separator.
[in]	precision	Precision to use after the decimal point. Default is 6 digits.
[in]	force_sign	If true, force a '+' sign for positive values.

◆ setEnumAttribute()

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

void ts::xml::Element::setEnumAttribute	(	const Enumeration &	definition,
		const UString &	name,
		INT	value
	)

inline

Set an enumeration attribute of a node.

Template Parameters

INT	An integer or enum type.

Parameters

[in]	definition	The definition of enumeration values.
[in]	name	Attribute name.
[in]	value	Attribute value.

◆ setOptionalEnumAttribute()

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

void ts::xml::Element::setOptionalEnumAttribute	(	const Enumeration &	definition,
		const UString &	name,
		const std::optional< INT > &	value
	)

inline

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

Template Parameters

INT	An integer or enum type.

Parameters

[in]	definition	The definition of enumeration values.
[in]	name	Attribute name.
[in]	value	Attribute optional value. If the variable is not set, no attribute is set.

◆ setDateTimeAttribute()

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

inline

Set a date/time attribute of an XML element.

Parameters

[in]	name	Attribute name.
[in]	value	Attribute value.

◆ 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]	name	Attribute name.
[in]	value	Attribute value.

◆ setDateAttribute()

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

inline

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

Parameters

[in]	name	Attribute name.
[in]	value	Attribute value.

◆ 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]	name	Attribute name.
[in]	value	Attribute value.

◆ 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]	name	Attribute name.
[in]	value	Attribute value.

◆ 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]	name	Attribute name.
[in]	value	Attribute value.

◆ 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]	name	Attribute name.
[in]	value	Attribute value.

◆ 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]	name	Attribute name.
[in]	value	Attribute value.

◆ getAttribute()

bool ts::xml::Element::getAttribute	(	UString &	value,
		const UString &	name,
		bool	required = `false`,
		const UString &	defValue = `UString()`,
		size_t	minSize = `0`,
		size_t	maxSize = `UNLIMITED`
	)		const

Get a string attribute of an XML element.

Parameters

[out]	value	Returned value of the attribute.
[in]	name	Name of the attribute.
[in]	required	If true, generate an error if the attribute is not found.
[in]	defValue	Default value to return if the attribute is not present.
[in]	minSize	Minimum allowed size for the value string.
[in]	maxSize	Maximum allowed size for the value string.

Returns: True on success, false on error.

◆ getOptionalAttribute()

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

Get an optional string attribute of an XML element.

Parameters

[out]	value	Returned value of the attribute. If the attribute is not present, the variable is reset.
[in]	name	Name of the attribute.
[in]	minSize	Minimum allowed size for the value string.
[in]	maxSize	Maximum 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 &	defValue = `UString()`,
		size_t	minSize = `0`,
		size_t	maxSize = `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]	value	Returned value of the attribute. If the attribute is not present, the variable is reset.
[in]	name	Name of the attribute.
[in]	required	If true, generate an error if the attribute is not found.
[in]	defValue	Default value to return if the attribute is not present.
[in]	minSize	Minimum allowed size for the value string.
[in]	maxSize	Maximum allowed size for the value string.

Returns: True on success, false on error.

◆ getBoolAttribute()

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

Get a boolean attribute of an XML element.

Parameters

[out]	value	Returned value of the attribute.
[in]	name	Name of the attribute.
[in]	required	If true, generate an error if the attribute is not found.
[in]	defValue	Default value to return if the attribute is not present.

Returns: True on success, false on error.

◆ 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]	value	Returned value of the attribute.
[in]	name	Name of the attribute.

Returns: True on success, false on error.

◆ 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	defValue = `static_cast<INT>(0)`,
		INT2	minValue = `std::numeric_limits<typename ts::underlying_type<INT>::type>::min()`,
		INT3	maxValue = `std::numeric_limits<typename ts::underlying_type<INT>::type>::max()`
	)		const

Get an integer or enum attribute of an XML element.

Template Parameters

INT	An integer or enum type.

Parameters

[out]	value	Returned value of the attribute.
[in]	name	Name of the attribute.
[in]	required	If true, generate an error if the attribute is not found.
[in]	defValue	Default value to return if the attribute is not present.
[in]	minValue	Minimum allowed value for the attribute.
[in]	maxValue	Maximum 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	defValue = `static_cast<INT>(0)`,
		INT2	minValue = `std::numeric_limits<typename ts::underlying_type<INT>::type>::min()`,
		INT3	maxValue = `std::numeric_limits<typename ts::underlying_type<INT>::type>::max()`
	)		const

inline

Get an integer or enum attribute of an XML element.

Template Parameters

INT	An integer type.

Parameters

[out]	value	Returned value of the attribute. Always set, possibly to the default value.
[in]	name	Name of the attribute.
[in]	required	If true, generate an error if the attribute is not found.
[in]	defValue	Default value to return if the attribute is not present.
[in]	minValue	Minimum allowed value for the attribute.
[in]	maxValue	Maximum allowed value for the attribute.

Returns: True on success, false on error.

◆ 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	minValue = `std::numeric_limits<typename ts::underlying_type<INT>::type>::min()`,
		INT2	maxValue = `std::numeric_limits<typename ts::underlying_type<INT>::type>::max()`
	)		const

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

Template Parameters

INT	An integer or enum type.

Parameters

[out]	value	Returned value of the attribute. If the attribute is not present, the variable is reset.
[in]	name	Name of the attribute.
[in]	minValue	Minimum allowed value for the attribute.
[in]	maxValue	Maximum 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	minValue = `std::numeric_limits<typename ts::underlying_type<INT>::type>::min()`,
		INT2	maxValue = `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

INT	An integer or enum type.

Parameters

[out]	value	Returned value of the attribute. If the attribute is not present, the variable is reset.
[in]	name	Name of the attribute.
[in]	condition	If true, the attribute must be present. If false, the attribute must nbot be present.
[in]	minValue	Minimum allowed value for the attribute.
[in]	maxValue	Maximum allowed value for the attribute.

Returns: True on success, false on error.

◆ 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 Enumeration &	definition,
		const UString &	name,
		bool	required = `false`,
		INT1	defValue = `INT(0)`
	)		const

Get an enumeration attribute of an XML element.

Integer literals and integer values are accepted in the attribute.

Template Parameters

INT	An integer or enum type.

Parameters

[out]	value	Returned value of the attribute.
[in]	definition	The definition of enumeration values.
[in]	name	Name of the attribute.
[in]	required	If true, generate an error if the attribute is not found.
[in]	defValue	Default 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 Enumeration &	definition,
		const UString &	name,
		bool	required = `false`,
		INT1	defValue = `INT(0)`
	)		const

inline

Get an enumeration attribute of an XML element.

Template Parameters

INT	An integer or enum type.

Parameters

[out]	value	Returned value of the attribute. Always set, possibly to the default value.
[in]	definition	The definition of enumeration values.
[in]	name	Name of the attribute.
[in]	required	If true, generate an error if the attribute is not found.
[in]	defValue	Default value to return if the attribute is not present.

Returns: True on success, false on error.

◆ getOptionalEnumAttribute()

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

bool ts::xml::Element::getOptionalEnumAttribute	(	std::optional< INT > &	value,
		const Enumeration &	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

INT	An integer or enum type.

Parameters

[out]	value	Returned value of the attribute. If the attribute is not present, the variable is reset.
[in]	definition	The definition of enumeration values.
[in]	name	Name of the attribute.

Returns: True on success, false on error.

◆ 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	defValue = `static_cast<FLT>(0.0)`,
		FLT2	minValue = `std::numeric_limits<FLT>::lowest()`,
		FLT3	maxValue = `std::numeric_limits<FLT>::max()`
	)		const

Get a floating-point attribute of an XML element.

Template Parameters

FLT	A floating-point type.

Parameters

[out]	value	Returned value of the attribute.
[in]	name	Name of the attribute.
[in]	required	If true, generate an error if the attribute is not found.
[in]	defValue	Default value to return if the attribute is not present.
[in]	minValue	Minimum allowed value for the attribute.
[in]	maxValue	Maximum allowed value for the attribute.

Returns: True on success, false on error.

◆ 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	minValue = `std::numeric_limits<FLT>::lowest()`,
		FLT2	maxValue = `std::numeric_limits<FLT>::max()`
	)		const

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

Template Parameters

FLT	A floating-point type.

Parameters

[out]	value	Returned value of the attribute. If the attribute is not present, the variable is reset.
[in]	name	Name of the attribute.
[in]	minValue	Minimum allowed value for the attribute.
[in]	maxValue	Maximum 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	defValue = `static_cast<FLT>(0)`,
		FLT2	minValue = `std::numeric_limits<FLT>::lowest()`,
		FLT3	maxValue = `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

FLT	A floating-point type.

Parameters

[out]	value	Returned value of the attribute.
[in]	name	Name of the attribute.
[in]	required	If true, generate an error if the attribute is not found.
[in]	defValue	Default value to return if the attribute is not present.
[in]	minValue	Minimum allowed value for the attribute.
[in]	maxValue	Maximum allowed value for the attribute.

Returns: True on success, false on error.

◆ 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 > &	defValue = `cn::duration<Rep, Period>::zero()`,
		const cn::duration< Rep, Period > &	minValue = `cn::duration<Rep, Period>::min()`,
		const cn::duration< Rep, Period > &	maxValue = `cn::duration<Rep, Period>::max()`
	)		const

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

Parameters

[out]	value	Returned value of the attribute.
[in]	name	Name of the attribute.
[in]	required	If true, generate an error if the attribute is not found.
[in]	defValue	Default value to return if the attribute is not present.
[in]	minValue	Minimum allowed value for the attribute.
[in]	maxValue	Maximum allowed value for the attribute.

Returns: True on success, false on error.

◆ getDateTimeAttribute()

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

Get a date/time attribute of an XML element.

Parameters

[out]	value	Returned value of the attribute.
[in]	name	Name of the attribute.
[in]	required	If true, generate an error if the attribute is not found.
[in]	defValue	Default value to return if the attribute is not present.

Returns: True on success, false on error.

◆ 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]	value	Returned value of the attribute.
[in]	name	Name of the attribute.

Returns: True on success, false on error.

◆ getDateAttribute()

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

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

Parameters

[out]	value	Returned value of the attribute.
[in]	name	Name of the attribute.
[in]	required	If true, generate an error if the attribute is not found.
[in]	defValue	Default value to return if the attribute is not present.

Returns: True on success, false on error.

◆ 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]	value	Returned value of the attribute.
[in]	name	Name of the attribute.

Returns: True on success, false on error.

◆ 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]	value	Returned value of the attribute.
[in]	name	Name of the attribute.
[in]	required	If 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 > &	defValue
	)		const

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

Parameters

[out]	value	Returned value of the attribute.
[in]	name	Name of the attribute.
[in]	required	If true, generate an error if the attribute is not found.
[in]	defValue	Default value to return if the attribute is not present.

Returns: True on success, false on error.

◆ 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]	value	Returned value of the attribute.
[in]	name	Name of the attribute.

Returns: True on success, false on error.

◆ getIPAttribute()

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

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

Parameters

[out]	value	Returned value of the attribute.
[in]	name	Name of the attribute.
[in]	required	If true, generate an error if the attribute is not found.
[in]	defValue	Default value to return if the attribute is not present.

Returns: True on success, false on error.

◆ getMACAttribute()

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

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

Parameters

[out]	value	Returned value of the attribute.
[in]	name	Name of the attribute.
[in]	required	If true, generate an error if the attribute is not found.
[in]	defValue	Default value to return if the attribute is not present.

Returns: True on success, false on error.

◆ getAttributesNames()

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

Get the list of all attribute names.

Parameters

[out] names Returned 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] attr Returned 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] names Returned 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.

◆ merge()

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

Recursively merge another element into this one.

Parameters

[in,out]	other	Another element to merge. The other object is destroyed, some of its nodes are reparented into the main object.
[in]	attrOptions	What 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] name When 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.

◆ 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.

◆ print()

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

overridevirtual

Format the node for an output XML document.

Parameters

[in,out]	output	The output object to format the XML document.
[in]	keepNodeOpen	If 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 keepNodeOpen was true. The default implementation is to do nothing. Subclasses may replace this.

Parameters

[in,out]	output	The output object to format the XML document.
[in]	levels	Number 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
	)

overrideprotectedvirtual

Parse the node.

Parameters

[in,out]	parser	The 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]	parent	Candidate parent node, for information only, do not modify. Can be null.

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 *	newParent,
		bool	last = `true`
	)

inherited

Attach the node to a new parent.

The node is first detached from its previous parent.

Parameters

[in,out]	newParent	New 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]	last	If 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 * newSibling )

inlineinherited

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

Parameters

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

◆ moveAfter()

void ts::xml::Node::moveAfter ( Node * newSibling )

inlineinherited

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

Parameters

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

◆ move()

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

inherited

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

Parameters

[in,out]	newSibling	A new sibling. The node will be moved before or after this one.
[in]	before	If true, move the node before newSibling, 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.

◆ 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 "".
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] value New value to set.

See also: value()

◆ removeComments()

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

inherited

Remove all comments in the XML node.

Parameters

[in] recurse If 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.

◆ 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] parser The 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 )

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] parser The document parser.

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] on True 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.

◆ ringInsertAfter()

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

inherited

Insert this object in a ring after the specified node.

Parameters

[in] o A 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] o A 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] o The node to swap with.

◆ ringNext() [1/2]

template<typename T >

T * ts::RingNode::ringNext ( )

inlineinherited

Get the next node in the ring.

Template Parameters

T	A 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

T	A 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

T	A 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

T	A 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:

tsxmlElement.h

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Element() [1/3]

◆ Element() [2/3]

◆ Element() [3/3]

Member Function Documentation

◆ name()

◆ parentName()

◆ haveSameName()

◆ findFirstChild() [1/2]

◆ findFirstChild() [2/2]

◆ getChildren()

◆ hasChildElement()

◆ getTextChild()

◆ getText()

◆ text()

◆ getHexaTextChild()

◆ getHexaText()

◆ addElement()

◆ addText()

◆ addHexaText() [1/2]

◆ addHexaText() [2/2]

◆ addHexaTextChild() [1/2]

◆ addHexaTextChild() [2/2]

◆ hasAttribute() [1/2]

◆ hasAttribute() [2/2]

◆ attribute()

◆ deleteAttribute()

◆ setAttribute()

◆ setOptionalAttribute()

◆ setBoolAttribute()

◆ setOptionalBoolAttribute()

◆ setIntAttribute()

◆ setOptionalIntAttribute()

◆ setChronoAttribute()

◆ setFloatAttribute()

◆ setOptionalFloatAttribute()

◆ setEnumAttribute()

◆ setOptionalEnumAttribute()

◆ setDateTimeAttribute()

◆ setOptionalDateTimeAttribute()

◆ setDateAttribute()

◆ setOptionalDateAttribute()

◆ setTimeAttribute()

◆ setOptionalTimeAttribute()

◆ setIPAttribute()

◆ setMACAttribute()

◆ getAttribute()

◆ getOptionalAttribute()

◆ getVariableAttribute()

◆ getBoolAttribute()

◆ getOptionalBoolAttribute()

◆ getIntAttribute() [1/2]

◆ getIntAttribute() [2/2]

◆ getOptionalIntAttribute()

◆ getConditionalIntAttribute()

◆ getEnumAttribute() [1/2]

◆ getEnumAttribute() [2/2]

◆ getOptionalEnumAttribute()

◆ getFloatAttribute()

◆ getOptionalFloatAttribute()

◆ getVariableFloatAttribute()

◆ getChronoAttribute()

◆ getDateTimeAttribute()

◆ getOptionalDateTimeAttribute()

◆ getDateAttribute()

◆ getOptionalDateAttribute()

◆ getTimeAttribute() [1/2]

◆ getTimeAttribute() [2/2]

◆ getOptionalTimeAttribute()

◆ getIPAttribute()

◆ getMACAttribute()

◆ getAttributesNames()

◆ getAttributes()

◆ getAttributesNamesInModificationOrder()

◆ getAttributesCount()

◆ merge()

◆ sort()