The XML element is a container class. More...

#include <XmlElement.h>

Inheritance diagram for PLCore::XmlElement:

Public Member Functions
PLCORE_API	XmlElement (const String &sValue)
	Constructor.
PLCORE_API	XmlElement (const XmlElement &cSource)
	Copy constructor.
virtual PLCORE_API	~XmlElement ()
	Destructor.
PLCORE_API XmlElement &	operator= (const XmlElement &cSource)
	Copy operator.
PLCORE_API String	GetAttribute (const String &sName) const
	Given an attribute name, 'GetAttribute()' returns the value for the attribute of that name, or empty string if none exists.
PLCORE_API String	GetAttribute (const String &sName, int *pnValue) const
	Given an attribute name, 'GetAttribute()' returns the value for the attribute of that name, or empty string if none exists.
PLCORE_API String	GetAttribute (const String &sName, double *pdValue) const
	Given an attribute name, 'GetAttribute()' returns the value for the attribute of that name, or empty string if none exists.
PLCORE_API EQueryResult	QueryIntAttribute (const String &sName, int *pnValue) const
	Examines the attribute.
PLCORE_API EQueryResult	QueryFloatAttribute (const String &sName, float *pfValue) const
	Examines the attribute.
PLCORE_API EQueryResult	QueryDoubleAttribute (const String &sName, double *pdValue) const
	Examines the attribute.
PLCORE_API void	SetAttribute (const String &sName, const String &sValue)
	Sets an attribute of name to a given value.
PLCORE_API void	SetAttribute (const String &sName, int nValue)
	Sets an attribute of name to a given value.
PLCORE_API void	SetDoubleAttribute (const String &sName, double dValue)
	Sets an attribute of name to a given value.
PLCORE_API void	RemoveAttribute (const String &sName)
	Deletes an attribute with the given name.
XmlAttribute *	GetFirstAttribute ()
	Access the first attribute in this element.
const XmlAttribute *	GetFirstAttribute () const
XmlAttribute *	GetLastAttribute ()
	Access the last attribute in this element.
const XmlAttribute *	GetLastAttribute () const
PLCORE_API String	GetText () const
	Convenience function for easy access to the text inside an element.
virtual PLCORE_API bool	Save (File &cFile, uint32 nDepth=0) override
	Save function.
virtual PLCORE_API String	ToString (uint32 nDepth=0) const override
	Output as string function.
virtual PLCORE_API const char *	Parse (const char pszData, XmlParsingData pData=nullptr, EEncoding nEncoding=EncodingUnknown) override
	Parse the given null terminated block of XML data.
virtual PLCORE_API XmlNode *	Clone () const override
	Create an exact duplicate of this node and return it.

Detailed Description

The XML element is a container class.

Remarks:: An element has a value, the element name, and can contain other elements, text, comments, and unknowns. Elements also contain an arbitrary number of attributes.

Constructor & Destructor Documentation

PLCORE_API PLCore::XmlElement::XmlElement ( const String & sValue )

Constructor.

Parameters:

[in] sValue Value of this element (value = element tag name)

PLCORE_API PLCore::XmlElement::XmlElement ( const XmlElement & cSource )

Copy constructor.

Parameters:

[in] cSource Source to copy from

virtual PLCORE_API PLCore::XmlElement::~XmlElement ( ) [virtual]

Destructor.

Member Function Documentation

PLCORE_API XmlElement& PLCore::XmlElement::operator= ( const XmlElement & cSource )

Copy operator.

Parameters:

[in] cSource Source to copy from

Returns:: Reference to this instance

PLCORE_API String PLCore::XmlElement::GetAttribute ( const String & sName ) const

Given an attribute name, 'GetAttribute()' returns the value for the attribute of that name, or empty string if none exists.

Parameters:

[in] sName Attribute name

Returns:: Attribute value, empty on error

PLCORE_API String PLCore::XmlElement::GetAttribute	(	const String &	sName,
		int *	pnValue
	)		const

Given an attribute name, 'GetAttribute()' returns the value for the attribute of that name, or empty string if none exists.

Parameters:

[in]	sName	Attribute name
[out]	pnValue	If not a null pointer, this variable will receive the integer value - if the attribute value can be converted into an integer, if not, this variable is not touched

Returns:: Attribute value, empty on error

Remarks:: If the attribute exists and can be converted to an integer, the integer value will be put in the return 'pnValue', if 'pnValue' is not a null pointer.

PLCORE_API String PLCore::XmlElement::GetAttribute	(	const String &	sName,
		double *	pdValue
	)		const

Given an attribute name, 'GetAttribute()' returns the value for the attribute of that name, or empty string if none exists.

Parameters:

[in]	sName	Attribute name
[out]	pdValue	If not a null pointer, this variable will receive the double value - if the attribute value can be converted into a double, if not, this variable is not touched

Returns:: Attribute value, empty on error

Remarks:: If the attribute exists and can be converted to an double, the double value will be put in the return 'pdValue', if 'pdValue' is not a null pointer.

PLCORE_API EQueryResult PLCore::XmlElement::QueryIntAttribute	(	const String &	sName,
		int *	pnValue
	)		const

Examines the attribute.

Parameters:

[in]	sName	Attribute name
[out]	pnValue	If not a null pointer, this variable will receive the integer value - if the attribute value can be converted into an integer, if not, this variable is not touched

Returns:: 'Success' if all went fine, 'WrongType' if value is not an integer and 'NoAttribute' if the attribute does not exist

