\section{gear\-:\-:Ti\-Xml\-Handle Class Reference}
\label{classgear_1_1TiXmlHandle}\index{gear\-::\-Ti\-Xml\-Handle@{gear\-::\-Ti\-Xml\-Handle}}


A \doxyref{Ti\-Xml\-Handle}{p.}{classgear_1_1TiXmlHandle} is a class that wraps a node pointer with null checks; this is an incredibly useful thing.  




{\ttfamily \#include $<$tinyxml.\-h$>$}

\subsection*{Public Member Functions}
\begin{DoxyCompactItemize}
\item 
{\bf Ti\-Xml\-Handle} ({\bf Ti\-Xml\-Node} $\ast$node)\label{classgear_1_1TiXmlHandle_aa6bdbe693e1e400b2b94924e402ad988}

\begin{DoxyCompactList}\small\item\em Create a handle from any node (at any depth of the tree.) This can be a null pointer. \end{DoxyCompactList}\item 
{\bf Ti\-Xml\-Handle} (const {\bf Ti\-Xml\-Handle} \&ref)\label{classgear_1_1TiXmlHandle_accad79d5c5a021fbe786586091725040}

\begin{DoxyCompactList}\small\item\em Copy constructor. \end{DoxyCompactList}\item 
{\bf Ti\-Xml\-Handle} {\bfseries operator=} (const {\bf Ti\-Xml\-Handle} \&ref)\label{classgear_1_1TiXmlHandle_ac18fdab37f6b4535b8dbaa72601717ba}

\item 
{\bf Ti\-Xml\-Handle} {\bf First\-Child} () const \label{classgear_1_1TiXmlHandle_ad3cba2cc54583f5b846fa95988cc3eb5}

\begin{DoxyCompactList}\small\item\em Return a handle to the first child node. \end{DoxyCompactList}\item 
{\bf Ti\-Xml\-Handle} {\bf First\-Child} (const char $\ast$value) const \label{classgear_1_1TiXmlHandle_a098c2431e5fada783a19b9b82f5e0257}

\begin{DoxyCompactList}\small\item\em Return a handle to the first child node with the given name. \end{DoxyCompactList}\item 
{\bf Ti\-Xml\-Handle} {\bf First\-Child\-Element} () const \label{classgear_1_1TiXmlHandle_ad07e15b493147a2544f0f306234239b0}

\begin{DoxyCompactList}\small\item\em Return a handle to the first child element. \end{DoxyCompactList}\item 
{\bf Ti\-Xml\-Handle} {\bf First\-Child\-Element} (const char $\ast$value) const \label{classgear_1_1TiXmlHandle_ae29c49ee17dd993da232d4e9644a64f2}

\begin{DoxyCompactList}\small\item\em Return a handle to the first child element with the given name. \end{DoxyCompactList}\item 
{\bf Ti\-Xml\-Handle} {\bf Child} (const char $\ast$value, int index) const 
\begin{DoxyCompactList}\small\item\em Return a handle to the \char`\"{}index\char`\"{} child with the given name. \end{DoxyCompactList}\item 
{\bf Ti\-Xml\-Handle} {\bf Child} (int index) const 
\begin{DoxyCompactList}\small\item\em Return a handle to the \char`\"{}index\char`\"{} child. \end{DoxyCompactList}\item 
{\bf Ti\-Xml\-Handle} {\bf Child\-Element} (const char $\ast$value, int index) const 
\begin{DoxyCompactList}\small\item\em Return a handle to the \char`\"{}index\char`\"{} child element with the given name. \end{DoxyCompactList}\item 
{\bf Ti\-Xml\-Handle} {\bf Child\-Element} (int index) const 
\begin{DoxyCompactList}\small\item\em Return a handle to the \char`\"{}index\char`\"{} child element. \end{DoxyCompactList}\item 
{\bf Ti\-Xml\-Handle} {\bfseries First\-Child} (const std\-::string \&\-\_\-value) const \label{classgear_1_1TiXmlHandle_ade57f348ddf0585a949d25d8dab9d558}

\item 
{\bf Ti\-Xml\-Handle} {\bfseries First\-Child\-Element} (const std\-::string \&\-\_\-value) const \label{classgear_1_1TiXmlHandle_adf14461c60a3d52b7f9b20f61317a5e7}

\item 
{\bf Ti\-Xml\-Handle} {\bfseries Child} (const std\-::string \&\-\_\-value, int index) const \label{classgear_1_1TiXmlHandle_a8b694148de79100f17248e0ab6d1dea7}

\item 
{\bf Ti\-Xml\-Handle} {\bfseries Child\-Element} (const std\-::string \&\-\_\-value, int index) const \label{classgear_1_1TiXmlHandle_a53469f0418a34068d6807a7f31ae396a}

\item 
{\bf Ti\-Xml\-Node} $\ast$ {\bf Node} () const \label{classgear_1_1TiXmlHandle_a36df43d9eb13a9727fd3be417ed16725}

\begin{DoxyCompactList}\small\item\em Return the handle as a \doxyref{Ti\-Xml\-Node}{p.}{classgear_1_1TiXmlNode}. This may return null. \end{DoxyCompactList}\item 
{\bf Ti\-Xml\-Element} $\ast$ {\bf Element} () const \label{classgear_1_1TiXmlHandle_af7f6db639235ac5337ede47719bd1b96}

\begin{DoxyCompactList}\small\item\em Return the handle as a \doxyref{Ti\-Xml\-Element}{p.}{classgear_1_1TiXmlElement}. This may return null. \end{DoxyCompactList}\item 
{\bf Ti\-Xml\-Text} $\ast$ {\bf Text} () const \label{classgear_1_1TiXmlHandle_a5a6096e9fc5d1735a2d3af9e667880b5}

\begin{DoxyCompactList}\small\item\em Return the handle as a \doxyref{Ti\-Xml\-Text}{p.}{classgear_1_1TiXmlText}. This may return null. \end{DoxyCompactList}\item 
{\bf Ti\-Xml\-Unknown} $\ast$ {\bf Unknown} () const \label{classgear_1_1TiXmlHandle_ab5f2d7674bf320e1770fb76c9d8a044a}

\begin{DoxyCompactList}\small\item\em Return the handle as a \doxyref{Ti\-Xml\-Unknown}{p.}{classgear_1_1TiXmlUnknown}. This may return null;. \end{DoxyCompactList}\end{DoxyCompactItemize}


\subsection{Detailed Description}
A \doxyref{Ti\-Xml\-Handle}{p.}{classgear_1_1TiXmlHandle} is a class that wraps a node pointer with null checks; this is an incredibly useful thing. 

Note that \doxyref{Ti\-Xml\-Handle}{p.}{classgear_1_1TiXmlHandle} is not part of the Tiny\-Xml D\-O\-M structure. It is a separate utility class.

Take an example\-: \begin{DoxyVerb}<Document>
        <Element attributeA = "valueA">
                <Child attributeB = "value1" />
                <Child attributeB = "value2" />
        </Element>
<Document>
\end{DoxyVerb}


Assuming you want the value of \char`\"{}attribute\-B\char`\"{} in the 2nd \char`\"{}\-Child\char`\"{} element, it's very easy to write a {\itshape lot} of code that looks like\-:

\begin{DoxyVerb}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.
\end{DoxyVerb}


And that doesn't even cover \char`\"{}else\char`\"{} cases. \doxyref{Ti\-Xml\-Handle}{p.}{classgear_1_1TiXmlHandle} addresses the verbosity of such code. A \doxyref{Ti\-Xml\-Handle}{p.}{classgear_1_1TiXmlHandle} checks for null pointers so it is perfectly safe and correct to use\-:

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


Which is M\-U\-C\-H more concise and useful.

It is also safe to copy handles -\/ internally they are nothing more than node pointers. \begin{DoxyVerb}TiXmlHandle handleCopy = handle;
\end{DoxyVerb}


What they should not be used for is iteration\-:

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


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\-:

\begin{DoxyVerb}TiXmlElement* child = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).FirstChild( "Child" ).Element();

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

