Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / tinyxml / refs/tags/fp2-sibon-17.12.1 / . / docs / classTiXmlHandle.html
blob: f7af6026e46a09dbb0773a7730bacb13a213f7d4 [file] [log] [blame]
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]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">
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]3<title>TinyXml: TiXmlHandle Class Reference</title>
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]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&nbsp;Page</a> | <a class="qindex" href="hierarchy.html">Class&nbsp;Hierarchy</a> | <a class="qindex" href="annotated.html">Class&nbsp;List</a> | <a class="qindex" href="files.html">File&nbsp;List</a> | <a class="qindex" href="functions.html">Class&nbsp;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 &lt;<a class="el" href="tinyxml_8h-source.html">tinyxml.h</a>&gt;</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&nbsp;</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>
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]18
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]19<tr><td class="mdescLeft">&nbsp;</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 &amp;ref)" -->
21&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classTiXmlHandle.html#a1">TiXmlHandle</a> (const <a class="el" href="classTiXmlHandle.html">TiXmlHandle</a> &amp;ref)</td></tr>
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]22
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]23<tr><td class="mdescLeft">&nbsp;</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>&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classTiXmlHandle.html#a3">FirstChild</a> () const </td></tr>
26
27<tr><td class="mdescLeft">&nbsp;</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>&nbsp;</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">&nbsp;</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>&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classTiXmlHandle.html#a5">FirstChildElement</a> () const </td></tr>
34
35<tr><td class="mdescLeft">&nbsp;</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>&nbsp;</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">&nbsp;</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>&nbsp;</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">&nbsp;</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>&nbsp;</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">&nbsp;</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>&nbsp;</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">&nbsp;</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>&nbsp;</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">&nbsp;</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> *&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classTiXmlHandle.html#a15">Node</a> () const </td></tr>
54
55<tr><td class="mdescLeft">&nbsp;</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> *&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classTiXmlHandle.html#a16">Element</a> () const </td></tr>
58
59<tr><td class="mdescLeft">&nbsp;</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> *&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classTiXmlHandle.html#a17">Text</a> () const </td></tr>
62
63<tr><td class="mdescLeft">&nbsp;</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> *&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classTiXmlHandle.html#a18">Unknown</a> () const </td></tr>
66
67<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Return the handle as a <a class="el" href="classTiXmlUnknown.html">TiXmlUnknown</a>. This may return null;. <br></td></tr>
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]68</table>
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]69<hr><a name="_details"></a><h2>Detailed Description</h2>
70A TiXmlHandle is a class that wraps a node pointer with null checks; this is an incredibly useful thing.
71<p>
72Note that TiXmlHandle is not part of the TinyXml DOM structure. It is a separate utility class.<p>
73Take an example: <div class="fragment"><pre class="fragment"> &lt;Document&gt;
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]74 &lt;Element attributeA = "valueA"&gt;
75 &lt;Child attributeB = "value1" /&gt;
76 &lt;Child attributeB = "value2" /&gt;
77 &lt;/Element&gt;
78 &lt;Document&gt;
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]79 </pre></div><p>
80Assuming 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" );
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]82 if ( root )
83 {
84 TiXmlElement* element = root-&gt;FirstChildElement( "Element" );
85 if ( element )
86 {
87 TiXmlElement* child = element-&gt;FirstChildElement( "Child" );
88 if ( child )
89 {
90 TiXmlElement* child2 = child-&gt;NextSiblingElement( "Child" );
91 if ( child2 )
92 {
93 // Finally do something useful.
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]94 </pre></div><p>
95And 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( &amp;document );
97 TiXmlElement* child2 = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", 1 ).Element();
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]98 if ( child2 )
99 {
100 // do something useful
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]101 </pre></div><p>
102Which is MUCH more concise and useful.<p>
103It 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>
105What they should not be used for is iteration:<p>
106<div class="fragment"><pre class="fragment"> int i=0;
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]107 while ( true )
108 {
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]109 TiXmlElement* child = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", i ).Element();
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]110 if ( !child )
111 break;
112 // do something
113 ++i;
114 }
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]115 </pre></div><p>
116It 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();
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]118
119 for( child; child; child=child-&gt;NextSiblingElement() )
120 {
121 // do something
122 }
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]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">
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]131 <tr>
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]132 <td class="md" nowrap valign="top"><a class="el" href="classTiXmlHandle.html">TiXmlHandle</a> TiXmlHandle::Child </td>
133 <td class="md" valign="top">(&nbsp;</td>
134 <td class="md" nowrap valign="top">int&nbsp;</td>
135 <td class="mdname1" valign="top" nowrap> <em>index</em> </td>
136 <td class="md" valign="top">&nbsp;)&nbsp;</td>
137 <td class="md" nowrap> const</td>
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]138 </tr>
139 </table>
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]140 </td>
141 </tr>
142</table>
143<table cellspacing="5" cellpadding="0" border="0">
144 <tr>
145 <td>
146 &nbsp;
147 </td>
148 <td>
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]149
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]150<p>
151Return a handle to the "index" child.
152<p>
153The 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">
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]161 <tr>
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]162 <td class="md" nowrap valign="top"><a class="el" href="classTiXmlHandle.html">TiXmlHandle</a> TiXmlHandle::Child </td>
163 <td class="md" valign="top">(&nbsp;</td>
164 <td class="md" nowrap valign="top">const char *&nbsp;</td>
165 <td class="mdname" nowrap> <em>value</em>, </td>
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]166 </tr>
167 <tr>
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]168 <td class="md" nowrap align="right"></td>
169 <td class="md"></td>
170 <td class="md" nowrap>int&nbsp;</td>
171 <td class="mdname" nowrap> <em>index</em></td>
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]172 </tr>
173 <tr>
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]174 <td class="md"></td>
175 <td class="md">)&nbsp;</td>
176 <td class="md" colspan="2"> const</td>
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]177 </tr>
178 </table>
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]179 </td>
180 </tr>
181</table>
182<table cellspacing="5" cellpadding="0" border="0">
183 <tr>
184 <td>
185 &nbsp;
186 </td>
187 <td>
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]188
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]189<p>
190Return a handle to the "index" child with the given name.
191<p>
192The 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">
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]200 <tr>
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]201 <td class="md" nowrap valign="top"><a class="el" href="classTiXmlHandle.html">TiXmlHandle</a> TiXmlHandle::ChildElement </td>
202 <td class="md" valign="top">(&nbsp;</td>
203 <td class="md" nowrap valign="top">int&nbsp;</td>
204 <td class="mdname1" valign="top" nowrap> <em>index</em> </td>
205 <td class="md" valign="top">&nbsp;)&nbsp;</td>
206 <td class="md" nowrap> const</td>
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]207 </tr>
208 </table>
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]209 </td>
210 </tr>
211</table>
212<table cellspacing="5" cellpadding="0" border="0">
213 <tr>
214 <td>
215 &nbsp;
216 </td>
217 <td>
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]218
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]219<p>
220Return a handle to the "index" child element.
221<p>
222The 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">
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]230 <tr>
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]231 <td class="md" nowrap valign="top"><a class="el" href="classTiXmlHandle.html">TiXmlHandle</a> TiXmlHandle::ChildElement </td>
232 <td class="md" valign="top">(&nbsp;</td>
233 <td class="md" nowrap valign="top">const char *&nbsp;</td>
234 <td class="mdname" nowrap> <em>value</em>, </td>
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]235 </tr>
236 <tr>
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]237 <td class="md" nowrap align="right"></td>
238 <td class="md"></td>
239 <td class="md" nowrap>int&nbsp;</td>
240 <td class="mdname" nowrap> <em>index</em></td>
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]241 </tr>
242 <tr>
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]243 <td class="md"></td>
244 <td class="md">)&nbsp;</td>
245 <td class="md" colspan="2"> const</td>
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]246 </tr>
247 </table>
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]248 </td>
249 </tr>
250</table>
251<table cellspacing="5" cellpadding="0" border="0">
252 <tr>
253 <td>
254 &nbsp;
255 </td>
256 <td>
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]257
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]258<p>
259Return a handle to the "index" child element with the given name.
260<p>
261The 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&nbsp;
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]267<a href="http://www.doxygen.org/index.html">
Dan Albert0238a202014-08-22 00:52:41 +0000[diff] [blame]268<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.4.4 </small></address>
The Android Open Source Project562be062009-03-03 19:30:48 -0800[diff] [blame]269</body>
270</html>