XMLElement Class Reference

An object representing an XML element. More...

#include <XMLElement.h++>

Collaboration diagram for XMLElement:

Public Member Functions
String	getName () const
	Get the name of the element.
void	setAttribute (const String &name, const String &value) throw (InvalidArgumentException)
	Set a String attribute in the element.
void	setAttribute (const String &name, int value) throw (InvalidArgumentException)
	Set an integer attribute in the element.
void	setAttribute (const String &name, const int64_t &value) throw (InvalidArgumentException)
	Set a 64-bit integer attribute in the element.
void	setAttribute (const String &name, const double &value) throw (InvalidArgumentException)
	Set a floating point attribute in the element.
void	setAttribute (const String &name, bool value) throw (InvalidArgumentException)
	Set a boolean attribute in the element.
XMLElement &	getParent () throw ()
	Get the parent element of this element.
const XMLElement &	getParent () const throw ()
	Get the parent element of this element.
bool	getAttribute (const String &name, String &value, const String &defaultValue="") const throw (InvalidArgumentException)
	Get the value of a String attribute in the element.
bool	getAttribute (const String &name, int &value, int defaultValue=0) const throw (InvalidArgumentException)
	Get the value of an integer attribute in the element.
bool	getAttribute (const String &name, int64_t &value, const int64_t &defaultValue=0) const throw (InvalidArgumentException)
	Get the value of a 64-bit integer attribute in the element.
bool	getAttribute (const String &name, bool &value, bool defaultValue=false) const throw (InvalidArgumentException)
	Get the value of a boolean attribute in the element.
bool	getAttribute (const String &name, double &value, const double &defaultValue=0.0) const throw (InvalidArgumentException)
	Get the value of a floating point attribute in the element.
void	getAttributeNames (StringVec &names) const
	Get the names of all of the element's attributes.
void	removeAttributes ()
	Remove all attributes from the element.
bool	hasAttributes () const
	Test if the element has any attributes.
bool	hasContent () const
	Test if the element has content.
void	setContent (const String &content)
	Set the element's content.
const String	getContent () const
	Get the element's content.
bool	hasChildren () const
	Test if the element has children.
uint_t	getChildCount () const
	Get the element's child count.
XMLElement &	addChild (const String &name) throw (InvalidArgumentException)
	Add a new child element to the element.
XMLElement &	getChild (const String &name=String::null)
	Get the first child of the element.
const XMLElement &	getChild (const String &name=String::null) const
	Get the first child of the element.
XMLElement &	getChild (uint_t index)
	Get the child at the given index.
const XMLElement &	getChild (uint_t index) const
	Get the child at the given index.
bool	hasChild (const String &name) const throw (InvalidArgumentException)
	Test if the element has at least one child element with the given name.
XMLElement &	operator[] (const String &name) throw (InvalidArgumentException)
	Get the first child with the given name.
XMLElement &	operator[] (const char *name) throw (InvalidArgumentException)
	Get the first child with the given name.
const XMLElement &	operator[] (const String &name) const throw (InvalidArgumentException)
	Get the first child with the given name.
const XMLElement &	operator[] (const char *name) const throw (InvalidArgumentException)
	Get the first child with the given name.
XMLElement &	operator[] (int index) throw (OutOfBoundsException)
	Get the child at the given index.
const XMLElement &	operator[] (int index) const throw (OutOfBoundsException)
	Get the child at the given index.
void	removeChildren ()
	Remove (and delete) all of the child elements.
void	removeChildren (const String &name) throw (InvalidArgumentException)
	Remove (and delete) all of the child elements with the given name.
XMLElement &	operator= (bool val)
	Set the element's content to the string representation of a bool.
XMLElement &	operator= (long val)
	Set the element's content to the string representation of a long.
XMLElement &	operator= (unsigned long val)
	Set the element's content to the string representation of an unsigned long.
XMLElement &	operator= (const int64_t &val)
	Set the element's content to the string representation of an int64_t.
XMLElement &	operator= (const uint64_t &val)
	Set the element's content to the string representation of a uint64_t.
