TiXmlHandle Class Reference

Wraps a node pointer. More...

#include <edelib/TiXml.h>

List of all members.

Public Member Functions

 TiXmlHandle (TiXmlNode *_node)
 TiXmlHandle (const TiXmlHandle &ref)
TiXmlHandle operator= (const TiXmlHandle &ref)
TiXmlHandle FirstChild () const
TiXmlHandle FirstChild (const char *value) const
TiXmlHandle FirstChildElement () const
TiXmlHandle FirstChildElement (const char *value) const
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
TiXmlNodeToNode () const
TiXmlElementToElement () const
TiXmlTextToText () const
TiXmlUnknownToUnknown () const
TiXmlNodeNode () const
TiXmlElementElement () const
TiXmlTextText () const
TiXmlUnknownUnknown () const

Detailed Description

Wraps a node pointer.

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
 *   }
 * 

Constructor & Destructor Documentation

TiXmlHandle ( TiXmlNode _node  )  [inline]

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

TiXmlHandle ( const TiXmlHandle ref  )  [inline]

Copy constructor


Member Function Documentation

TiXmlHandle Child ( int  index  )  const

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

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.

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.

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.

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

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

TiXmlHandle FirstChild (  )  const

Return a handle to the first child node.

TiXmlHandle FirstChildElement ( const char *  value  )  const

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

TiXmlHandle FirstChildElement (  )  const

Return a handle to the first child element.

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

Assignement from TiXmlHandle

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

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

TiXmlNode* ToNode (  )  const [inline]

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

TiXmlText* ToText (  )  const [inline]

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

TiXmlUnknown* ToUnknown (  )  const [inline]

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

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

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

Generated on 23 May 2013 for edelib by  doxygen 1.6.1