SimTK::Xml::Node Class Reference

Abstract handle for holding any kind of node in an XML tree. More...

Inheritance diagram for SimTK::Xml::Node:

Public Member Functions
bool	operator== (const Node &other) const
	Comparing Nodes for equality means asking if the two Node handles are referring to exactly the same object; two different nodes that happen to have the same properties will not test equal by this criteria. More...
bool	operator!= (const Node &other) const
	Inequality test using same criteria as operator==(). More...
Construction and destruction
These methods are mostly used by the derived node classes; Nodes are not generally created directly in user code.
	Node ()
	Create an empty Node handle that can be used to hold a reference to any kind of Node. More...
	Node (const Node &src)
	Copy constructor is shallow; that is, this handle will refer to the same node as the source. More...
Node &	operator= (const Node &src)
	Copy assignment is shallow; the handle is first cleared and then will refer to the same node as the source. More...
Node	clone () const
	The clone() method makes a deep copy of this Node and its children and returns a new orphan Node with the same contents; ordinary assignment and copy construction is shallow. More...
	~Node ()
	The Node handle destructor does not recover heap space so if you create orphan nodes and then don't put them in a document there will be a memory leak unless you explicitly destruct them first with clearOrphan(). More...
void	clear ()
	This method restores the Node handle to its default-constructed state but does not recover any heap space; use clearOrphan() if you know this node was never put into a document. More...
void	clearOrphan ()
	This method explictly frees the heap space for an orphan node that was created but never inserted into a document. More...
Node classification
You can find out what concrete type of node this abstract Node handle is referring to (if any), who owns the node, and if it is owned by a parent element you can get access to the parent.
NodeType	getNodeType () const
	Get the Xml::NodeType of this node. More...
String	getNodeTypeAsString () const
	Get the Node type as a string; an empty handle returns "NoNode". More...
bool	isValid () const
	Return true if this Node handle is referencing some node, false if the Node handle is empty. More...
bool	isTopLevelNode () const
	Return true if this Node is owned by the top-level Xml document, false if the Node is owned by an Element or is an orphan, or if the Node handle is empty. More...
bool	isOrphan () const
	Return true if this Node is an orphan, meaning that it is not empty, but is not owned by any element or top-level document. More...
bool	hasParentElement () const
	Return true if this node has a parent, i.e. More...
Element	getParentElement ()
	Return a handle referencing this node's parent if it has one, otherwise throws an error; check first with hasParentElement() if you aren't sure. More...
Access to node contents
Usually contents inspection is handled at the concrete node class level; here we can only provide information for which you don't need to know what kind of node this is.
const String &	getNodeText () const
	Return a text value associated with this Node (not including its child nodes if any); the behavior depends on the NodeType. More...
void	writeToString (String &out, bool compact=false) const
	Serialize this node (and everything it contains) to the given String. More...

Friends
class	Xml
class	Xml::Impl
class	Xml::node_iterator
class	Xml::Comment
class	Xml::Unknown
class	Xml::Text
class	Xml::Element

Related Functions
(Note that these are not member functions.)
std::ostream &	operator<< (std::ostream &o, const Xml::Node &xmlNode)
	Output a "pretty printed" textual representation of the given XML node (and all its contents) to an std::ostream. More...

Detailed Description

Abstract handle for holding any kind of node in an XML tree.

The concrete node handle types derived from Node are: Comment, Unknown, Text, and Element. Only an Element node may contain other nodes.

A node may be classified by who owns it. There are three possibilities:

• Top-level node: The node belongs to the top-level Xml document and does not have a parent node.
• Child node: The node belongs to an element, which may be the root element or any lower-level element. The element that owns it is its "parent".
• Orphan node: The node is not yet part of any Xml document and does not belong to an element. In that case the Node handle serves as the owner and the node does not have a parent node.

A Node handle may also be empty, meaning it refers to no node at all so there is nothing to own.

Top-level nodes can only be Comment nodes, Unknown nodes, or the lone root Element node. Child nodes and orphans can be of Element and Text type also. Normally orphans exist only briefly during the time a new node is constructed and the time it is adopted by some element (usually in the same constructor) so you can ignore them for the most part. But if you must keep orphan nodes around, be aware that they must be referenced by only one handle at a time to avoid ownership conflicts.

Constructor & Destructor Documentation

SimTK::Xml::Node::Node ( )

inline

Create an empty Node handle that can be used to hold a reference to any kind of Node.