XMLElement &	operator= (float val)
	Set the element's content to the string representation of a float.
XMLElement &	operator= (const double &val)
	Set the element's content to the string representation of a double.
XMLElement &	operator= (const String &val)
	Set the element's content.
bool	toBool () const
	Return the element's content as a bool.
int	toInt () const
	Return the element's content as a long.
uint_t	toUInt () const
	Return the element's content as an unsigned long.
int64_t	toInt64 () const
	Return the element's content as an int64_t.
uint64_t	toUInt64 () const
	Return the element's content as a uint64_t.
float	toFloat () const
	Return the element's content as a float.
double	toDouble () const
	Return the element's content as a double.
String	toString () const
	Return the element's content as a String.
bool	isNull () const
	Test if the element is a "null" element.
	operator const void * () const throw ()
	Boolean evaluation cast operator.
bool	operator! () const
	Test if the element is a "null" element.
void	write (std::ostream &stream, int depth, uint_t tabWidth) const
	Write the element (and its children, recursively) to a stream.
Static Public Member Functions
static void	validateName (const String &name) throw (InvalidArgumentException)
	Determine if an element or attribute name is valid.
Static Public Attributes
static XMLElement	null
	The "null" element.
Friends
class	XMLDocument
class	XMLElementConstIterator
class	XMLElementIterator

Detailed Description

An object representing an XML element.

XMLElement objects cannot be constructed directly by the caller, to reinforce the convention that they are owned by their enclosing XMLDocument.

All methods in this class return XMLElement::null if a matching or requested element was not found; this is a special instance of XMLElement for which isNull() returns true and whose mutator methods are all no-ops.

To iterate over the child elements of a given element elem, use an XMLElementIterator or XMLElementConstIterator.

Author:: Mark Lindner

Member Function Documentation

XMLElement & addChild ( const String & name ) throw (InvalidArgumentException)

Add a new child element to the element.

Parameters:

name

The name for the new element.

Returns:: A reference to the new XMLElement.

Exceptions:

InvalidArgumentException

If the name is invalid.

bool getAttribute	(	const String &	name,
		double &	value,
		const double &	defaultValue = `0.0`
	)			const throw (InvalidArgumentException)

Get the value of a floating point attribute in the element.

Parameters:

	name	The attribute name.
	value	The value to fill in.
	defaultValue	The value to fill in if the element has no attribute with the given name.

Returns:: true if the value was found, false if the default value was filled in.

Exceptions:

InvalidArgumentException

If the name is invalid.

bool getAttribute	(	const String &	name,
		bool &	value,
		bool	defaultValue = `false`
	)			const throw (InvalidArgumentException)

Get the value of a boolean attribute in the element.

Parameters:

	name	The attribute name.
	value	The value to fill in.
	defaultValue	The value to fill in if the element has no attribute with the given name.

Returns:: true if the value was found, false if the default value was filled in.

Exceptions:

InvalidArgumentException

If the name is invalid.

bool getAttribute	(	const String &	name,
		int64_t &	value,
		const int64_t &	defaultValue = `0`
	)			const throw (InvalidArgumentException)

Get the value of a 64-bit integer attribute in the element.

Parameters:

	name	The attribute name.
	value	The value to fill in.
	defaultValue	The value to fill in if the element has no attribute with the given name.

Returns:: true if the value was found, false if the default value was filled in.

Exceptions:

InvalidArgumentException

If the name is invalid.

bool getAttribute	(	const String &	name,
		int &	value,
		int	defaultValue = `0`
	)			const throw (InvalidArgumentException)

Get the value of an integer attribute in the element.

Parameters:

	name	The attribute name.
	value	The value to fill in.
	defaultValue	The value to fill in if the element has no attribute with the given name.

Returns:: true if the value was found, false if the default value was filled in.

Exceptions:

InvalidArgumentException

If the name is invalid.

bool getAttribute	(	const String &	name,
		String &	value,
		const String &	defaultValue = `""`
	)			const throw (InvalidArgumentException)

Get the value of a String attribute in the element.

Parameters:

	name	The attribute name.
	value	The value to fill in.
	defaultValue	The value to fill in if the element has no attribute with the given name.

