1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2 <html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"> 3 <title>TinyXml: TiXmlHandle Class Reference</title> 4 <link href="doxygen.css" rel="stylesheet" type="text/css"> 5 </head><body> 6 <!-- Generated by Doxygen 1.4.4 --> 7 <div class="qindex"><a class="qindex" href="index.html">Main Page</a> | <a class="qindex" href="hierarchy.html">Class Hierarchy</a> | <a class="qindex" href="annotated.html">Class List</a> | <a class="qindex" href="files.html">File List</a> | <a class="qindex" href="functions.html">Class Members</a></div> 8 <h1>TiXmlHandle Class Reference</h1><!-- doxytag: class="TiXmlHandle" -->A TiXmlHandle is a class that wraps a node pointer with null checks; this is an incredibly useful thing. 9 <a href="#_details">More...</a> 10 <p> 11 <code>#include <<a class="el" href="tinyxml_8h-source.html">tinyxml.h</a>></code> 12 <p> 13 <a href="classTiXmlHandle-members.html">List of all members.</a><table border="0" cellpadding="0" cellspacing="0"> 14 <tr><td></td></tr> 15 <tr><td colspan="2"><br><h2>Public Member Functions</h2></td></tr> 16 <tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="a0"></a><!-- doxytag: member="TiXmlHandle::TiXmlHandle" ref="a0" args="(TiXmlNode *_node)" --> 17 </td><td class="memItemRight" valign="bottom"><a class="el" href="classTiXmlHandle.html#a0">TiXmlHandle</a> (<a class="el" href="classTiXmlNode.html">TiXmlNode</a> *_node)</td></tr> 18 19 <tr><td class="mdescLeft"> </td><td class="mdescRight">Create a handle from any node (at any depth of the tree.) This can be a null pointer. <br></td></tr> 20 <tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="a1"></a><!-- doxytag: member="TiXmlHandle::TiXmlHandle" ref="a1" args="(const TiXmlHandle &ref)" --> 21 </td><td class="memItemRight" valign="bottom"><a class="el" href="classTiXmlHandle.html#a1">TiXmlHandle</a> (const <a class="el" href="classTiXmlHandle.html">TiXmlHandle</a> &ref)</td></tr> 22 23 <tr><td class="mdescLeft"> </td><td class="mdescRight">Copy constructor. <br></td></tr> 24 <tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="a3"></a><!-- doxytag: member="TiXmlHandle::FirstChild" ref="a3" args="() const " --> 25 <a class="el" href="classTiXmlHandle.html">TiXmlHandle</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="classTiXmlHandle.html#a3">FirstChild</a> () const </td></tr> 26 27 <tr><td class="mdescLeft"> </td><td class="mdescRight">Return a handle to the first child node. <br></td></tr> 28 <tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="a4"></a><!-- doxytag: member="TiXmlHandle::FirstChild" ref="a4" args="(const char *value) const " --> 29 <a class="el" href="classTiXmlHandle.html">TiXmlHandle</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="classTiXmlHandle.html#a4">FirstChild</a> (const char *value) const </td></tr> 30 31 <tr><td class="mdescLeft"> </td><td class="mdescRight">Return a handle to the first child node with the given name. <br></td></tr> 32 <tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="a5"></a><!-- doxytag: member="TiXmlHandle::FirstChildElement" ref="a5" args="() const " --> 33 <a class="el" href="classTiXmlHandle.html">TiXmlHandle</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="classTiXmlHandle.html#a5">FirstChildElement</a> () const </td></tr> 34 35 <tr><td class="mdescLeft"> </td><td class="mdescRight">Return a handle to the first child element. <br></td></tr> 36 <tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="a6"></a><!-- doxytag: member="TiXmlHandle::FirstChildElement" ref="a6" args="(const char *value) const " --> 37 <a class="el" href="classTiXmlHandle.html">TiXmlHandle</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="classTiXmlHandle.html#a6">FirstChildElement</a> (const char *value) const </td></tr> 38 39 <tr><td class="mdescLeft"> </td><td class="mdescRight">Return a handle to the first child element with the given name. <br></td></tr> 40 <tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="el" href="classTiXmlHandle.html">TiXmlHandle</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="classTiXmlHandle.html#a7">Child</a> (const char *value, int index) const </td></tr> 41 42 <tr><td class="mdescLeft"> </td><td class="mdescRight">Return a handle to the "index" child with the given name. <a href="#a7"></a><br></td></tr> 43 <tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="el" href="classTiXmlHandle.html">TiXmlHandle</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="classTiXmlHandle.html#a8">Child</a> (int index) const </td></tr> 44 45 <tr><td class="mdescLeft"> </td><td class="mdescRight">Return a handle to the "index" child. <a href="#a8"></a><br></td></tr> 46 <tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="el" href="classTiXmlHandle.html">TiXmlHandle</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="classTiXmlHandle.html#a9">ChildElement</a> (const char *value, int index) const </td></tr> 47 48 <tr><td class="mdescLeft"> </td><td class="mdescRight">Return a handle to the "index" child element with the given name. <a href="#a9"></a><br></td></tr> 49 <tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="el" href="classTiXmlHandle.html">TiXmlHandle</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="classTiXmlHandle.html#a10">ChildElement</a> (int index) const </td></tr> 50 51 <tr><td class="mdescLeft"> </td><td class="mdescRight">Return a handle to the "index" child element. <a href="#a10"></a><br></td></tr> 52 <tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="a15"></a><!-- doxytag: member="TiXmlHandle::Node" ref="a15" args="() const " --> 53 <a class="el" href="classTiXmlNode.html">TiXmlNode</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="classTiXmlHandle.html#a15">Node</a> () const </td></tr> 54 55 <tr><td class="mdescLeft"> </td><td class="mdescRight">Return the handle as a <a class="el" href="classTiXmlNode.html">TiXmlNode</a>. This may return null. <br></td></tr> 56 <tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="a16"></a><!-- doxytag: member="TiXmlHandle::Element" ref="a16" args="() const " --> 57 <a class="el" href="classTiXmlElement.html">TiXmlElement</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="classTiXmlHandle.html#a16">Element</a> () const </td></tr> 58 59 <tr><td class="mdescLeft"> </td><td class="mdescRight">Return the handle as a <a class="el" href="classTiXmlElement.html">TiXmlElement</a>. This may return null. <br></td></tr> 60 <tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="a17"></a><!-- doxytag: member="TiXmlHandle::Text" ref="a17" args="() const " --> 61 <a class="el" href="classTiXmlText.html">TiXmlText</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="classTiXmlHandle.html#a17">Text</a> () const </td></tr> 62 63 <tr><td class="mdescLeft"> </td><td class="mdescRight">Return the handle as a <a class="el" href="classTiXmlText.html">TiXmlText</a>. This may return null. <br></td></tr> 64 <tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="a18"></a><!-- doxytag: member="TiXmlHandle::Unknown" ref="a18" args="() const " --> 65 <a class="el" href="classTiXmlUnknown.html">TiXmlUnknown</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="classTiXmlHandle.html#a18">Unknown</a> () const </td></tr> 66 67 <tr><td class="mdescLeft"> </td><td class="mdescRight">Return the handle as a <a class="el" href="classTiXmlUnknown.html">TiXmlUnknown</a>. This may return null;. <br></td></tr> 68 </table> 69 <hr><a name="_details"></a><h2>Detailed Description</h2> 70 A TiXmlHandle is a class that wraps a node pointer with null checks; this is an incredibly useful thing. 71 <p> 72 Note that TiXmlHandle is not part of the TinyXml DOM structure. It is a separate utility class.<p> 73 Take an example: <div class="fragment"><pre class="fragment"> <Document> 74 <Element attributeA = "valueA"> 75 <Child attributeB = "value1" /> 76 <Child attributeB = "value2" /> 77 </Element> 78 <Document> 79 </pre></div><p> 80 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:<p> 81 <div class="fragment"><pre class="fragment"> TiXmlElement* root = document.FirstChildElement( "Document" ); 82 if ( root ) 83 { 84 TiXmlElement* element = root->FirstChildElement( "Element" ); 85 if ( element ) 86 { 87 TiXmlElement* child = element->FirstChildElement( "Child" ); 88 if ( child ) 89 { 90 TiXmlElement* child2 = child->NextSiblingElement( "Child" ); 91 if ( child2 ) 92 { 93 // Finally do something useful. 94 </pre></div><p> 95 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:<p> 96 <div class="fragment"><pre class="fragment"> TiXmlHandle docHandle( &document ); 97 TiXmlElement* child2 = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", 1 ).Element(); 98 if ( child2 ) 99 { 100 // do something useful 101 </pre></div><p> 102 Which is MUCH more concise and useful.<p> 103 It is also safe to copy handles - internally they are nothing more than node pointers. <div class="fragment"><pre class="fragment"> TiXmlHandle handleCopy = handle; 104 </pre></div><p> 105 What they should not be used for is iteration:<p> 106 <div class="fragment"><pre class="fragment"> int i=0; 107 while ( true ) 108 { 109 TiXmlElement* child = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", i ).Element(); 110 if ( !child ) 111 break; 112 // do something 113 ++i; 114 } 115 </pre></div><p> 116 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:<p> 117 <div class="fragment"><pre class="fragment"> TiXmlElement* child = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).FirstChild( "Child" ).Element(); 118 119 for( child; child; child=child->NextSiblingElement() ) 120 { 121 // do something 122 } 123 </pre></div> 124 <p> 125 <hr><h2>Member Function Documentation</h2> 126 <a class="anchor" name="a8"></a><!-- doxytag: member="TiXmlHandle::Child" ref="a8" args="(int index) const " --><p> 127 <table class="mdTable" cellpadding="2" cellspacing="0"> 128 <tr> 129 <td class="mdRow"> 130 <table cellpadding="0" cellspacing="0" border="0"> 131 <tr> 132 <td class="md" nowrap valign="top"><a class="el" href="classTiXmlHandle.html">TiXmlHandle</a> TiXmlHandle::Child </td> 133 <td class="md" valign="top">( </td> 134 <td class="md" nowrap valign="top">int </td> 135 <td class="mdname1" valign="top" nowrap> <em>index</em> </td> 136 <td class="md" valign="top"> ) </td> 137 <td class="md" nowrap> const</td> 138 </tr> 139 </table> 140 </td> 141 </tr> 142 </table> 143 <table cellspacing="5" cellpadding="0" border="0"> 144 <tr> 145 <td> 146 147 </td> 148 <td> 149 150 <p> 151 Return a handle to the "index" child. 152 <p> 153 The first child is 0, the second 1, etc. </td> 154 </tr> 155 </table> 156 <a class="anchor" name="a7"></a><!-- doxytag: member="TiXmlHandle::Child" ref="a7" args="(const char *value, int index) const " --><p> 157 <table class="mdTable" cellpadding="2" cellspacing="0"> 158 <tr> 159 <td class="mdRow"> 160 <table cellpadding="0" cellspacing="0" border="0"> 161 <tr> 162 <td class="md" nowrap valign="top"><a class="el" href="classTiXmlHandle.html">TiXmlHandle</a> TiXmlHandle::Child </td> 163 <td class="md" valign="top">( </td> 164 <td class="md" nowrap valign="top">const char * </td> 165 <td class="mdname" nowrap> <em>value</em>, </td> 166 </tr> 167 <tr> 168 <td class="md" nowrap align="right"></td> 169 <td class="md"></td> 170 <td class="md" nowrap>int </td> 171 <td class="mdname" nowrap> <em>index</em></td> 172 </tr> 173 <tr> 174 <td class="md"></td> 175 <td class="md">) </td> 176 <td class="md" colspan="2"> const</td> 177 </tr> 178 </table> 179 </td> 180 </tr> 181 </table> 182 <table cellspacing="5" cellpadding="0" border="0"> 183 <tr> 184 <td> 185 186 </td> 187 <td> 188 189 <p> 190 Return a handle to the "index" child with the given name. 191 <p> 192 The first child is 0, the second 1, etc. </td> 193 </tr> 194 </table> 195 <a class="anchor" name="a10"></a><!-- doxytag: member="TiXmlHandle::ChildElement" ref="a10" args="(int index) const " --><p> 196 <table class="mdTable" cellpadding="2" cellspacing="0"> 197 <tr> 198 <td class="mdRow"> 199 <table cellpadding="0" cellspacing="0" border="0"> 200 <tr> 201 <td class="md" nowrap valign="top"><a class="el" href="classTiXmlHandle.html">TiXmlHandle</a> TiXmlHandle::ChildElement </td> 202 <td class="md" valign="top">( </td> 203 <td class="md" nowrap valign="top">int </td> 204 <td class="mdname1" valign="top" nowrap> <em>index</em> </td> 205 <td class="md" valign="top"> ) </td> 206 <td class="md" nowrap> const</td> 207 </tr> 208 </table> 209 </td> 210 </tr> 211 </table> 212 <table cellspacing="5" cellpadding="0" border="0"> 213 <tr> 214 <td> 215 216 </td> 217 <td> 218 219 <p> 220 Return a handle to the "index" child element. 221 <p> 222 The first child element is 0, the second 1, etc. Note that only TiXmlElements are indexed: other types are not counted. </td> 223 </tr> 224 </table> 225 <a class="anchor" name="a9"></a><!-- doxytag: member="TiXmlHandle::ChildElement" ref="a9" args="(const char *value, int index) const " --><p> 226 <table class="mdTable" cellpadding="2" cellspacing="0"> 227 <tr> 228 <td class="mdRow"> 229 <table cellpadding="0" cellspacing="0" border="0"> 230 <tr> 231 <td class="md" nowrap valign="top"><a class="el" href="classTiXmlHandle.html">TiXmlHandle</a> TiXmlHandle::ChildElement </td> 232 <td class="md" valign="top">( </td> 233 <td class="md" nowrap valign="top">const char * </td> 234 <td class="mdname" nowrap> <em>value</em>, </td> 235 </tr> 236 <tr> 237 <td class="md" nowrap align="right"></td> 238 <td class="md"></td> 239 <td class="md" nowrap>int </td> 240 <td class="mdname" nowrap> <em>index</em></td> 241 </tr> 242 <tr> 243 <td class="md"></td> 244 <td class="md">) </td> 245 <td class="md" colspan="2"> const</td> 246 </tr> 247 </table> 248 </td> 249 </tr> 250 </table> 251 <table cellspacing="5" cellpadding="0" border="0"> 252 <tr> 253 <td> 254 255 </td> 256 <td> 257 258 <p> 259 Return a handle to the "index" child element with the given name. 260 <p> 261 The first child element is 0, the second 1, etc. Note that only TiXmlElements are indexed: other types are not counted. </td> 262 </tr> 263 </table> 264 <hr>The documentation for this class was generated from the following file:<ul> 265 <li><a class="el" href="tinyxml_8h-source.html">tinyxml.h</a></ul> 266 <hr size="1"><address style="align: right;"><small>Generated on Sat Oct 8 14:15:30 2005 for TinyXml by 267 <a href="http://www.doxygen.org/index.html"> 268 <img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.4.4 </small></address> 269 </body> 270 </html> 271