Note:

This function is an alternative to the 'GetAttribute()' function with richer error checking.

PLCORE_API EQueryResult PLCore::XmlElement::QueryFloatAttribute	(	const String &	sName,
		float *	pfValue
	)		const

Examines the attribute.

Parameters:

[in]	sName	Attribute name
[out]	pfValue	If not a null pointer, this variable will receive the float value - if the attribute value can be converted into a float, if not, this variable is not touched

Returns:: 'Success' if all went fine, 'WrongType' if value is not a float and 'NoAttribute' if the attribute does not exist

See also:

QueryIntAttribute()

PLCORE_API EQueryResult PLCore::XmlElement::QueryDoubleAttribute	(	const String &	sName,
		double *	pdValue
	)		const

Examines the attribute.

Parameters:

[in]	sName	Attribute name
[out]	pdValue	If not a null pointer, this variable will receive the double value - if the attribute value can be converted into a double, if not, this variable is not touched

Returns:: 'Success' if all went fine, 'WrongType' if value is not a double and 'NoAttribute' if the attribute does not exist

See also:

QueryIntAttribute()

PLCORE_API void PLCore::XmlElement::SetAttribute	(	const String &	sName,
		const String &	sValue
	)

Sets an attribute of name to a given value.

Parameters:

[in]	sName	Attribute name
[in]	sValue	Attribute value

Remarks:: The attribute will be created if it does not exist, or changed if it does.

PLCORE_API void PLCore::XmlElement::SetAttribute	(	const String &	sName,
		int	nValue
	)

Sets an attribute of name to a given value.

Parameters:

[in]	sName	Attribute name
[in]	nValue	Attribute value

Remarks:: The attribute will be created if it does not exist, or changed if it does.

PLCORE_API void PLCore::XmlElement::SetDoubleAttribute	(	const String &	sName,
		double	dValue
	)

Sets an attribute of name to a given value.

Parameters:

[in]	sName	Attribute name
[in]	dValue	Attribute value

Remarks:: The attribute will be created if it does not exist, or changed if it does.

PLCORE_API void PLCore::XmlElement::RemoveAttribute ( const String & sName )

Deletes an attribute with the given name.

Parameters:

[in] sName Name of the attribute to remove

XmlAttribute * PLCore::XmlElement::GetFirstAttribute ( ) [inline]

Access the first attribute in this element.

Returns:: The first attribute, a null pointer if there's no first attribute

const XmlAttribute * PLCore::XmlElement::GetFirstAttribute ( ) const [inline]

XmlAttribute * PLCore::XmlElement::GetLastAttribute ( ) [inline]

Access the last attribute in this element.

Returns:: The last attribute, a null pointer if there's no last attribute

const XmlAttribute * PLCore::XmlElement::GetLastAttribute ( ) const [inline]

PLCORE_API String PLCore::XmlElement::GetText ( ) const

Convenience function for easy access to the text inside an element.

Remarks:: Although easy and concise, GetText() is limited compared to getting the XmlText child and accessing it directly.

If the first child of 'this' is a XmlText, the GetText() returns the character string of the text node, else null is returned.

This is a convenient method for getting the text of simple contained text:

		*    <foo>This is text</foo>
		*    const char *pszText = fooElement->GetText();
		*

'pszText' will be a pointer to "This is text".

Note that this function can be misleading. If the element foo was created from this XML:

		*    <foo><b>This is text</b></foo>
		*

then the value of str would be null. The first child node isn't a text node, it is another element. From this XML:

		*    <foo>This is <b>text</b></foo>
		*

GetText() will return "This is ".

WARNING: GetText() accesses a child node - don't become confused with the similarly named XmlNode::ToText() which is safe type casts on the referenced node.

Returns:: Text inside an element, or empty string

virtual PLCORE_API bool PLCore::XmlElement::Save	(	File &	cFile,
		uint32	nDepth = `0`
	)		`[override, virtual]`

Save function.

Parameters:

[out]	cFile	File to write in, must be opened and writable
[in]	nDepth	Current depth

Returns:: 'true' if all went fine, else 'false'

Implements PLCore::XmlBase.

virtual PLCORE_API String PLCore::XmlElement::ToString ( uint32 nDepth = 0 ) const [override, virtual]

Output as string function.

Parameters:

[in] nDepth Current depth

Returns:: String containing the XML

Implements PLCore::XmlBase.

virtual PLCORE_API const char* PLCore::XmlElement::Parse	(	const char *	pszData,
		XmlParsingData *	pData = `nullptr`,
		EEncoding	nEncoding = `EncodingUnknown`
	)		`[override, virtual]`

Parse the given null terminated block of XML data.

Parameters:

[in]	pszData	Parsing data, if a null pointer, an error will be returned
[in]	pData	Parsing data, can be a null pointer
[in]	nEncoding	Encoding

Returns:: The pointer to the parameter 'pszData' if all went fine, else a null pointer

Remarks:: Passing in an encoding to this method (either 'EncodingLegacy' or 'EncodingUTF8' will force the parser to use that encoding, regardless of what the parser might otherwise try to detect.

Implements PLCore::XmlBase.

virtual PLCORE_API XmlNode* PLCore::XmlElement::Clone ( ) const [override, virtual]

Create an exact duplicate of this node and return it.

Returns:: The clone, a null pointer on error

Note:

The memory must be deleted by the caller

Implements PLCore::XmlNode.

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

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation