TiXmlHandle Class Reference

#include <tinyxml.h>

List of all members.

Public Member Functions

 TiXmlHandle (TiXmlNode *_node)
 Create a handle from any node (at any depth of the tree.) This can be a null pointer.
 TiXmlHandle (const TiXmlHandle &ref)
 Copy constructor.
TiXmlHandle operator= (const TiXmlHandle &ref)
TiXmlHandle FirstChild () const
 Return a handle to the first child node.
TiXmlHandle FirstChild (const char *value) const
 Return a handle to the first child node with the given name.
TiXmlHandle FirstChildElement () const
 Return a handle to the first child element.
TiXmlHandle FirstChildElement (const char *value) const
 Return a handle to the first child element with the given name.
TiXmlHandle Child (const char *value, int index) const
TiXmlHandle Child (int index) const
TiXmlHandle ChildElement (const char *value, int index) const
TiXmlHandle ChildElement (int index) const
TiXmlHandle FirstChild (const std::string &_value) const
TiXmlHandle FirstChildElement (const std::string &_value) const
TiXmlHandle Child (const std::string &_value, int index) const
TiXmlHandle ChildElement (const std::string &_value, int index) const
TiXmlNodeToNode () const
TiXmlElementToElement () const
TiXmlTextToText () const
TiXmlUnknownToUnknown () const
TiXmlNodeNode () const
TiXmlElementElement () const
TiXmlTextText () const
TiXmlUnknownUnknown () const

Private Attributes

TiXmlNodenode

Detailed Description

A TiXmlHandle is a class that wraps a node pointer with null checks; this is an incredibly useful thing. Note that TiXmlHandle is not part of the TinyXml DOM structure. It is a separate utility class.

Take an example:

	<Document>
		<Element attributeA = "valueA">
			<Child attributeB = "value1" />
			<Child attributeB = "value2" />
		</Element>
	<Document>
	