SimTK::Xml::Node::Node ( const Node &  src )

inline

Copy constructor is shallow; that is, this handle will refer to the same node as the source.

Note that this handle will provide write access to the underlying node, even if the source was const.

SimTK::Xml::Node::~Node ( )

inline

The Node handle destructor does not recover heap space so if you create orphan nodes and then don't put them in a document there will be a memory leak unless you explicitly destruct them first with clearOrphan().

Member Function Documentation

Node& SimTK::Xml::Node::operator= ( const Node &  src )

inline

Copy assignment is shallow; the handle is first cleared and then will refer to the same node as the source.

Note that this handle will provide write access to the underlying node even if the source handle was const.

See also

clear()

Node SimTK::Xml::Node::clone

(

)

const

The clone() method makes a deep copy of this Node and its children and returns a new orphan Node with the same contents; ordinary assignment and copy construction is shallow.

void SimTK::Xml::Node::clear

(

)

This method restores the Node handle to its default-constructed state but does not recover any heap space; use clearOrphan() if you know this node was never put into a document.

void SimTK::Xml::Node::clearOrphan

(

)

This method explictly frees the heap space for an orphan node that was created but never inserted into a document.

It is an error to call this if the node is in a document.

NodeType SimTK::Xml::Node::getNodeType

(

)

const

Get the Xml::NodeType of this node.

If this Node handle is empty, the returned NodeType will be "Xml::NoNode".

String SimTK::Xml::Node::getNodeTypeAsString

(

)

const

Get the Node type as a string; an empty handle returns "NoNode".

bool SimTK::Xml::Node::isValid ( ) const

inline

Return true if this Node handle is referencing some node, false if the Node handle is empty.

bool SimTK::Xml::Node::isTopLevelNode

(

)

const

Return true if this Node is owned by the top-level Xml document, false if the Node is owned by an Element or is an orphan, or if the Node handle is empty.

bool SimTK::Xml::Node::isOrphan

(

)

const

Return true if this Node is an orphan, meaning that it is not empty, but is not owned by any element or top-level document.

This is typically a Node object that has just been constructed, or one that has been cloned from another Node.

bool SimTK::Xml::Node::hasParentElement

(

)

const

Return true if this node has a parent, i.e.

it is owned by an element; the root element and other top-level nodes are owned by the document and thus do not have a parent.

See also

getParentElement()

Element SimTK::Xml::Node::getParentElement

(

)

Return a handle referencing this node's parent if it has one, otherwise throws an error; check first with hasParentElement() if you aren't sure.

const String& SimTK::Xml::Node::getNodeText

(

)

const

Return a text value associated with this Node (not including its child nodes if any); the behavior depends on the NodeType.

This is a convenience that saves downcasting a generic Node to a concrete type when all you want to do is dump out the text. It is not particularly useful for Element nodes. Here is what you get for each type of node:

• Comment: everything between "<!--" and "-->"
• Unknown: everything between "<" and ">"
• Text: the text
• Element: the element's tag word (not the element's value)
• None: (i.e., an empty handle) throw an error.

void SimTK::Xml::Node::writeToString	(	String &	out,
		bool	compact = false
	)		const

Serialize this node (and everything it contains) to the given String.

The output will be "pretty printed" and terminated with a newline unless you specify compact = true in which case indents and newlines will be suppressed. Pretty printing uses the containing Xml::Document's indent string, if this Node is in a document, otherwise the default of four spaces for each indent level is used.

bool SimTK::Xml::Node::operator== ( const Node &  other ) const

inline

Comparing Nodes for equality means asking if the two Node handles are referring to exactly the same object; two different nodes that happen to have the same properties will not test equal by this criteria.

bool SimTK::Xml::Node::operator!= ( const Node &  other ) const

inline

Inequality test using same criteria as operator==().

Friends And Related Function Documentation

friend class Xml

friend

friend class Xml::Impl

friend

friend class Xml::node_iterator

friend

friend class Xml::Comment

friend

friend class Xml::Unknown

friend

friend class Xml::Text

friend

friend class Xml::Element

friend

std::ostream & operator<< ( std::ostream &  o, const Xml::Node &  xmlNode  )

related

Output a "pretty printed" textual representation of the given XML node (and all its contents) to an std::ostream.

Pretty printing uses the indent string from the Node's containing Xml::Document, if this Node is in a document, otherwise the default of four spaces for each indent level is used.

---

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

• Xml.h