Returns:: true if the value was found, false if the default value was filled in.

Exceptions:

InvalidArgumentException

If the name is invalid.

void getAttributeNames ( StringVec & names ) const

Get the names of all of the element's attributes.

Parameters:

names

The vector in which to place the names.

const XMLElement & getChild ( uint_t index ) const

Get the child at the given index.

Parameters:

index

The index.

Returns:: The child element, or XMLElement::null if the index is out of range.

XMLElement & getChild ( uint_t index )

Get the child at the given index.

Parameters:

index

The index.

Returns:: The child element, or XMLElement::null if the index is out of range.

const XMLElement & getChild ( const String & name = String::null ) const

Get the first child of the element.

Parameters:

name

If not String::null, gets the firt child element with the given name.

Returns:: The first child element, or XMLElement::null if no matching element was found.

XMLElement & getChild ( const String & name = String::null )

Get the first child of the element.

Parameters:

name

If not String::null, gets the firt child element with the given name.

Returns:: The first child element, or XMLElement::null if no matching element was found.

uint_t getChildCount ( ) const

Get the element's child count.

Returns:: The number of child elements.

const String getContent ( ) const [inline]

Get the element's content.

Returns:: The content.

String getName ( ) const [inline]

Get the name of the element.

const XMLElement & getParent ( ) const throw ()

Get the parent element of this element.

Returns:: The parent element, or XMLElement::null if the element has no parent (i.e., if it is the root element).

XMLElement & getParent ( ) throw ()

Get the parent element of this element.

Returns:: The parent element, or XMLElement::null if the element has no parent (i.e., if it is the root element).

bool hasAttributes ( ) const

Test if the element has any attributes.

Returns:: true if the element has at least one attribute, false otherwise.

bool hasChild ( const String & name ) const throw (InvalidArgumentException)

Test if the element has at least one child element with the given name.

Parameters:

name

The name.

Returns:: true if a child with the given name exists, false otherwise.

Exceptions:

InvalidArgumentException

If the name is invalid.

bool hasChildren ( ) const

Test if the element has children.

Returns:: true if the element has at least one child, false otherwise.

bool hasContent ( ) const [inline]

Test if the element has content.

Returns:: true if the element has content (including content that consists solely of whitespace characters), false otherwise.

bool isNull ( ) const [inline]

Test if the element is a "null" element.

operator const void * ( ) const throw () [inline]

Boolean evaluation cast operator.

bool operator! ( ) const [inline]

Test if the element is a "null" element.

XMLElement & operator= ( const String & val )

Set the element's content.

Equivalent to setContent().

XMLElement & operator= ( const double & val )

Set the element's content to the string representation of a double.

XMLElement & operator= ( float val )

Set the element's content to the string representation of a float.

XMLElement & operator= ( const uint64_t & val )

Set the element's content to the string representation of a uint64_t.

XMLElement & operator= ( const int64_t & val )

Set the element's content to the string representation of an int64_t.

XMLElement & operator= ( unsigned long val )

Set the element's content to the string representation of an unsigned long.

XMLElement & operator= ( long val )

Set the element's content to the string representation of a long.

XMLElement & operator= ( bool val )

Set the element's content to the string representation of a bool.

const XMLElement & operator[] ( int index ) const throw (OutOfBoundsException)

Get the child at the given index.

Parameters:

index

The index.

Returns:: A reference to the child element, or XMLElement::null if the index is out of range. throw OutOfBoundsException If the index is negative.

XMLElement & operator[] ( int index ) throw (OutOfBoundsException)

Get the child at the given index.

Parameters:

index

The index.

Returns:: The child element, or XMLElement::null if if the index is out of range. throw OutOfBoundsException If the index is negative.

const XMLElement& operator[] ( const char * name ) const throw (InvalidArgumentException) [inline]

Get the first child with the given name.

Parameters:

name

The name.

Returns:: The first matching child element, or XMLElement::null if no matching element was found.

Exceptions:

InvalidArgumentException

If the name is invalid.

