Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
TiXmlHandle Class Reference
A TiXmlHandle is a class that wraps a node pointer with null checks; this is an incredibly useful thing. More...
#include <tinyxml.h>
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 | 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 |
| Return a handle to the "index" child with the given name. | |
| TiXmlHandle | Child (int index) const |
| Return a handle to the "index" child. | |
| TiXmlHandle | ChildElement (const char *value, int index) const |
| Return a handle to the "index" child element with the given name. | |
| TiXmlHandle | ChildElement (int index) const |
| Return a handle to the "index" child element. | |
| TiXmlNode * | ToNode () const |
| Return the handle as a TiXmlNode. | |
| TiXmlElement * | ToElement () const |
| Return the handle as a TiXmlElement. | |
| TiXmlText * | ToText () const |
| Return the handle as a TiXmlText. | |
| TiXmlUnknown * | ToUnknown () const |
| Return the handle as a TiXmlUnknown. | |
| TiXmlNode * | Node () const |
| TiXmlElement * | Element () const |
| TiXmlText * | Text () const |
| TiXmlUnknown * | Unknown () const |
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 1633 of file tinyxml.h.
Constructor & Destructor Documentation
| TiXmlHandle | ( | TiXmlNode * | _node ) |
| TiXmlHandle | ( | const TiXmlHandle & | ref ) |
Member Function Documentation
| 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 1651 of file tinyxml.cpp.
| TiXmlHandle Child | ( | int | index ) | const |
Return a handle to the "index" child.
The first child is 0, the second 1, etc.
Definition at line 1632 of file tinyxml.cpp.
| 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 1689 of file tinyxml.cpp.
| 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 1670 of file tinyxml.cpp.
| TiXmlElement* Element | ( | ) | const |
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.
Definition at line 1596 of file tinyxml.cpp.
| TiXmlHandle FirstChild | ( | ) | const |
Return a handle to the first child node.
Definition at line 1584 of file tinyxml.cpp.
| TiXmlHandle FirstChildElement | ( | ) | const |
Return a handle to the first child element.
Definition at line 1608 of file tinyxml.cpp.
| TiXmlHandle FirstChildElement | ( | const char * | value ) | const |
Return a handle to the first child element with the given name.
Definition at line 1620 of file tinyxml.cpp.
| TiXmlNode* Node | ( | ) | const |
| TiXmlElement* ToElement | ( | ) | const |
Return the handle as a TiXmlElement.
This may return null.
| TiXmlNode* ToNode | ( | ) | const |
| TiXmlText* ToText | ( | ) | const |
| TiXmlUnknown* ToUnknown | ( | ) | const |
Return the handle as a TiXmlUnknown.
This may return null.
| TiXmlUnknown* Unknown | ( | ) | const |
Generated on Tue Jul 12 2022 20:43:31 by
1.7.2