Definition at line 1374 of file tinyxml.\-h.



\subsection{Member Function Documentation}
\index{gear\-::\-Ti\-Xml\-Handle@{gear\-::\-Ti\-Xml\-Handle}!Child@{Child}}
\index{Child@{Child}!gear::TiXmlHandle@{gear\-::\-Ti\-Xml\-Handle}}
\subsubsection[{Child}]{\setlength{\rightskip}{0pt plus 5cm}{\bf Ti\-Xml\-Handle} gear\-::\-Ti\-Xml\-Handle\-::\-Child (
\begin{DoxyParamCaption}
\item[{const char $\ast$}]{value, }
\item[{int}]{index}
\end{DoxyParamCaption}
) const}\label{classgear_1_1TiXmlHandle_a7f03f30e683cddee52fc9672429814ed}


Return a handle to the \char`\"{}index\char`\"{} child with the given name. 

The first child is 0, the second 1, etc. 

Definition at line 1554 of file tinyxml.\-cc.



References gear\-::\-Ti\-Xml\-Node\-::\-First\-Child(), gear\-::\-Ti\-Xml\-Node\-::\-Next\-Sibling(), and Ti\-Xml\-Handle().

\index{gear\-::\-Ti\-Xml\-Handle@{gear\-::\-Ti\-Xml\-Handle}!Child@{Child}}
\index{Child@{Child}!gear::TiXmlHandle@{gear\-::\-Ti\-Xml\-Handle}}
\subsubsection[{Child}]{\setlength{\rightskip}{0pt plus 5cm}{\bf Ti\-Xml\-Handle} gear\-::\-Ti\-Xml\-Handle\-::\-Child (
\begin{DoxyParamCaption}
\item[{int}]{index}
\end{DoxyParamCaption}
) const}\label{classgear_1_1TiXmlHandle_a776a66b4443308465636f4caa342929d}


Return a handle to the \char`\"{}index\char`\"{} child. 

The first child is 0, the second 1, etc. 

Definition at line 1535 of file tinyxml.\-cc.



References gear\-::\-Ti\-Xml\-Node\-::\-First\-Child(), gear\-::\-Ti\-Xml\-Node\-::\-Next\-Sibling(), and Ti\-Xml\-Handle().

\index{gear\-::\-Ti\-Xml\-Handle@{gear\-::\-Ti\-Xml\-Handle}!Child\-Element@{Child\-Element}}
\index{Child\-Element@{Child\-Element}!gear::TiXmlHandle@{gear\-::\-Ti\-Xml\-Handle}}
\subsubsection[{Child\-Element}]{\setlength{\rightskip}{0pt plus 5cm}{\bf Ti\-Xml\-Handle} gear\-::\-Ti\-Xml\-Handle\-::\-Child\-Element (
\begin{DoxyParamCaption}
\item[{const char $\ast$}]{value, }
\item[{int}]{index}
\end{DoxyParamCaption}
) const}\label{classgear_1_1TiXmlHandle_ad05282da3449cff566ec8434493c5a2c}


Return a handle to the \char`\"{}index\char`\"{} child element with the given name. 

The first child element is 0, the second 1, etc. Note that only Ti\-Xml\-Elements are indexed\-: other types are not counted. 

Definition at line 1592 of file tinyxml.\-cc.



References gear\-::\-Ti\-Xml\-Node\-::\-First\-Child\-Element(), gear\-::\-Ti\-Xml\-Node\-::\-Next\-Sibling\-Element(), and Ti\-Xml\-Handle().

\index{gear\-::\-Ti\-Xml\-Handle@{gear\-::\-Ti\-Xml\-Handle}!Child\-Element@{Child\-Element}}
\index{Child\-Element@{Child\-Element}!gear::TiXmlHandle@{gear\-::\-Ti\-Xml\-Handle}}
\subsubsection[{Child\-Element}]{\setlength{\rightskip}{0pt plus 5cm}{\bf Ti\-Xml\-Handle} gear\-::\-Ti\-Xml\-Handle\-::\-Child\-Element (
\begin{DoxyParamCaption}
\item[{int}]{index}
\end{DoxyParamCaption}
) const}\label{classgear_1_1TiXmlHandle_ab95393f64e4c63e95dfd4cba2fba4c8b}


Return a handle to the \char`\"{}index\char`\"{} child element. 

The first child element is 0, the second 1, etc. Note that only Ti\-Xml\-Elements are indexed\-: other types are not counted. 

Definition at line 1573 of file tinyxml.\-cc.



References gear\-::\-Ti\-Xml\-Node\-::\-First\-Child\-Element(), gear\-::\-Ti\-Xml\-Node\-::\-Next\-Sibling\-Element(), and Ti\-Xml\-Handle().



The documentation for this class was generated from the following files\-:\begin{DoxyCompactItemize}
\item 
tinyxml.\-h\item 
tinyxml.\-cc\end{DoxyCompactItemize}