Assuming you want the value of "attributeB" in the 2nd "Child" element, it's very easy to write a *lot* of code that looks like:

	TiXmlElement* root = document.FirstChildElement( "Document" );
	if ( root )
	{
		TiXmlElement* element = root->FirstChildElement( "Element" );
		if ( element )
		{
			TiXmlElement* child = element->FirstChildElement( "Child" );
			if ( child )
			{
				TiXmlElement* child2 = child->NextSiblingElement( "Child" );
				if ( child2 )
				{
					// Finally do something useful.
	

And that doesn't even cover "else" cases. TiXmlHandle addresses the verbosity of such code. A TiXmlHandle checks for null pointers so it is perfectly safe and correct to use:

	TiXmlHandle docHandle( &document );
	TiXmlElement* child2 = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", 1 ).ToElement();
	if ( child2 )
	{
		// do something useful
	

Which is MUCH more concise and useful.

It is also safe to copy handles - internally they are nothing more than node pointers.

	TiXmlHandle handleCopy = handle;
	

What they should not be used for is iteration:

	int i=0; 
	while ( true )
	{
		TiXmlElement* child = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", i ).ToElement();
		if ( !child )
			break;
		// do something
		++i;
	}
	

It seems reasonable, but it is in fact two embedded while loops. The Child method is a linear walk to find the element, so this code would iterate much more than it needs to. Instead, prefer:

	TiXmlElement* child = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).FirstChild( "Child" ).ToElement();

	for( child; child; child=child->NextSiblingElement() )
	{
		// do something
	}
	

Definition at line 1613 of file tinyxml.h.


Constructor & Destructor Documentation

TiXmlHandle::TiXmlHandle ( TiXmlNode _node  )  [inline]

Create a handle from any node (at any depth of the tree.) This can be a null pointer.

Definition at line 1617 of file tinyxml.h.

References node.

Referenced by Child(), ChildElement(), FirstChild(), and FirstChildElement().

01617 { this->node = _node; }

TiXmlHandle::TiXmlHandle ( const TiXmlHandle ref  )  [inline]

Copy constructor.

Definition at line 1619 of file tinyxml.h.

References node.

01619 { this->node = ref.node; }


Member Function Documentation

TiXmlHandle TiXmlHandle::Child ( const std::string &  _value,
int  index 
) const [inline]

Definition at line 1654 of file tinyxml.h.

References Child().

Referenced by Child().

01654 { return Child( _value.c_str(), index ); }

TiXmlHandle TiXmlHandle::Child ( int  index  )  const

Return a handle to the "index" child. The first child is 0, the second 1, etc.

Definition at line 1664 of file tinyxml.cpp.

References TiXmlNode::NextSibling(), and TiXmlHandle().

01665 {
01666         if ( node )
01667         {
01668                 int i;
01669                 TiXmlNode* child = node->FirstChild();
01670                 for (   i=0;
01671                                 child && i<count;
01672                                 child = child->NextSibling(), ++i )
01673                 {
01674                         // nothing
01675                 }
01676                 if ( child )
01677                         return TiXmlHandle( child );
01678         }
01679         return TiXmlHandle( 0 );
01680 }

TiXmlHandle TiXmlHandle::Child ( const char *  value,
int  index 
) const

Return a handle to the "index" child with the given name. The first child is 0, the second 1, etc.

Definition at line 1683 of file tinyxml.cpp.

References TiXmlNode::NextSibling(), and TiXmlHandle().

01684 {
01685         if ( node )
01686         {
01687                 int i;
01688                 TiXmlNode* child = node->FirstChild( value );
01689                 for (   i=0;
01690                                 child && i<count;
01691                                 child = child->NextSibling( value ), ++i )
01692                 {
01693                         // nothing
01694                 }
01695                 if ( child )
01696                         return TiXmlHandle( child );
01697         }
01698         return TiXmlHandle( 0 );
01699 }

TiXmlHandle TiXmlHandle::ChildElement ( const std::string &  _value,
int  index 
) const [inline]

Definition at line 1655 of file tinyxml.h.

References ChildElement().

Referenced by ChildElement().

01655 { return ChildElement( _value.c_str(), index ); }

TiXmlHandle TiXmlHandle::ChildElement ( int  index  )  const

Return a handle to the "index" child element. The first child element is 0, the second 1, etc. Note that only TiXmlElements are indexed: other types are not counted.

Definition at line 1702 of file tinyxml.cpp.

References TiXmlNode::NextSiblingElement(), and TiXmlHandle().

01703 {
01704         if ( node )
01705         {
01706                 int i;
01707                 TiXmlElement* child = node->FirstChildElement();
01708                 for (   i=0;
01709                                 child && i<count;
01710                                 child = child->NextSiblingElement(), ++i )
01711                 {
01712                         // nothing
01713                 }
01714                 if ( child )
01715                         return TiXmlHandle( child );
01716         }
01717         return TiXmlHandle( 0 );
01718 }

TiXmlHandle TiXmlHandle::ChildElement ( const char *  value,
int  index 
) const

Return a handle to the "index" child element with the given name. The first child element is 0, the second 1, etc. Note that only TiXmlElements are indexed: other types are not counted.

Definition at line 1721 of file tinyxml.cpp.

References TiXmlNode::NextSiblingElement(), and TiXmlHandle().

01722 {
01723         if ( node )
01724         {
01725                 int i;
01726                 TiXmlElement* child = node->FirstChildElement( value );
01727                 for (   i=0;
01728                                 child && i<count;
01729                                 child = child->NextSiblingElement( value ), ++i )
01730                 {
01731                         // nothing
01732                 }
01733                 if ( child )
01734                         return TiXmlHandle( child );
01735         }
01736         return TiXmlHandle( 0 );
01737 }

TiXmlElement* TiXmlHandle::Element (  )  const [inline]
Deprecated:
use ToElement. Return the handle as a TiXmlElement. This may return null.

Definition at line 1678 of file tinyxml.h.

References ToElement().

01678 { return ToElement(); }

TiXmlHandle TiXmlHandle::FirstChild ( const std::string &  _value  )  const [inline]

Definition at line 1651 of file tinyxml.h.

References FirstChild().

Referenced by FirstChild().

01651 { return FirstChild( _value.c_str() ); }

TiXmlHandle TiXmlHandle::FirstChild ( const char *  value  )  const

Return a handle to the first child node with the given name.

Definition at line 1628 of file tinyxml.cpp.

References TiXmlHandle().

01629 {
01630         if ( node )
01631         {
01632                 TiXmlNode* child = node->FirstChild( value );
01633                 if ( child )
01634                         return TiXmlHandle( child );
01635         }
01636         return TiXmlHandle( 0 );
01637 }

TiXmlHandle TiXmlHandle::FirstChild (  )  const

Return a handle to the first child node.

Definition at line 1616 of file tinyxml.cpp.

References TiXmlHandle().

01617 {
01618         if ( node )
01619         {
01620                 TiXmlNode* child = node->FirstChild();
01621                 if ( child )
01622                         return TiXmlHandle( child );
01623         }
01624         return TiXmlHandle( 0 );
01625 }

TiXmlHandle TiXmlHandle::FirstChildElement ( const std::string &  _value  )  const [inline]

Definition at line 1652 of file tinyxml.h.

References FirstChildElement().

Referenced by FirstChildElement().

01652 { return FirstChildElement( _value.c_str() ); }

TiXmlHandle TiXmlHandle::FirstChildElement ( const char *  value  )  const

Return a handle to the first child element with the given name.

Definition at line 1652 of file tinyxml.cpp.

References TiXmlHandle().

01653 {
01654         if ( node )
01655         {
01656                 TiXmlElement* child = node->FirstChildElement( value );
01657                 if ( child )
01658                         return TiXmlHandle( child );
01659         }
01660         return TiXmlHandle( 0 );
01661 }

TiXmlHandle TiXmlHandle::FirstChildElement (  )  const

Return a handle to the first child element.

Definition at line 1640 of file tinyxml.cpp.

References TiXmlHandle().

01641 {
01642         if ( node )
01643         {
01644                 TiXmlElement* child = node->FirstChildElement();
01645                 if ( child )
01646                         return TiXmlHandle( child );
01647         }
01648         return TiXmlHandle( 0 );
01649 }

TiXmlNode* TiXmlHandle::Node (  )  const [inline]
Deprecated:
use ToNode. Return the handle as a TiXmlNode. This may return null.

Definition at line 1674 of file tinyxml.h.

References ToNode().

01674 { return ToNode(); } 

TiXmlHandle TiXmlHandle::operator= ( const TiXmlHandle ref  )  [inline]

Definition at line 1620 of file tinyxml.h.

References node.

01620 { this->node = ref.node; return *this; }

TiXmlText* TiXmlHandle::Text (  )  const [inline]
Deprecated:
use ToText() Return the handle as a TiXmlText. This may return null.

Definition at line 1682 of file tinyxml.h.

References ToText().

01682 { return ToText(); }

TiXmlElement* TiXmlHandle::ToElement (  )  const [inline]

Return the handle as a TiXmlElement. This may return null.

Definition at line 1663 of file tinyxml.h.

References node, and TiXmlNode::ToElement().

Referenced by Element().

01663 { return ( ( node && node->ToElement() ) ? node->ToElement() : 0 ); }

TiXmlNode* TiXmlHandle::ToNode (  )  const [inline]

Return the handle as a TiXmlNode. This may return null.

Definition at line 1660 of file tinyxml.h.

References node.

Referenced by Node().

01660 { return node; } 

TiXmlText* TiXmlHandle::ToText (  )  const [inline]

Return the handle as a TiXmlText. This may return null.

Definition at line 1666 of file tinyxml.h.

References node, and TiXmlNode::ToText().

Referenced by Text().

01666 { return ( ( node && node->ToText() ) ? node->ToText() : 0 ); }

TiXmlUnknown* TiXmlHandle::ToUnknown (  )  const [inline]

Return the handle as a TiXmlUnknown. This may return null.

Definition at line 1669 of file tinyxml.h.

References node, and TiXmlNode::ToUnknown().

Referenced by Unknown().

01669 { return ( ( node && node->ToUnknown() ) ? node->ToUnknown() : 0 ); }

TiXmlUnknown* TiXmlHandle::Unknown (  )  const [inline]
Deprecated:
use ToUnknown() Return the handle as a TiXmlUnknown. This may return null.

Definition at line 1686 of file tinyxml.h.

References ToUnknown().

01686 { return ToUnknown(); }


Member Data Documentation

Definition at line 1689 of file tinyxml.h.

Referenced by operator=(), TiXmlHandle(), ToElement(), ToNode(), ToText(), and ToUnknown().


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

Generated on 11 Jan 2018 for loon by  doxygen 1.6.1