const XMLElement& operator[] ( const String & name ) const throw (InvalidArgumentException) [inline]

Get the first child with the given name.

Parameters:

name

The name.

Returns:: The first matching child element, or XMLElement::null if no matching element was found.

Exceptions:

InvalidArgumentException

If the name is invalid.

XMLElement & operator[] ( const char * name ) throw (InvalidArgumentException)

Get the first child with the given name.

If no such child exists, a new child with the given name is automatically added.

Parameters:

name

The name.

Returns:: A reference to the child element.

Exceptions:

InvalidArgumentException

If the name is invalid.

XMLElement & operator[] ( const String & name ) throw (InvalidArgumentException)

Get the first child with the given name.

If no such child exists, a new child with the given name is automatically added.

Parameters:

name

The name.

Returns:: A reference to the child element.

Exceptions:

InvalidArgumentException

If the name is invalid.

void removeAttributes ( )

Remove all attributes from the element.

void removeChildren ( const String & name ) throw (InvalidArgumentException)

Remove (and delete) all of the child elements with the given name.

Parameters:

name

The name.

Exceptions:

InvalidArgumentException

If the name is invalid.

void removeChildren ( )

Remove (and delete) all of the child elements.

void setAttribute	(	const String &	name,
		bool	value
	)			throw (InvalidArgumentException)

Set a boolean attribute in the element.

Parameters:

	name	The attribute name.
	value	The attribute value. If the element already contains an attribute with the given name, the old value is overwritten.

Exceptions:

InvalidArgumentException

If the name is invalid.

void setAttribute	(	const String &	name,
		const double &	value
	)			throw (InvalidArgumentException)

Set a floating point attribute in the element.

Parameters:

	name	The attribute name.
	value	The attribute value. If the element already contains an attribute with the given name, the old value is overwritten.

Exceptions:

InvalidArgumentException

If the name is invalid.

void setAttribute	(	const String &	name,
		const int64_t &	value
	)			throw (InvalidArgumentException)

Set a 64-bit integer attribute in the element.

Parameters:

	name	The attribute name.
	value	The attribute value. If the element already contains an attribute with the given name, the old value is overwritten.

Exceptions:

InvalidArgumentException

If the name is invalid.

void setAttribute	(	const String &	name,
		int	value
	)			throw (InvalidArgumentException)

Set an integer attribute in the element.

Parameters:

	name	The attribute name.
	value	The attribute value. If the element already contains an attribute with the given name, the old value is overwritten.

Exceptions:

InvalidArgumentException

If the name is invalid.

void setAttribute	(	const String &	name,
		const String &	value
	)			throw (InvalidArgumentException)

Set a String attribute in the element.

Parameters:

	name	The attribute name.
	value	The attribute value. If the element already contains an attribute with the given name, the old value is overwritten.

Exceptions:

InvalidArgumentException

If the name is invalid.

void setContent ( const String & content ) [inline]

Set the element's content.

Parameters:

content

The content.

bool toBool ( ) const

Return the element's content as a bool.

double toDouble ( ) const

Return the element's content as a double.

float toFloat ( ) const

Return the element's content as a float.

int toInt ( ) const

Return the element's content as a long.

int64_t toInt64 ( ) const

Return the element's content as an int64_t.

String toString ( ) const [inline]

Return the element's content as a String.

Equivalent to getContent().

uint_t toUInt ( ) const

Return the element's content as an unsigned long.

uint64_t toUInt64 ( ) const

Return the element's content as a uint64_t.

void validateName ( const String & name ) throw (InvalidArgumentException) [static]

Determine if an element or attribute name is valid.

void write	(	std::ostream &	stream,
		int	depth,
		uint_t	tabWidth
	)			const

Write the element (and its children, recursively) to a stream.

Friends And Related Function Documentation

friend class XMLDocument [friend]

friend class XMLElementConstIterator [friend]

friend class XMLElementIterator [friend]

Member Data Documentation

XMLElement null [static]

The "null" element.

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

XMLElement Class Reference

Public Member Functions

Static Public Member Functions

Static Public Attributes

Friends

Detailed Description

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation