\section{Ti\-Xml\-Handle Class Reference}
\label{classTiXmlHandle}\index{Ti\-Xml\-Handle@{Ti\-Xml\-Handle}}


A \doxyref{Ti\-Xml\-Handle}{p.}{classTiXmlHandle} 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{classTiXmlHandle_aba18fd7bdefb942ecdea4bf4b8e29ec8}

\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{classTiXmlHandle_a236d7855e1e56ccc7b980630c48c7fd7}

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

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

\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{classTiXmlHandle_a8c61f64ae9365d89c264f289085541f8}

\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{classTiXmlHandle_a24d1112e995e937e4dddb202d4113d4a}

\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{classTiXmlHandle_af0aea751320f5e430fac6f8fff3b8dd4}

\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{classTiXmlHandle_a8b10982dd39e74f3b068ca8952282d8a}

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

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

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

\item 
{\bf Ti\-Xml\-Node} $\ast$ {\bf To\-Node} () const 
\begin{DoxyCompactList}\small\item\em Return the handle as a \doxyref{Ti\-Xml\-Node}{p.}{classTiXmlNode}. \end{DoxyCompactList}\item 
{\bf Ti\-Xml\-Element} $\ast$ {\bf To\-Element} () const 
\begin{DoxyCompactList}\small\item\em Return the handle as a \doxyref{Ti\-Xml\-Element}{p.}{classTiXmlElement}. \end{DoxyCompactList}\item 
{\bf Ti\-Xml\-Text} $\ast$ {\bf To\-Text} () const 
\begin{DoxyCompactList}\small\item\em Return the handle as a \doxyref{Ti\-Xml\-Text}{p.}{classTiXmlText}. \end{DoxyCompactList}\item 
{\bf Ti\-Xml\-Unknown} $\ast$ {\bf To\-Unknown} () const 
\begin{DoxyCompactList}\small\item\em Return the handle as a \doxyref{Ti\-Xml\-Unknown}{p.}{classTiXmlUnknown}. \end{DoxyCompactList}\item 
{\bf Ti\-Xml\-Node} $\ast$ {\bf Node} () const 
\item 
{\bf Ti\-Xml\-Element} $\ast$ {\bf Element} () const 
\item 
{\bf Ti\-Xml\-Text} $\ast$ {\bf Text} () const 
\item 
{\bf Ti\-Xml\-Unknown} $\ast$ {\bf Unknown} () const 
\end{DoxyCompactItemize}


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

Note that \doxyref{Ti\-Xml\-Handle}{p.}{classTiXmlHandle} 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.}{classTiXmlHandle} addresses the verbosity of such code. A \doxyref{Ti\-Xml\-Handle}{p.}{classTiXmlHandle} 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 ).ToElement();
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 ).ToElement();
        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" ).ToElement();

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

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


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

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

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

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


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

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

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

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


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. 

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

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


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. 

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

\index{Ti\-Xml\-Handle@{Ti\-Xml\-Handle}!Element@{Element}}
\index{Element@{Element}!TiXmlHandle@{Ti\-Xml\-Handle}}
\subsubsection[{Element}]{\setlength{\rightskip}{0pt plus 5cm}{\bf Ti\-Xml\-Element}$\ast$ Ti\-Xml\-Handle\-::\-Element (
\begin{DoxyParamCaption}
{}
\end{DoxyParamCaption}
) const\hspace{0.3cm}{\ttfamily [inline]}}\label{classTiXmlHandle_acb5fe8388a526289ea65e817a51e05e7}
\begin{DoxyRefDesc}{Deprecated}
\item[{\bf Deprecated}]use To\-Element. Return the handle as a \doxyref{Ti\-Xml\-Element}{p.}{classTiXmlElement}. This may return null. \end{DoxyRefDesc}


References To\-Element().

\index{Ti\-Xml\-Handle@{Ti\-Xml\-Handle}!Node@{Node}}
\index{Node@{Node}!TiXmlHandle@{Ti\-Xml\-Handle}}
\subsubsection[{Node}]{\setlength{\rightskip}{0pt plus 5cm}{\bf Ti\-Xml\-Node}$\ast$ Ti\-Xml\-Handle\-::\-Node (
\begin{DoxyParamCaption}
{}
\end{DoxyParamCaption}
) const\hspace{0.3cm}{\ttfamily [inline]}}\label{classTiXmlHandle_ab44b723a8dc9af72838a303c079d0376}
\begin{DoxyRefDesc}{Deprecated}
\item[{\bf Deprecated}]use To\-Node. Return the handle as a \doxyref{Ti\-Xml\-Node}{p.}{classTiXmlNode}. This may return null. \end{DoxyRefDesc}


References To\-Node().

\index{Ti\-Xml\-Handle@{Ti\-Xml\-Handle}!Text@{Text}}
\index{Text@{Text}!TiXmlHandle@{Ti\-Xml\-Handle}}
\subsubsection[{Text}]{\setlength{\rightskip}{0pt plus 5cm}{\bf Ti\-Xml\-Text}$\ast$ Ti\-Xml\-Handle\-::\-Text (
\begin{DoxyParamCaption}
{}
\end{DoxyParamCaption}
) const\hspace{0.3cm}{\ttfamily [inline]}}\label{classTiXmlHandle_a9fc739c8a18d160006f82572fc143d13}
\begin{DoxyRefDesc}{Deprecated}
\item[{\bf Deprecated}]use \doxyref{To\-Text()}{p.}{classTiXmlHandle_a4ac53a652296203a5b5e13854d923586} Return the handle as a \doxyref{Ti\-Xml\-Text}{p.}{classTiXmlText}. This may return null. \end{DoxyRefDesc}


References To\-Text().

\index{Ti\-Xml\-Handle@{Ti\-Xml\-Handle}!To\-Element@{To\-Element}}
\index{To\-Element@{To\-Element}!TiXmlHandle@{Ti\-Xml\-Handle}}
\subsubsection[{To\-Element}]{\setlength{\rightskip}{0pt plus 5cm}{\bf Ti\-Xml\-Element}$\ast$ Ti\-Xml\-Handle\-::\-To\-Element (
\begin{DoxyParamCaption}
{}
\end{DoxyParamCaption}
) const\hspace{0.3cm}{\ttfamily [inline]}}\label{classTiXmlHandle_abc6e7ed383a5fe1e52b0c0004b457b9e}


Return the handle as a \doxyref{Ti\-Xml\-Element}{p.}{classTiXmlElement}. 

This may return null. 

References Ti\-Xml\-Node\-::\-To\-Element().



Referenced by Element().

\index{Ti\-Xml\-Handle@{Ti\-Xml\-Handle}!To\-Node@{To\-Node}}
\index{To\-Node@{To\-Node}!TiXmlHandle@{Ti\-Xml\-Handle}}
\subsubsection[{To\-Node}]{\setlength{\rightskip}{0pt plus 5cm}{\bf Ti\-Xml\-Node}$\ast$ Ti\-Xml\-Handle\-::\-To\-Node (
\begin{DoxyParamCaption}
{}
\end{DoxyParamCaption}
) const\hspace{0.3cm}{\ttfamily [inline]}}\label{classTiXmlHandle_af678e5088e83be67baf76f699756f2c3}


Return the handle as a \doxyref{Ti\-Xml\-Node}{p.}{classTiXmlNode}. 

This may return null. 

Referenced by Node().

\index{Ti\-Xml\-Handle@{Ti\-Xml\-Handle}!To\-Text@{To\-Text}}
\index{To\-Text@{To\-Text}!TiXmlHandle@{Ti\-Xml\-Handle}}
\subsubsection[{To\-Text}]{\setlength{\rightskip}{0pt plus 5cm}{\bf Ti\-Xml\-Text}$\ast$ Ti\-Xml\-Handle\-::\-To\-Text (
\begin{DoxyParamCaption}
{}
\end{DoxyParamCaption}
) const\hspace{0.3cm}{\ttfamily [inline]}}\label{classTiXmlHandle_a4ac53a652296203a5b5e13854d923586}


Return the handle as a \doxyref{Ti\-Xml\-Text}{p.}{classTiXmlText}. 

This may return null. 

References Ti\-Xml\-Node\-::\-To\-Text().



Referenced by Text().

\index{Ti\-Xml\-Handle@{Ti\-Xml\-Handle}!To\-Unknown@{To\-Unknown}}
\index{To\-Unknown@{To\-Unknown}!TiXmlHandle@{Ti\-Xml\-Handle}}
\subsubsection[{To\-Unknown}]{\setlength{\rightskip}{0pt plus 5cm}{\bf Ti\-Xml\-Unknown}$\ast$ Ti\-Xml\-Handle\-::\-To\-Unknown (
\begin{DoxyParamCaption}
{}
\end{DoxyParamCaption}
) const\hspace{0.3cm}{\ttfamily [inline]}}\label{classTiXmlHandle_a1381c17507a130767b1e23afc93b3674}


Return the handle as a \doxyref{Ti\-Xml\-Unknown}{p.}{classTiXmlUnknown}. 

This may return null. 

References Ti\-Xml\-Node\-::\-To\-Unknown().



Referenced by Unknown().

\index{Ti\-Xml\-Handle@{Ti\-Xml\-Handle}!Unknown@{Unknown}}
\index{Unknown@{Unknown}!TiXmlHandle@{Ti\-Xml\-Handle}}
\subsubsection[{Unknown}]{\setlength{\rightskip}{0pt plus 5cm}{\bf Ti\-Xml\-Unknown}$\ast$ Ti\-Xml\-Handle\-::\-Unknown (
\begin{DoxyParamCaption}
{}
\end{DoxyParamCaption}
) const\hspace{0.3cm}{\ttfamily [inline]}}\label{classTiXmlHandle_a49675b74357ba2aae124657a9a1ef465}
\begin{DoxyRefDesc}{Deprecated}
\item[{\bf Deprecated}]use \doxyref{To\-Unknown()}{p.}{classTiXmlHandle_a1381c17507a130767b1e23afc93b3674} Return the handle as a \doxyref{Ti\-Xml\-Unknown}{p.}{classTiXmlUnknown}. This may return null. \end{DoxyRefDesc}


References To\-Unknown().



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