Newer
Older
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
<span class="tok-n">xml_attribute</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">first_attribute</span><span class="tok-p">()</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-n">xml_attribute</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">last_attribute</span><span class="tok-p">()</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-n">xml_attribute</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-n">next_attribute</span><span class="tok-p">()</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-n">xml_attribute</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-n">previous_attribute</span><span class="tok-p">()</span> <span class="tok-k">const</span><span class="tok-p">;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p><code>parent</code> function returns the node’s parent; all non-null nodes except the document have non-null parent. <code>first_child</code> and <code>last_child</code> return the first and last child of the node, respectively; note that only document nodes and element nodes can have non-empty child node list. If node has no children, both functions return null nodes. <code>next_sibling</code> and <code>previous_sibling</code> return the node that’s immediately to the right/left of this node in the children list, respectively - for example, in <code><a/><b/><c/></code>, calling <code>next_sibling</code> for a handle that points to <code><b/></code> results in a handle pointing to <code><c/></code>, and calling <code>previous_sibling</code> results in handle pointing to <code><a/></code>. If node does not have next/previous sibling (this happens if it is the last/first node in the list, respectively), the functions return null nodes. <code>first_attribute</code>, <code>last_attribute</code>, <code>next_attribute</code> and <code>previous_attribute</code> functions behave similarly to the corresponding child node functions and allow to iterate through attribute list in the same way.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
Because of memory consumption reasons, attributes do not have a link to their parent nodes. Thus there is no <code>xml_attribute::parent()</code> function.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Calling any of the functions above on the null handle results in a null handle - i.e. <code>node.first_child().next_sibling()</code> returns the second child of <code>node</code>, and null handle if <code>node</code> is null, has no children at all or if it has only one child node.</p>
</div>
<div class="paragraph">
<p>With these functions, you can iterate through all child nodes and display all attributes like this (<a href="samples/traverse_base.cpp" class="bare">samples/traverse_base.cpp</a>):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-k">for</span> <span class="tok-p">(</span><span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_node</span> <span class="tok-n">tool</span> <span class="tok-o">=</span> <span class="tok-n">tools</span><span class="tok-p">.</span><span class="tok-n">first_child</span><span class="tok-p">();</span> <span class="tok-n">tool</span><span class="tok-p">;</span> <span class="tok-n">tool</span> <span class="tok-o">=</span> <span class="tok-n">tool</span><span class="tok-p">.</span><span class="tok-n">next_sibling</span><span class="tok-p">())</span>
<span class="tok-p">{</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-s">"Tool:"</span><span class="tok-p">;</span>
<span class="tok-k">for</span> <span class="tok-p">(</span><span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_attribute</span> <span class="tok-n">attr</span> <span class="tok-o">=</span> <span class="tok-n">tool</span><span class="tok-p">.</span><span class="tok-n">first_attribute</span><span class="tok-p">();</span> <span class="tok-n">attr</span><span class="tok-p">;</span> <span class="tok-n">attr</span> <span class="tok-o">=</span> <span class="tok-n">attr</span><span class="tok-p">.</span><span class="tok-n">next_attribute</span><span class="tok-p">())</span>
<span class="tok-p">{</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-s">" "</span> <span class="tok-o"><<</span> <span class="tok-n">attr</span><span class="tok-p">.</span><span class="tok-n">name</span><span class="tok-p">()</span> <span class="tok-o"><<</span> <span class="tok-s">"="</span> <span class="tok-o"><<</span> <span class="tok-n">attr</span><span class="tok-p">.</span><span class="tok-n">value</span><span class="tok-p">();</span>
<span class="tok-p">}</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">endl</span><span class="tok-p">;</span>
<span class="tok-p">}</span></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="access.nodedata"><a class="anchor" href="#access.nodedata"></a><a class="link" href="#access.nodedata">5.2. Getting node data</a></h3>
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
<div class="paragraph">
<p><a id="xml_node::name"></a><a id="xml_node::value"></a>
Apart from structural information (parent, child nodes, attributes), nodes can have name and value, both of which are strings. Depending on node type, name or value may be absent. <a href="#node_document">node_document</a> nodes do not have a name or value, <a href="#node_element">node_element</a> and <a href="#node_declaration">node_declaration</a> nodes always have a name but never have a value, <a href="#node_pcdata">node_pcdata</a>, <a href="#node_cdata">node_cdata</a>, <a href="#node_comment">node_comment</a> and <a href="#node_doctype">node_doctype</a> nodes never have a name but always have a value (it may be empty though), <a href="#node_pi">node_pi</a> nodes always have a name and a value (again, value may be empty). In order to get node’s name or value, you can use the following functions:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">name</span><span class="tok-p">()</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">value</span><span class="tok-p">()</span> <span class="tok-k">const</span><span class="tok-p">;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>In case node does not have a name or value or if the node handle is null, both functions return empty strings - they never return null pointers.</p>
</div>
<div id="xml_node::child_value" class="paragraph">
<p>It is common to store data as text contents of some node - i.e. <code><node><description>This is a node</description></node></code>. In this case, <code><description></code> node does not have a value, but instead has a child of type <a href="#node_pcdata">node_pcdata</a> with value <code>"This is a node"</code>. pugixml provides several helper functions to parse such data:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">child_value</span><span class="tok-p">()</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">child_value</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">name</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-n">xml_text</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">text</span><span class="tok-p">()</span> <span class="tok-k">const</span><span class="tok-p">;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p><code>child_value()</code> returns the value of the first child with type <a href="#node_pcdata">node_pcdata</a> or <a href="#node_cdata">node_cdata</a>; <code>child_value(name)</code> is a simple wrapper for <code>child(name).child_value()</code>. For the above example, calling <code>node.child_value("description")</code> and <code>description.child_value()</code> will both produce string <code>"This is a node"</code>. If there is no child with relevant type, or if the handle is null, <code>child_value</code> functions return empty string.</p>
</div>
<div class="paragraph">
<p><code>text()</code> returns a special object that can be used for working with PCDATA contents in more complex cases than just retrieving the value; it is described in <a href="#access.text">Working with text contents</a> sections.</p>
</div>
<div class="paragraph">
<p>There is an example of using some of these functions <a href="#code_traverse_base_data">at the end of the next section</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="access.attrdata"><a class="anchor" href="#access.attrdata"></a><a class="link" href="#access.attrdata">5.3. Getting attribute data</a></h3>
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
<div class="paragraph">
<p><a id="xml_attribute::name"></a><a id="xml_attribute::value"></a>
All attributes have name and value, both of which are strings (value may be empty). There are two corresponding accessors, like for <code>xml_node</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-n">name</span><span class="tok-p">()</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-n">value</span><span class="tok-p">()</span> <span class="tok-k">const</span><span class="tok-p">;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>In case the attribute handle is null, both functions return empty strings - they never return null pointers.</p>
</div>
<div id="xml_attribute::as_string" class="paragraph">
<p>If you need a non-empty string if the attribute handle is null (for example, you need to get the option value from XML attribute, but if it is not specified, you need it to default to <code>"sorted"</code> instead of <code>""</code>), you can use <code>as_string</code> accessor:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-n">as_string</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">def</span> <span class="tok-o">=</span> <span class="tok-s">""</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>It returns <code>def</code> argument if the attribute handle is null. If you do not specify the argument, the function is equivalent to <code>value()</code>.</p>
</div>
<div class="paragraph">
<p><a id="xml_attribute::as_int"></a><a id="xml_attribute::as_uint"></a><a id="xml_attribute::as_double"></a><a id="xml_attribute::as_float"></a><a id="xml_attribute::as_bool"></a><a id="xml_attribute::as_llong"></a><a id="xml_attribute::as_ullong"></a>
In many cases attribute values have types that are not strings - i.e. an attribute may always contain values that should be treated as integers, despite the fact that they are represented as strings in XML. pugixml provides several accessors that convert attribute value to some other type:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-kt">int</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-n">as_int</span><span class="tok-p">(</span><span class="tok-kt">int</span> <span class="tok-n">def</span> <span class="tok-o">=</span> <span class="tok-mi">0</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-kt">unsigned</span> <span class="tok-kt">int</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-n">as_uint</span><span class="tok-p">(</span><span class="tok-kt">unsigned</span> <span class="tok-kt">int</span> <span class="tok-n">def</span> <span class="tok-o">=</span> <span class="tok-mi">0</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-kt">double</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-n">as_double</span><span class="tok-p">(</span><span class="tok-kt">double</span> <span class="tok-n">def</span> <span class="tok-o">=</span> <span class="tok-mi">0</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-kt">float</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-n">as_float</span><span class="tok-p">(</span><span class="tok-kt">float</span> <span class="tok-n">def</span> <span class="tok-o">=</span> <span class="tok-mi">0</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-kt">bool</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-n">as_bool</span><span class="tok-p">(</span><span class="tok-kt">bool</span> <span class="tok-n">def</span> <span class="tok-o">=</span> <span class="tok-nb">false</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-kt">long</span> <span class="tok-kt">long</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-n">as_llong</span><span class="tok-p">(</span><span class="tok-kt">long</span> <span class="tok-kt">long</span> <span class="tok-n">def</span> <span class="tok-o">=</span> <span class="tok-mi">0</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-kt">unsigned</span> <span class="tok-kt">long</span> <span class="tok-kt">long</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-n">as_ullong</span><span class="tok-p">(</span><span class="tok-kt">unsigned</span> <span class="tok-kt">long</span> <span class="tok-kt">long</span> <span class="tok-n">def</span> <span class="tok-o">=</span> <span class="tok-mi">0</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p><code>as_int</code>, <code>as_uint</code>, <code>as_llong</code>, <code>as_ullong</code>, <code>as_double</code> and <code>as_float</code> convert attribute values to numbers. If attribute handle is null <code>def</code> argument is returned (which is 0 by default). Otherwise, all leading whitespace characters are truncated, and the remaining string is parsed as an integer number in either decimal or hexadecimal form (applicable to <code>as_int</code>, <code>as_uint</code>, <code>as_llong</code> and <code>as_ullong</code>; hexadecimal format is used if the number has <code>0x</code> or <code>0X</code> prefix) or as a floating point number in either decimal or scientific form (<code>as_double</code> or <code>as_float</code>).</p>
</div>
<div class="paragraph">
<p>In case the input string contains a non-numeric character sequence or a number that is out of the target numeric range, the result is undefined.</p>
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<div class="title">Caution</div>
</td>
<td class="content">
Number conversion functions depend on current C locale as set with <code>setlocale</code>, so may return unexpected results if the locale is different from <code>"C"</code>.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p><code>as_bool</code> converts attribute value to boolean as follows: if attribute handle is null, <code>def</code> argument is returned (which is <code>false</code> by default). If attribute value is empty, <code>false</code> is returned. Otherwise, <code>true</code> is returned if the first character is one of <code>'1', 't', 'T', 'y', 'Y'</code>. This means that strings like <code>"true"</code> and <code>"yes"</code> are recognized as <code>true</code>, while strings like <code>"false"</code> and <code>"no"</code> are recognized as <code>false</code>. For more complex matching you’ll have to write your own function.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
<code>as_llong</code> and <code>as_ullong</code> are only available if your platform has reliable support for the <code>long long</code> type, including string conversions.
</td>
</tr>
</table>
</div>
<div id="code_traverse_base_data" class="paragraph">
<p>This is an example of using these functions, along with node data retrieval ones (<a href="samples/traverse_base.cpp" class="bare">samples/traverse_base.cpp</a>):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-k">for</span> <span class="tok-p">(</span><span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_node</span> <span class="tok-n">tool</span> <span class="tok-o">=</span> <span class="tok-n">tools</span><span class="tok-p">.</span><span class="tok-n">child</span><span class="tok-p">(</span><span class="tok-s">"Tool"</span><span class="tok-p">);</span> <span class="tok-n">tool</span><span class="tok-p">;</span> <span class="tok-n">tool</span> <span class="tok-o">=</span> <span class="tok-n">tool</span><span class="tok-p">.</span><span class="tok-n">next_sibling</span><span class="tok-p">(</span><span class="tok-s">"Tool"</span><span class="tok-p">))</span>
<span class="tok-p">{</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-s">"Tool "</span> <span class="tok-o"><<</span> <span class="tok-n">tool</span><span class="tok-p">.</span><span class="tok-n">attribute</span><span class="tok-p">(</span><span class="tok-s">"Filename"</span><span class="tok-p">).</span><span class="tok-n">value</span><span class="tok-p">();</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-s">": AllowRemote "</span> <span class="tok-o"><<</span> <span class="tok-n">tool</span><span class="tok-p">.</span><span class="tok-n">attribute</span><span class="tok-p">(</span><span class="tok-s">"AllowRemote"</span><span class="tok-p">).</span><span class="tok-n">as_bool</span><span class="tok-p">();</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-s">", Timeout "</span> <span class="tok-o"><<</span> <span class="tok-n">tool</span><span class="tok-p">.</span><span class="tok-n">attribute</span><span class="tok-p">(</span><span class="tok-s">"Timeout"</span><span class="tok-p">).</span><span class="tok-n">as_int</span><span class="tok-p">();</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-s">", Description '"</span> <span class="tok-o"><<</span> <span class="tok-n">tool</span><span class="tok-p">.</span><span class="tok-n">child_value</span><span class="tok-p">(</span><span class="tok-s">"Description"</span><span class="tok-p">)</span> <span class="tok-o"><<</span> <span class="tok-s">"'</span><span class="tok-se">\n</span><span class="tok-s">"</span><span class="tok-p">;</span>
<span class="tok-p">}</span></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="access.contents"><a class="anchor" href="#access.contents"></a><a class="link" href="#access.contents">5.4. Contents-based traversal functions</a></h3>
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
<div class="paragraph">
<p><a id="xml_node::child"></a><a id="xml_node::attribute"></a><a id="xml_node::next_sibling_name"></a><a id="xml_node::previous_sibling_name"></a>
Since a lot of document traversal consists of finding the node/attribute with the correct name, there are special functions for that purpose:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-n">xml_node</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">child</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">name</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-n">xml_attribute</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">attribute</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">name</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-n">xml_node</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">next_sibling</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">name</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-n">xml_node</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">previous_sibling</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">name</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p><code>child</code> and <code>attribute</code> return the first child/attribute with the specified name; <code>next_sibling</code> and <code>previous_sibling</code> return the first sibling in the corresponding direction with the specified name. All string comparisons are case-sensitive. In case the node handle is null or there is no node/attribute with the specified name, null handle is returned.</p>
</div>
<div class="paragraph">
<p><code>child</code> and <code>next_sibling</code> functions can be used together to loop through all child nodes with the desired name like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-k">for</span> <span class="tok-p">(</span><span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_node</span> <span class="tok-n">tool</span> <span class="tok-o">=</span> <span class="tok-n">tools</span><span class="tok-p">.</span><span class="tok-n">child</span><span class="tok-p">(</span><span class="tok-s">"Tool"</span><span class="tok-p">);</span> <span class="tok-n">tool</span><span class="tok-p">;</span> <span class="tok-n">tool</span> <span class="tok-o">=</span> <span class="tok-n">tool</span><span class="tok-p">.</span><span class="tok-n">next_sibling</span><span class="tok-p">(</span><span class="tok-s">"Tool"</span><span class="tok-p">))</span></code></pre>
</div>
</div>
<div id="xml_node::find_child_by_attribute" class="paragraph">
<p>Occasionally the needed node is specified not by the unique name but instead by the value of some attribute; for example, it is common to have node collections with each node having a unique id: <code><group><item id="1"/> <item id="2"/></group></code>. There are two functions for finding child nodes based on the attribute values:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-n">xml_node</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">find_child_by_attribute</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">name</span><span class="tok-p">,</span> <span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">attr_name</span><span class="tok-p">,</span> <span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">attr_value</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-n">xml_node</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">find_child_by_attribute</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">attr_name</span><span class="tok-p">,</span> <span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">attr_value</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The three-argument function returns the first child node with the specified name which has an attribute with the specified name/value; the two-argument function skips the name test for the node, which can be useful for searching in heterogeneous collections. If the node handle is null or if no node is found, null handle is returned. All string comparisons are case-sensitive.</p>
</div>
<div class="paragraph">
<p>In all of the above functions, all arguments have to be valid strings; passing null pointers results in undefined behavior.</p>
</div>
<div class="paragraph">
<p>This is an example of using these functions (<a href="samples/traverse_base.cpp" class="bare">samples/traverse_base.cpp</a>):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-s">"Tool for *.dae generation: "</span> <span class="tok-o"><<</span> <span class="tok-n">tools</span><span class="tok-p">.</span><span class="tok-n">find_child_by_attribute</span><span class="tok-p">(</span><span class="tok-s">"Tool"</span><span class="tok-p">,</span> <span class="tok-s">"OutputFileMasks"</span><span class="tok-p">,</span> <span class="tok-s">"*.dae"</span><span class="tok-p">).</span><span class="tok-n">attribute</span><span class="tok-p">(</span><span class="tok-s">"Filename"</span><span class="tok-p">).</span><span class="tok-n">value</span><span class="tok-p">()</span> <span class="tok-o"><<</span> <span class="tok-s">"</span><span class="tok-se">\n</span><span class="tok-s">"</span><span class="tok-p">;</span>
<span class="tok-k">for</span> <span class="tok-p">(</span><span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_node</span> <span class="tok-n">tool</span> <span class="tok-o">=</span> <span class="tok-n">tools</span><span class="tok-p">.</span><span class="tok-n">child</span><span class="tok-p">(</span><span class="tok-s">"Tool"</span><span class="tok-p">);</span> <span class="tok-n">tool</span><span class="tok-p">;</span> <span class="tok-n">tool</span> <span class="tok-o">=</span> <span class="tok-n">tool</span><span class="tok-p">.</span><span class="tok-n">next_sibling</span><span class="tok-p">(</span><span class="tok-s">"Tool"</span><span class="tok-p">))</span>
<span class="tok-p">{</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-s">"Tool "</span> <span class="tok-o"><<</span> <span class="tok-n">tool</span><span class="tok-p">.</span><span class="tok-n">attribute</span><span class="tok-p">(</span><span class="tok-s">"Filename"</span><span class="tok-p">).</span><span class="tok-n">value</span><span class="tok-p">()</span> <span class="tok-o"><<</span> <span class="tok-s">"</span><span class="tok-se">\n</span><span class="tok-s">"</span><span class="tok-p">;</span>
<span class="tok-p">}</span></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="access.rangefor"><a class="anchor" href="#access.rangefor"></a><a class="link" href="#access.rangefor">5.5. Range-based for-loop support</a></h3>
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
<div class="paragraph">
<p><a id="xml_node::children"></a><a id="xml_node::attributes"></a>
If your C++ compiler supports range-based for-loop (this is a C++11 feature, at the time of writing it’s supported by Microsoft Visual Studio 2012+, GCC 4.6+ and Clang 3.0+), you can use it to enumerate nodes/attributes. Additional helpers are provided to support this; note that they are also compatible with <a href="http://www.boost.org/libs/foreach/">Boost Foreach</a>, and possibly other pre-C++11 foreach facilities.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-n"><em>implementation</em></span><span class="tok-o">-</span><span class="tok-n"><em>defined</em></span><span class="tok-o">-</span><span class="tok-n"><em>type</em></span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">children</span><span class="tok-p">()</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-n"><em>implementation</em></span><span class="tok-o">-</span><span class="tok-n"><em>defined</em></span><span class="tok-o">-</span><span class="tok-n"><em>type</em></span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">children</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">name</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-n"><em>implementation</em></span><span class="tok-o">-</span><span class="tok-n"><em>defined</em></span><span class="tok-o">-</span><span class="tok-n"><em>type</em></span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">attributes</span><span class="tok-p">()</span> <span class="tok-k">const</span><span class="tok-p">;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p><code>children</code> function allows you to enumerate all child nodes; <code>children</code> function with <code>name</code> argument allows you to enumerate all child nodes with a specific name; <code>attributes</code> function allows you to enumerate all attributes of the node. Note that you can also use node object itself in a range-based for construct, which is equivalent to using <code>children()</code>.</p>
</div>
<div class="paragraph">
<p>This is an example of using these functions (<a href="samples/traverse_rangefor.cpp" class="bare">samples/traverse_rangefor.cpp</a>):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-k">for</span> <span class="tok-p">(</span><span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_node</span> <span class="tok-nl">tool</span><span class="tok-p">:</span> <span class="tok-n">tools</span><span class="tok-p">.</span><span class="tok-n">children</span><span class="tok-p">(</span><span class="tok-s">"Tool"</span><span class="tok-p">))</span>
<span class="tok-p">{</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-s">"Tool:"</span><span class="tok-p">;</span>
<span class="tok-k">for</span> <span class="tok-p">(</span><span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_attribute</span> <span class="tok-nl">attr</span><span class="tok-p">:</span> <span class="tok-n">tool</span><span class="tok-p">.</span><span class="tok-n">attributes</span><span class="tok-p">())</span>
<span class="tok-p">{</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-s">" "</span> <span class="tok-o"><<</span> <span class="tok-n">attr</span><span class="tok-p">.</span><span class="tok-n">name</span><span class="tok-p">()</span> <span class="tok-o"><<</span> <span class="tok-s">"="</span> <span class="tok-o"><<</span> <span class="tok-n">attr</span><span class="tok-p">.</span><span class="tok-n">value</span><span class="tok-p">();</span>
<span class="tok-p">}</span>
<span class="tok-k">for</span> <span class="tok-p">(</span><span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_node</span> <span class="tok-nl">child</span><span class="tok-p">:</span> <span class="tok-n">tool</span><span class="tok-p">.</span><span class="tok-n">children</span><span class="tok-p">())</span>
<span class="tok-p">{</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-s">", child "</span> <span class="tok-o"><<</span> <span class="tok-n">child</span><span class="tok-p">.</span><span class="tok-n">name</span><span class="tok-p">();</span>
<span class="tok-p">}</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">endl</span><span class="tok-p">;</span>
<span class="tok-p">}</span></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="access.iterators"><a class="anchor" href="#access.iterators"></a><a class="link" href="#access.iterators">5.6. Traversing node/attribute lists via iterators</a></h3>
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
<div class="paragraph">
<p><a id="xml_node_iterator"></a><a id="xml_attribute_iterator"></a><a id="xml_node::begin"></a><a id="xml_node::end"></a><a id="xml_node::attributes_begin"></a><a id="xml_node::attributes_end"></a>
Child node lists and attribute lists are simply double-linked lists; while you can use <code>previous_sibling</code>/<code>next_sibling</code> and other such functions for iteration, pugixml additionally provides node and attribute iterators, so that you can treat nodes as containers of other nodes or attributes:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-k">class</span> <span class="tok-nc">xml_node_iterator</span><span class="tok-p">;</span>
<span class="tok-k">class</span> <span class="tok-nc">xml_attribute_iterator</span><span class="tok-p">;</span>
<span class="tok-k">typedef</span> <span class="tok-n">xml_node_iterator</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">iterator</span><span class="tok-p">;</span>
<span class="tok-n">iterator</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">begin</span><span class="tok-p">()</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-n">iterator</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">end</span><span class="tok-p">()</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-k">typedef</span> <span class="tok-n">xml_attribute_iterator</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">attribute_iterator</span><span class="tok-p">;</span>
<span class="tok-n">attribute_iterator</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">attributes_begin</span><span class="tok-p">()</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-n">attribute_iterator</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">attributes_end</span><span class="tok-p">()</span> <span class="tok-k">const</span><span class="tok-p">;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p><code>begin</code> and <code>attributes_begin</code> return iterators that point to the first node/attribute, respectively; <code>end</code> and <code>attributes_end</code> return past-the-end iterator for node/attribute list, respectively - this iterator can’t be dereferenced, but decrementing it results in an iterator pointing to the last element in the list (except for empty lists, where decrementing past-the-end iterator results in undefined behavior). Past-the-end iterator is commonly used as a termination value for iteration loops (see sample below). If you want to get an iterator that points to an existing handle, you can construct the iterator with the handle as a single constructor argument, like so: <code>xml_node_iterator(node)</code>. For <code>xml_attribute_iterator</code>, you’ll have to provide both an attribute and its parent node.</p>
</div>
<div class="paragraph">
<p><code>begin</code> and <code>end</code> return equal iterators if called on null node; such iterators can’t be dereferenced. <code>attributes_begin</code> and <code>attributes_end</code> behave the same way. For correct iterator usage this means that child node/attribute collections of null nodes appear to be empty.</p>
</div>
<div class="paragraph">
<p>Both types of iterators have bidirectional iterator semantics (i.e. they can be incremented and decremented, but efficient random access is not supported) and support all usual iterator operations - comparison, dereference, etc. The iterators are invalidated if the node/attribute objects they’re pointing to are removed from the tree; adding nodes/attributes does not invalidate any iterators.</p>
</div>
<div class="paragraph">
<p>Here is an example of using iterators for document traversal (<a href="samples/traverse_iter.cpp" class="bare">samples/traverse_iter.cpp</a>):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-k">for</span> <span class="tok-p">(</span><span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_node_iterator</span> <span class="tok-n">it</span> <span class="tok-o">=</span> <span class="tok-n">tools</span><span class="tok-p">.</span><span class="tok-n">begin</span><span class="tok-p">();</span> <span class="tok-n">it</span> <span class="tok-o">!=</span> <span class="tok-n">tools</span><span class="tok-p">.</span><span class="tok-n">end</span><span class="tok-p">();</span> <span class="tok-o">++</span><span class="tok-n">it</span><span class="tok-p">)</span>
<span class="tok-p">{</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-s">"Tool:"</span><span class="tok-p">;</span>
<span class="tok-k">for</span> <span class="tok-p">(</span><span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_attribute_iterator</span> <span class="tok-n">ait</span> <span class="tok-o">=</span> <span class="tok-n">it</span><span class="tok-o">-></span><span class="tok-n">attributes_begin</span><span class="tok-p">();</span> <span class="tok-n">ait</span> <span class="tok-o">!=</span> <span class="tok-n">it</span><span class="tok-o">-></span><span class="tok-n">attributes_end</span><span class="tok-p">();</span> <span class="tok-o">++</span><span class="tok-n">ait</span><span class="tok-p">)</span>
<span class="tok-p">{</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-s">" "</span> <span class="tok-o"><<</span> <span class="tok-n">ait</span><span class="tok-o">-></span><span class="tok-n">name</span><span class="tok-p">()</span> <span class="tok-o"><<</span> <span class="tok-s">"="</span> <span class="tok-o"><<</span> <span class="tok-n">ait</span><span class="tok-o">-></span><span class="tok-n">value</span><span class="tok-p">();</span>
<span class="tok-p">}</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">endl</span><span class="tok-p">;</span>
<span class="tok-p">}</span></code></pre>
</div>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<div class="title">Caution</div>
</td>
<td class="content">
Node and attribute iterators are somewhere in the middle between const and non-const iterators. While dereference operation yields a non-constant reference to the object, so that you can use it for tree modification operations, modifying this reference using assignment - i.e. passing iterators to a function like <code>std::sort</code> - will not give expected results, as assignment modifies local handle that’s stored in the iterator.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="access.walker"><a class="anchor" href="#access.walker"></a><a class="link" href="#access.walker">5.7. Recursive traversal with xml_tree_walker</a></h3>
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
<div id="xml_tree_walker" class="paragraph">
<p>The methods described above allow traversal of immediate children of some node; if you want to do a deep tree traversal, you’ll have to do it via a recursive function or some equivalent method. However, pugixml provides a helper for depth-first traversal of a subtree. In order to use it, you have to implement <code>xml_tree_walker</code> interface and to call <code>traverse</code> function:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-k">class</span> <span class="tok-nc">xml_tree_walker</span>
<span class="tok-p">{</span>
<span class="tok-k">public</span><span class="tok-o">:</span>
<span class="tok-k">virtual</span> <span class="tok-kt">bool</span> <span class="tok-n">begin</span><span class="tok-p">(</span><span class="tok-n">xml_node</span><span class="tok-o">&</span> <span class="tok-n">node</span><span class="tok-p">);</span>
<span class="tok-k">virtual</span> <span class="tok-kt">bool</span> <span class="tok-n">for_each</span><span class="tok-p">(</span><span class="tok-n">xml_node</span><span class="tok-o">&</span> <span class="tok-n">node</span><span class="tok-p">)</span> <span class="tok-o">=</span> <span class="tok-mi">0</span><span class="tok-p">;</span>
<span class="tok-k">virtual</span> <span class="tok-kt">bool</span> <span class="tok-nf">end</span><span class="tok-p">(</span><span class="tok-n">xml_node</span><span class="tok-o">&</span> <span class="tok-n">node</span><span class="tok-p">);</span>
<span class="tok-kt">int</span> <span class="tok-n">depth</span><span class="tok-p">()</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-p">};</span>
<span class="tok-kt">bool</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">traverse</span><span class="tok-p">(</span><span class="tok-n">xml_tree_walker</span><span class="tok-o">&</span> <span class="tok-n">walker</span><span class="tok-p">);</span></code></pre>
</div>
</div>
<div class="paragraph">
<p><a id="xml_tree_walker::begin"></a><a id="xml_tree_walker::for_each"></a><a id="xml_tree_walker::end"></a><a id="xml_node::traverse"></a>
The traversal is launched by calling <code>traverse</code> function on traversal root and proceeds as follows:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>First, <code>begin</code> function is called with traversal root as its argument.</p>
</li>
<li>
<p>Then, <code>for_each</code> function is called for all nodes in the traversal subtree in depth first order, excluding the traversal root. Node is passed as an argument.</p>
</li>
<li>
<p>Finally, <code>end</code> function is called with traversal root as its argument.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>If <code>begin</code>, <code>end</code> or any of the <code>for_each</code> calls return <code>false</code>, the traversal is terminated and <code>false</code> is returned as the traversal result; otherwise, the traversal results in <code>true</code>. Note that you don’t have to override <code>begin</code> or <code>end</code> functions; their default implementations return <code>true</code>.</p>
</div>
<div id="xml_tree_walker::depth" class="paragraph">
<p>You can get the node’s depth relative to the traversal root at any point by calling <code>depth</code> function. It returns <code>-1</code> if called from <code>begin</code>/<code>end</code>, and returns 0-based depth if called from <code>for_each</code> - depth is 0 for all children of the traversal root, 1 for all grandchildren and so on.</p>
</div>
<div class="paragraph">
<p>This is an example of traversing tree hierarchy with xml_tree_walker (<a href="samples/traverse_walker.cpp" class="bare">samples/traverse_walker.cpp</a>):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-k">struct</span> <span class="tok-nl">simple_walker</span><span class="tok-p">:</span> <span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_tree_walker</span>
<span class="tok-p">{</span>
<span class="tok-k">virtual</span> <span class="tok-kt">bool</span> <span class="tok-n">for_each</span><span class="tok-p">(</span><span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_node</span><span class="tok-o">&</span> <span class="tok-n">node</span><span class="tok-p">)</span>
<span class="tok-p">{</span>
<span class="tok-k">for</span> <span class="tok-p">(</span><span class="tok-kt">int</span> <span class="tok-n">i</span> <span class="tok-o">=</span> <span class="tok-mi">0</span><span class="tok-p">;</span> <span class="tok-n">i</span> <span class="tok-o"><</span> <span class="tok-n">depth</span><span class="tok-p">();</span> <span class="tok-o">++</span><span class="tok-n">i</span><span class="tok-p">)</span> <span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-s">" "</span><span class="tok-p">;</span> <span class="tok-c1">// indentation</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-n">node_types</span><span class="tok-p">[</span><span class="tok-n">node</span><span class="tok-p">.</span><span class="tok-n">type</span><span class="tok-p">()]</span> <span class="tok-o"><<</span> <span class="tok-s">": name='"</span> <span class="tok-o"><<</span> <span class="tok-n">node</span><span class="tok-p">.</span><span class="tok-n">name</span><span class="tok-p">()</span> <span class="tok-o"><<</span> <span class="tok-s">"', value='"</span> <span class="tok-o"><<</span> <span class="tok-n">node</span><span class="tok-p">.</span><span class="tok-n">value</span><span class="tok-p">()</span> <span class="tok-o"><<</span> <span class="tok-s">"'</span><span class="tok-se">\n</span><span class="tok-s">"</span><span class="tok-p">;</span>
<span class="tok-k">return</span> <span class="tok-nb">true</span><span class="tok-p">;</span> <span class="tok-c1">// continue traversal</span>
<span class="tok-p">}</span>
<span class="tok-p">};</span></code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-n">simple_walker</span> <span class="tok-n">walker</span><span class="tok-p">;</span>
<span class="tok-n">doc</span><span class="tok-p">.</span><span class="tok-n">traverse</span><span class="tok-p">(</span><span class="tok-n">walker</span><span class="tok-p">);</span></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="access.predicate"><a class="anchor" href="#access.predicate"></a><a class="link" href="#access.predicate">5.8. Searching for nodes/attributes with predicates</a></h3>
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
<div class="paragraph">
<p><a id="xml_node::find_attribute"></a><a id="xml_node::find_child"></a><a id="xml_node::find_node"></a>
While there are existing functions for getting a node/attribute with known contents, they are often not sufficient for simple queries. As an alternative for manual iteration through nodes/attributes until the needed one is found, you can make a predicate and call one of <code>find_</code> functions:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-k">template</span> <span class="tok-o"><</span><span class="tok-k">typename</span> <span class="tok-n">Predicate</span><span class="tok-o">></span> <span class="tok-n">xml_attribute</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">find_attribute</span><span class="tok-p">(</span><span class="tok-n">Predicate</span> <span class="tok-n">pred</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-k">template</span> <span class="tok-o"><</span><span class="tok-k">typename</span> <span class="tok-n">Predicate</span><span class="tok-o">></span> <span class="tok-n">xml_node</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">find_child</span><span class="tok-p">(</span><span class="tok-n">Predicate</span> <span class="tok-n">pred</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-k">template</span> <span class="tok-o"><</span><span class="tok-k">typename</span> <span class="tok-n">Predicate</span><span class="tok-o">></span> <span class="tok-n">xml_node</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">find_node</span><span class="tok-p">(</span><span class="tok-n">Predicate</span> <span class="tok-n">pred</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The predicate should be either a plain function or a function object which accepts one argument of type <code>xml_attribute</code> (for <code>find_attribute</code>) or <code>xml_node</code> (for <code>find_child</code> and <code>find_node</code>), and returns <code>bool</code>. The predicate is never called with null handle as an argument.</p>
</div>
<div class="paragraph">
<p><code>find_attribute</code> function iterates through all attributes of the specified node, and returns the first attribute for which the predicate returned <code>true</code>. If the predicate returned <code>false</code> for all attributes or if there were no attributes (including the case where the node is null), null attribute is returned.</p>
</div>
<div class="paragraph">
<p><code>find_child</code> function iterates through all child nodes of the specified node, and returns the first node for which the predicate returned <code>true</code>. If the predicate returned <code>false</code> for all nodes or if there were no child nodes (including the case where the node is null), null node is returned.</p>
</div>
<div class="paragraph">
<p><code>find_node</code> function performs a depth-first traversal through the subtree of the specified node (excluding the node itself), and returns the first node for which the predicate returned <code>true</code>. If the predicate returned <code>false</code> for all nodes or if subtree was empty, null node is returned.</p>
</div>
<div class="paragraph">
<p>This is an example of using predicate-based functions (<a href="samples/traverse_predicate.cpp" class="bare">samples/traverse_predicate.cpp</a>):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-kt">bool</span> <span class="tok-nf">small_timeout</span><span class="tok-p">(</span><span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_node</span> <span class="tok-n">node</span><span class="tok-p">)</span>
<span class="tok-p">{</span>
<span class="tok-k">return</span> <span class="tok-n">node</span><span class="tok-p">.</span><span class="tok-n">attribute</span><span class="tok-p">(</span><span class="tok-s">"Timeout"</span><span class="tok-p">).</span><span class="tok-n">as_int</span><span class="tok-p">()</span> <span class="tok-o"><</span> <span class="tok-mi">20</span><span class="tok-p">;</span>
<span class="tok-p">}</span>
<span class="tok-k">struct</span> <span class="tok-n">allow_remote_predicate</span>
<span class="tok-p">{</span>
<span class="tok-kt">bool</span> <span class="tok-k">operator</span><span class="tok-p">()(</span><span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_attribute</span> <span class="tok-n">attr</span><span class="tok-p">)</span> <span class="tok-k">const</span>
<span class="tok-p">{</span>
<span class="tok-k">return</span> <span class="tok-n">strcmp</span><span class="tok-p">(</span><span class="tok-n">attr</span><span class="tok-p">.</span><span class="tok-n">name</span><span class="tok-p">(),</span> <span class="tok-s">"AllowRemote"</span><span class="tok-p">)</span> <span class="tok-o">==</span> <span class="tok-mi">0</span><span class="tok-p">;</span>
<span class="tok-p">}</span>
<span class="tok-kt">bool</span> <span class="tok-k">operator</span><span class="tok-p">()(</span><span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_node</span> <span class="tok-n">node</span><span class="tok-p">)</span> <span class="tok-k">const</span>
<span class="tok-p">{</span>
<span class="tok-k">return</span> <span class="tok-n">node</span><span class="tok-p">.</span><span class="tok-n">attribute</span><span class="tok-p">(</span><span class="tok-s">"AllowRemote"</span><span class="tok-p">).</span><span class="tok-n">as_bool</span><span class="tok-p">();</span>
<span class="tok-p">}</span>
<span class="tok-p">};</span></code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-c1">// Find child via predicate (looks for direct children only)</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-n">tools</span><span class="tok-p">.</span><span class="tok-n">find_child</span><span class="tok-p">(</span><span class="tok-n">allow_remote_predicate</span><span class="tok-p">()).</span><span class="tok-n">attribute</span><span class="tok-p">(</span><span class="tok-s">"Filename"</span><span class="tok-p">).</span><span class="tok-n">value</span><span class="tok-p">()</span> <span class="tok-o"><<</span> <span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">endl</span><span class="tok-p">;</span>
<span class="tok-c1">// Find node via predicate (looks for all descendants in depth-first order)</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-n">doc</span><span class="tok-p">.</span><span class="tok-n">find_node</span><span class="tok-p">(</span><span class="tok-n">allow_remote_predicate</span><span class="tok-p">()).</span><span class="tok-n">attribute</span><span class="tok-p">(</span><span class="tok-s">"Filename"</span><span class="tok-p">).</span><span class="tok-n">value</span><span class="tok-p">()</span> <span class="tok-o"><<</span> <span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">endl</span><span class="tok-p">;</span>
<span class="tok-c1">// Find attribute via predicate</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-n">tools</span><span class="tok-p">.</span><span class="tok-n">last_child</span><span class="tok-p">().</span><span class="tok-n">find_attribute</span><span class="tok-p">(</span><span class="tok-n">allow_remote_predicate</span><span class="tok-p">()).</span><span class="tok-n">value</span><span class="tok-p">()</span> <span class="tok-o"><<</span> <span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">endl</span><span class="tok-p">;</span>
<span class="tok-c1">// We can use simple functions instead of function objects</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-n">tools</span><span class="tok-p">.</span><span class="tok-n">find_child</span><span class="tok-p">(</span><span class="tok-n">small_timeout</span><span class="tok-p">).</span><span class="tok-n">attribute</span><span class="tok-p">(</span><span class="tok-s">"Filename"</span><span class="tok-p">).</span><span class="tok-n">value</span><span class="tok-p">()</span> <span class="tok-o"><<</span> <span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">endl</span><span class="tok-p">;</span></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="access.text"><a class="anchor" href="#access.text"></a><a class="link" href="#access.text">5.9. Working with text contents</a></h3>
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
<div id="xml_text" class="paragraph">
<p>It is common to store data as text contents of some node - i.e. <code><node><description>This is a node</description></node></code>. In this case, <code><description></code> node does not have a value, but instead has a child of type <a href="#node_pcdata">node_pcdata</a> with value <code>"This is a node"</code>. pugixml provides a special class, <code>xml_text</code>, to work with such data. Working with text objects to modify data is described in <a href="#modify.text">the documentation for modifying document data</a>; this section describes the access interface of <code>xml_text</code>.</p>
</div>
<div id="xml_node::text" class="paragraph">
<p>You can get the text object from a node by using <code>text()</code> method:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-n">xml_text</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">text</span><span class="tok-p">()</span> <span class="tok-k">const</span><span class="tok-p">;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>If the node has a type <code>node_pcdata</code> or <code>node_cdata</code>, then the node itself is used to return data; otherwise, a first child node of type <code>node_pcdata</code> or <code>node_cdata</code> is used.</p>
</div>
<div class="paragraph">
<p><a id="xml_text::empty"></a><a id="xml_text::unspecified_bool_type"></a>
You can check if the text object is bound to a valid PCDATA/CDATA node by using it as a boolean value, i.e. <code>if (text) { …​ }</code> or <code>if (!text) { …​ }</code>. Alternatively you can check it by using the <code>empty()</code> method:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-kt">bool</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-n">empty</span><span class="tok-p">()</span> <span class="tok-k">const</span><span class="tok-p">;</span></code></pre>
</div>
</div>
<div id="xml_text::get" class="paragraph">
<p>Given a text object, you can get the contents (i.e. the value of PCDATA/CDATA node) by using the following function:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-n">get</span><span class="tok-p">()</span> <span class="tok-k">const</span><span class="tok-p">;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>In case text object is empty, the function returns an empty string - it never returns a null pointer.</p>
</div>
<div class="paragraph">
<p><a id="xml_text::as_string"></a><a id="xml_text::as_int"></a><a id="xml_text::as_uint"></a><a id="xml_text::as_double"></a><a id="xml_text::as_float"></a><a id="xml_text::as_bool"></a><a id="xml_text::as_llong"></a><a id="xml_text::as_ullong"></a>
If you need a non-empty string if the text object is empty, or if the text contents is actually a number or a boolean that is stored as a string, you can use the following accessors:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-n">as_string</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">def</span> <span class="tok-o">=</span> <span class="tok-s">""</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-kt">int</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-n">as_int</span><span class="tok-p">(</span><span class="tok-kt">int</span> <span class="tok-n">def</span> <span class="tok-o">=</span> <span class="tok-mi">0</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-kt">unsigned</span> <span class="tok-kt">int</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-n">as_uint</span><span class="tok-p">(</span><span class="tok-kt">unsigned</span> <span class="tok-kt">int</span> <span class="tok-n">def</span> <span class="tok-o">=</span> <span class="tok-mi">0</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-kt">double</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-n">as_double</span><span class="tok-p">(</span><span class="tok-kt">double</span> <span class="tok-n">def</span> <span class="tok-o">=</span> <span class="tok-mi">0</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-kt">float</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-n">as_float</span><span class="tok-p">(</span><span class="tok-kt">float</span> <span class="tok-n">def</span> <span class="tok-o">=</span> <span class="tok-mi">0</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-kt">bool</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-n">as_bool</span><span class="tok-p">(</span><span class="tok-kt">bool</span> <span class="tok-n">def</span> <span class="tok-o">=</span> <span class="tok-nb">false</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-kt">long</span> <span class="tok-kt">long</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-n">as_llong</span><span class="tok-p">(</span><span class="tok-kt">long</span> <span class="tok-kt">long</span> <span class="tok-n">def</span> <span class="tok-o">=</span> <span class="tok-mi">0</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-kt">unsigned</span> <span class="tok-kt">long</span> <span class="tok-kt">long</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-n">as_ullong</span><span class="tok-p">(</span><span class="tok-kt">unsigned</span> <span class="tok-kt">long</span> <span class="tok-kt">long</span> <span class="tok-n">def</span> <span class="tok-o">=</span> <span class="tok-mi">0</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>All of the above functions have the same semantics as similar <code>xml_attribute</code> members: they return the default argument if the text object is empty, they convert the text contents to a target type using the same rules and restrictions. You can <a href="#xml_attribute::as_int">refer to documentation for the attribute functions</a> for details.</p>
</div>
<div id="xml_text::data" class="paragraph">
<p><code>xml_text</code> is essentially a helper class that operates on <code>xml_node</code> values. It is bound to a node of type <a href="#node_pcdata">node_pcdata</a> or <a href="#node_cdata">node_cdata</a>. You can use the following function to retrieve this node:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-n">xml_node</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-n">data</span><span class="tok-p">()</span> <span class="tok-k">const</span><span class="tok-p">;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Essentially, assuming <code>text</code> is an <code>xml_text</code> object, calling <code>text.get()</code> is equivalent to calling <code>text.data().value()</code>.</p>
</div>
<div class="paragraph">
<p>This is an example of using <code>xml_text</code> object (<a href="samples/text.cpp" class="bare">samples/text.cpp</a>):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-s">"Project name: "</span> <span class="tok-o"><<</span> <span class="tok-n">project</span><span class="tok-p">.</span><span class="tok-n">child</span><span class="tok-p">(</span><span class="tok-s">"name"</span><span class="tok-p">).</span><span class="tok-n">text</span><span class="tok-p">().</span><span class="tok-n">get</span><span class="tok-p">()</span> <span class="tok-o"><<</span> <span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">endl</span><span class="tok-p">;</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-s">"Project version: "</span> <span class="tok-o"><<</span> <span class="tok-n">project</span><span class="tok-p">.</span><span class="tok-n">child</span><span class="tok-p">(</span><span class="tok-s">"version"</span><span class="tok-p">).</span><span class="tok-n">text</span><span class="tok-p">().</span><span class="tok-n">as_double</span><span class="tok-p">()</span> <span class="tok-o"><<</span> <span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">endl</span><span class="tok-p">;</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-s">"Project visibility: "</span> <span class="tok-o"><<</span> <span class="tok-p">(</span><span class="tok-n">project</span><span class="tok-p">.</span><span class="tok-n">child</span><span class="tok-p">(</span><span class="tok-s">"public"</span><span class="tok-p">).</span><span class="tok-n">text</span><span class="tok-p">().</span><span class="tok-n">as_bool</span><span class="tok-p">(</span><span class="tok-cm">/* def= */</span> <span class="tok-nb">true</span><span class="tok-p">)</span> <span class="tok-o">?</span> <span class="tok-s">"public"</span> <span class="tok-o">:</span> <span class="tok-s">"private"</span><span class="tok-p">)</span> <span class="tok-o"><<</span> <span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">endl</span><span class="tok-p">;</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-s">"Project description: "</span> <span class="tok-o"><<</span> <span class="tok-n">project</span><span class="tok-p">.</span><span class="tok-n">child</span><span class="tok-p">(</span><span class="tok-s">"description"</span><span class="tok-p">).</span><span class="tok-n">text</span><span class="tok-p">().</span><span class="tok-n">get</span><span class="tok-p">()</span> <span class="tok-o"><<</span> <span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">endl</span><span class="tok-p">;</span></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="access.misc"><a class="anchor" href="#access.misc"></a><a class="link" href="#access.misc">5.10. Miscellaneous functions</a></h3>
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
<div id="xml_node::root" class="paragraph">
<p>If you need to get the document root of some node, you can use the following function:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-n">xml_node</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">root</span><span class="tok-p">()</span> <span class="tok-k">const</span><span class="tok-p">;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>This function returns the node with type <a href="#node_document">node_document</a>, which is the root node of the document the node belongs to (unless the node is null, in which case null node is returned).</p>
</div>
<div class="paragraph">
<p><a id="xml_node::path"></a><a id="xml_node::first_element_by_path"></a>
While pugixml supports complex XPath expressions, sometimes a simple path handling facility is needed. There are two functions, for getting node path and for converting path to a node:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-kt">string_t</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">path</span><span class="tok-p">(</span><span class="tok-kt">char_t</span> <span class="tok-n">delimiter</span> <span class="tok-o">=</span> <span class="tok-sc">'/'</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span>
<span class="tok-n">xml_node</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">first_element_by_path</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">path</span><span class="tok-p">,</span> <span class="tok-kt">char_t</span> <span class="tok-n">delimiter</span> <span class="tok-o">=</span> <span class="tok-sc">'/'</span><span class="tok-p">)</span> <span class="tok-k">const</span><span class="tok-p">;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Node paths consist of node names, separated with a delimiter (which is <code>/</code> by default); also paths can contain self (<code>.</code>) and parent (<code>..</code>) pseudo-names, so that this is a valid path: <code>"../../foo/./bar"</code>. <code>path</code> returns the path to the node from the document root, <code>first_element_by_path</code> looks for a node represented by a given path; a path can be an absolute one (absolute paths start with the delimiter), in which case the rest of the path is treated as document root relative, and relative to the given node. For example, in the following document: <code><a><b><c/></b></a></code>, node <code><c/></code> has path <code>"a/b/c"</code>; calling <code>first_element_by_path</code> for document with path <code>"a/b"</code> results in node <code><b/></code>; calling <code>first_element_by_path</code> for node <code><a/></code> with path <code>"../a/./b/../."</code> results in node <code><a/></code>; calling <code>first_element_by_path</code> with path <code>"/a"</code> results in node <code><a/></code> for any node.</p>
</div>
<div class="paragraph">
<p>In case path component is ambiguous (if there are two nodes with given name), the first one is selected; paths are not guaranteed to uniquely identify nodes in a document. If any component of a path is not found, the result of <code>first_element_by_path</code> is null node; also <code>first_element_by_path</code> returns null node for null nodes, in which case the path does not matter. <code>path</code> returns an empty string for null nodes.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
<code>path</code> function returns the result as STL string, and thus is not available if <a href="#PUGIXML_NO_STL">PUGIXML_NO_STL</a> is defined.
</td>
</tr>
</table>
</div>
<div id="xml_node::offset_debug" class="paragraph">
<p>pugixml does not record row/column information for nodes upon parsing for efficiency reasons. However, if the node has not changed in a significant way since parsing (the name/value are not changed, and the node itself is the original one, i.e. it was not deleted from the tree and re-added later), it is possible to get the offset from the beginning of XML buffer:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-kt">ptrdiff_t</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">offset_debug</span><span class="tok-p">()</span> <span class="tok-k">const</span><span class="tok-p">;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>If the offset is not available (this happens if the node is null, was not originally parsed from a stream, or has changed in a significant way), the function returns -1. Otherwise it returns the offset to node’s data from the beginning of XML buffer in <a href="#char_t">pugi::char_t</a> units. For more information on parsing offsets, see <a href="#xml_parse_result::offset">parsing error handling documentation</a>.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="modify"><a class="anchor" href="#modify"></a><a class="link" href="#modify">6. Modifying document data</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>The document in pugixml is fully mutable: you can completely change the document structure and modify the data of nodes/attributes. This section provides documentation for the relevant functions. All functions take care of memory management and structural integrity themselves, so they always result in structurally valid tree - however, it is possible to create an invalid XML tree (for example, by adding two attributes with the same name or by setting attribute/node name to empty/invalid string). Tree modification is optimized for performance and for memory consumption, so if you have enough memory you can create documents from scratch with pugixml and later save them to file/stream instead of relying on error-prone manual text writing and without too much overhead.</p>
</div>
<div class="paragraph">
<p>All member functions that change node/attribute data or structure are non-constant and thus can not be called on constant handles. However, you can easily convert constant handle to non-constant one by simple assignment: <code>void foo(const pugi::xml_node& n) { pugi::xml_node nc = n; }</code>, so const-correctness here mainly provides additional documentation.</p>
</div>
<div class="sect2">
<h3 id="modify.nodedata"><a class="anchor" href="#modify.nodedata"></a><a class="link" href="#modify.nodedata">6.1. Setting node data</a></h3>
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
<div class="paragraph">
<p><a id="xml_node::set_name"></a><a id="xml_node::set_value"></a>
As discussed before, nodes can have name and value, both of which are strings. Depending on node type, name or value may be absent. <a href="#node_document">node_document</a> nodes do not have a name or value, <a href="#node_element">node_element</a> and <a href="#node_declaration">node_declaration</a> nodes always have a name but never have a value, <a href="#node_pcdata">node_pcdata</a>, <a href="#node_cdata">node_cdata</a>, <a href="#node_comment">node_comment</a> and <a href="#node_doctype">node_doctype</a> nodes never have a name but always have a value (it may be empty though), <a href="#node_pi">node_pi</a> nodes always have a name and a value (again, value may be empty). In order to set node’s name or value, you can use the following functions:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-kt">bool</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">set_name</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-kt">bool</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">set_value</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">rhs</span><span class="tok-p">);</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Both functions try to set the name/value to the specified string, and return the operation result. The operation fails if the node can not have name or value (for instance, when trying to call <code>set_name</code> on a <a href="#node_pcdata">node_pcdata</a> node), if the node handle is null, or if there is insufficient memory to handle the request. The provided string is copied into document managed memory and can be destroyed after the function returns (for example, you can safely pass stack-allocated buffers to these functions). The name/value content is not verified, so take care to use only valid XML names, or the document may become malformed.</p>
</div>
<div class="paragraph">
<p>This is an example of setting node name and value (<a href="samples/modify_base.cpp" class="bare">samples/modify_base.cpp</a>):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_node</span> <span class="tok-n">node</span> <span class="tok-o">=</span> <span class="tok-n">doc</span><span class="tok-p">.</span><span class="tok-n">child</span><span class="tok-p">(</span><span class="tok-s">"node"</span><span class="tok-p">);</span>
<span class="tok-c1">// change node name</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-n">node</span><span class="tok-p">.</span><span class="tok-n">set_name</span><span class="tok-p">(</span><span class="tok-s">"notnode"</span><span class="tok-p">);</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-s">", new node name: "</span> <span class="tok-o"><<</span> <span class="tok-n">node</span><span class="tok-p">.</span><span class="tok-n">name</span><span class="tok-p">()</span> <span class="tok-o"><<</span> <span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">endl</span><span class="tok-p">;</span>
<span class="tok-c1">// change comment text</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-n">doc</span><span class="tok-p">.</span><span class="tok-n">last_child</span><span class="tok-p">().</span><span class="tok-n">set_value</span><span class="tok-p">(</span><span class="tok-s">"useless comment"</span><span class="tok-p">);</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-s">", new comment text: "</span> <span class="tok-o"><<</span> <span class="tok-n">doc</span><span class="tok-p">.</span><span class="tok-n">last_child</span><span class="tok-p">().</span><span class="tok-n">value</span><span class="tok-p">()</span> <span class="tok-o"><<</span> <span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">endl</span><span class="tok-p">;</span>
<span class="tok-c1">// we can't change value of the element or name of the comment</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-n">node</span><span class="tok-p">.</span><span class="tok-n">set_value</span><span class="tok-p">(</span><span class="tok-s">"1"</span><span class="tok-p">)</span> <span class="tok-o"><<</span> <span class="tok-s">", "</span> <span class="tok-o"><<</span> <span class="tok-n">doc</span><span class="tok-p">.</span><span class="tok-n">last_child</span><span class="tok-p">().</span><span class="tok-n">set_name</span><span class="tok-p">(</span><span class="tok-s">"2"</span><span class="tok-p">)</span> <span class="tok-o"><<</span> <span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">endl</span><span class="tok-p">;</span></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="modify.attrdata"><a class="anchor" href="#modify.attrdata"></a><a class="link" href="#modify.attrdata">6.2. Setting attribute data</a></h3>
<div class="paragraph">
<p><a id="xml_attribute::set_name"></a><a id="xml_attribute::set_value"></a>
All attributes have name and value, both of which are strings (value may be empty). You can set them with the following functions:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-kt">bool</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-n">set_name</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-kt">bool</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-n">set_value</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">rhs</span><span class="tok-p">);</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Both functions try to set the name/value to the specified string, and return the operation result. The operation fails if the attribute handle is null, or if there is insufficient memory to handle the request. The provided string is copied into document managed memory and can be destroyed after the function returns (for example, you can safely pass stack-allocated buffers to these functions). The name/value content is not verified, so take care to use only valid XML names, or the document may become malformed.</p>
</div>
<div class="paragraph">
<p>In addition to string functions, several functions are provided for handling attributes with numbers and booleans as values:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-kt">bool</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-n">set_value</span><span class="tok-p">(</span><span class="tok-kt">int</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-kt">bool</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-n">set_value</span><span class="tok-p">(</span><span class="tok-kt">unsigned</span> <span class="tok-kt">int</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-kt">bool</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-n">set_value</span><span class="tok-p">(</span><span class="tok-kt">long</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-kt">bool</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-n">set_value</span><span class="tok-p">(</span><span class="tok-kt">unsigned</span> <span class="tok-kt">long</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
<span class="tok-kt">bool</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-n">set_value</span><span class="tok-p">(</span><span class="tok-kt">double</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-kt">bool</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-n">set_value</span><span class="tok-p">(</span><span class="tok-kt">float</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-kt">bool</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-n">set_value</span><span class="tok-p">(</span><span class="tok-kt">bool</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-kt">bool</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-n">set_value</span><span class="tok-p">(</span><span class="tok-kt">long</span> <span class="tok-kt">long</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-kt">bool</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-n">set_value</span><span class="tok-p">(</span><span class="tok-kt">unsigned</span> <span class="tok-kt">long</span> <span class="tok-kt">long</span> <span class="tok-n">rhs</span><span class="tok-p">);</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The above functions convert the argument to string and then call the base <code>set_value</code> function. Integers are converted to a decimal form, floating-point numbers are converted to either decimal or scientific form, depending on the number magnitude, boolean values are converted to either <code>"true"</code> or <code>"false"</code>.</p>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<div class="title">Caution</div>
</td>
<td class="content">
Number conversion functions depend on current C locale as set with <code>setlocale</code>, so may generate unexpected results if the locale is different from <code>"C"</code>.
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
<code>set_value</code> overloads with <code>long long</code> type are only available if your platform has reliable support for the type, including string conversions.
</td>
</tr>
</table>
</div>
<div id="xml_attribute::assign" class="paragraph">
<p>For convenience, all <code>set_value</code> functions have the corresponding assignment operators:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-n">xml_attribute</span><span class="tok-o">&</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-k">operator</span><span class="tok-o">=</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-n">xml_attribute</span><span class="tok-o">&</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-k">operator</span><span class="tok-o">=</span><span class="tok-p">(</span><span class="tok-kt">int</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-n">xml_attribute</span><span class="tok-o">&</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-k">operator</span><span class="tok-o">=</span><span class="tok-p">(</span><span class="tok-kt">unsigned</span> <span class="tok-kt">int</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-n">xml_attribute</span><span class="tok-o">&</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-k">operator</span><span class="tok-o">=</span><span class="tok-p">(</span><span class="tok-kt">long</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-n">xml_attribute</span><span class="tok-o">&</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-k">operator</span><span class="tok-o">=</span><span class="tok-p">(</span><span class="tok-kt">unsigned</span> <span class="tok-kt">long</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
<span class="tok-n">xml_attribute</span><span class="tok-o">&</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-k">operator</span><span class="tok-o">=</span><span class="tok-p">(</span><span class="tok-kt">double</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-n">xml_attribute</span><span class="tok-o">&</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-k">operator</span><span class="tok-o">=</span><span class="tok-p">(</span><span class="tok-kt">float</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-n">xml_attribute</span><span class="tok-o">&</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-k">operator</span><span class="tok-o">=</span><span class="tok-p">(</span><span class="tok-kt">bool</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-n">xml_attribute</span><span class="tok-o">&</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-k">operator</span><span class="tok-o">=</span><span class="tok-p">(</span><span class="tok-kt">long</span> <span class="tok-kt">long</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-n">xml_attribute</span><span class="tok-o">&</span> <span class="tok-n">xml_attribute</span><span class="tok-o">::</span><span class="tok-k">operator</span><span class="tok-o">=</span><span class="tok-p">(</span><span class="tok-kt">unsigned</span> <span class="tok-kt">long</span> <span class="tok-kt">long</span> <span class="tok-n">rhs</span><span class="tok-p">);</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>These operators simply call the right <code>set_value</code> function and return the attribute they’re called on; the return value of <code>set_value</code> is ignored, so errors are ignored.</p>
</div>
<div class="paragraph">
<p>This is an example of setting attribute name and value (<a href="samples/modify_base.cpp" class="bare">samples/modify_base.cpp</a>):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_attribute</span> <span class="tok-n">attr</span> <span class="tok-o">=</span> <span class="tok-n">node</span><span class="tok-p">.</span><span class="tok-n">attribute</span><span class="tok-p">(</span><span class="tok-s">"id"</span><span class="tok-p">);</span>
<span class="tok-c1">// change attribute name/value</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-n">attr</span><span class="tok-p">.</span><span class="tok-n">set_name</span><span class="tok-p">(</span><span class="tok-s">"key"</span><span class="tok-p">)</span> <span class="tok-o"><<</span> <span class="tok-s">", "</span> <span class="tok-o"><<</span> <span class="tok-n">attr</span><span class="tok-p">.</span><span class="tok-n">set_value</span><span class="tok-p">(</span><span class="tok-s">"345"</span><span class="tok-p">);</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-s">", new attribute: "</span> <span class="tok-o"><<</span> <span class="tok-n">attr</span><span class="tok-p">.</span><span class="tok-n">name</span><span class="tok-p">()</span> <span class="tok-o"><<</span> <span class="tok-s">"="</span> <span class="tok-o"><<</span> <span class="tok-n">attr</span><span class="tok-p">.</span><span class="tok-n">value</span><span class="tok-p">()</span> <span class="tok-o"><<</span> <span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">endl</span><span class="tok-p">;</span>
<span class="tok-c1">// we can use numbers or booleans</span>
<span class="tok-n">attr</span><span class="tok-p">.</span><span class="tok-n">set_value</span><span class="tok-p">(</span><span class="tok-mf">1.234</span><span class="tok-p">);</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-s">"new attribute value: "</span> <span class="tok-o"><<</span> <span class="tok-n">attr</span><span class="tok-p">.</span><span class="tok-n">value</span><span class="tok-p">()</span> <span class="tok-o"><<</span> <span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">endl</span><span class="tok-p">;</span>
<span class="tok-c1">// we can also use assignment operators for more concise code</span>
<span class="tok-n">attr</span> <span class="tok-o">=</span> <span class="tok-nb">true</span><span class="tok-p">;</span>
<span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-s">"final attribute value: "</span> <span class="tok-o"><<</span> <span class="tok-n">attr</span><span class="tok-p">.</span><span class="tok-n">value</span><span class="tok-p">()</span> <span class="tok-o"><<</span> <span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">endl</span><span class="tok-p">;</span></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="modify.add"><a class="anchor" href="#modify.add"></a><a class="link" href="#modify.add">6.3. Adding nodes/attributes</a></h3>
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
<div class="paragraph">
<p><a id="xml_node::prepend_attribute"></a><a id="xml_node::append_attribute"></a><a id="xml_node::insert_attribute_after"></a><a id="xml_node::insert_attribute_before"></a><a id="xml_node::prepend_child"></a><a id="xml_node::append_child"></a><a id="xml_node::insert_child_after"></a><a id="xml_node::insert_child_before"></a>
Nodes and attributes do not exist without a document tree, so you can’t create them without adding them to some document. A node or attribute can be created at the end of node/attribute list or before/after some other node:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-n">xml_attribute</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">append_attribute</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">name</span><span class="tok-p">);</span>
<span class="tok-n">xml_attribute</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">prepend_attribute</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">name</span><span class="tok-p">);</span>
<span class="tok-n">xml_attribute</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">insert_attribute_after</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">name</span><span class="tok-p">,</span> <span class="tok-k">const</span> <span class="tok-n">xml_attribute</span><span class="tok-o">&</span> <span class="tok-n">attr</span><span class="tok-p">);</span>
<span class="tok-n">xml_attribute</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">insert_attribute_before</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">name</span><span class="tok-p">,</span> <span class="tok-k">const</span> <span class="tok-n">xml_attribute</span><span class="tok-o">&</span> <span class="tok-n">attr</span><span class="tok-p">);</span>
<span class="tok-n">xml_node</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">append_child</span><span class="tok-p">(</span><span class="tok-n">xml_node_type</span> <span class="tok-n">type</span> <span class="tok-o">=</span> <span class="tok-n">node_element</span><span class="tok-p">);</span>
<span class="tok-n">xml_node</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">prepend_child</span><span class="tok-p">(</span><span class="tok-n">xml_node_type</span> <span class="tok-n">type</span> <span class="tok-o">=</span> <span class="tok-n">node_element</span><span class="tok-p">);</span>
<span class="tok-n">xml_node</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">insert_child_after</span><span class="tok-p">(</span><span class="tok-n">xml_node_type</span> <span class="tok-n">type</span><span class="tok-p">,</span> <span class="tok-k">const</span> <span class="tok-n">xml_node</span><span class="tok-o">&</span> <span class="tok-n">node</span><span class="tok-p">);</span>
<span class="tok-n">xml_node</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">insert_child_before</span><span class="tok-p">(</span><span class="tok-n">xml_node_type</span> <span class="tok-n">type</span><span class="tok-p">,</span> <span class="tok-k">const</span> <span class="tok-n">xml_node</span><span class="tok-o">&</span> <span class="tok-n">node</span><span class="tok-p">);</span>
<span class="tok-n">xml_node</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">append_child</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">name</span><span class="tok-p">);</span>
<span class="tok-n">xml_node</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">prepend_child</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">name</span><span class="tok-p">);</span>
<span class="tok-n">xml_node</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">insert_child_after</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">name</span><span class="tok-p">,</span> <span class="tok-k">const</span> <span class="tok-n">xml_node</span><span class="tok-o">&</span> <span class="tok-n">node</span><span class="tok-p">);</span>
<span class="tok-n">xml_node</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">insert_child_before</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">name</span><span class="tok-p">,</span> <span class="tok-k">const</span> <span class="tok-n">xml_node</span><span class="tok-o">&</span> <span class="tok-n">node</span><span class="tok-p">);</span></code></pre>
</div>
</div>
<div class="paragraph">
<p><code>append_attribute</code> and <code>append_child</code> create a new node/attribute at the end of the corresponding list of the node the method is called on; <code>prepend_attribute</code> and <code>prepend_child</code> create a new node/attribute at the beginning of the list; <code>insert_attribute_after</code>, <code>insert_attribute_before</code>, <code>insert_child_after</code> and <code>insert_attribute_before</code> add the node/attribute before or after the specified node/attribute.</p>
</div>
<div class="paragraph">
<p>Attribute functions create an attribute with the specified name; you can specify the empty name and change the name later if you want to. Node functions with the <code>type</code> argument create the node with the specified type; since node type can’t be changed, you have to know the desired type beforehand. Also note that not all types can be added as children; see below for clarification. Node functions with the <code>name</code> argument create the element node (<a href="#node_element">node_element</a>) with the specified name.</p>
</div>
<div class="paragraph">
<p>All functions return the handle to the created object on success, and null handle on failure. There are several reasons for failure:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Adding fails if the target node is null;</p>
</li>
<li>
<p>Only <a href="#node_element">node_element</a> nodes can contain attributes, so attribute adding fails if node is not an element;</p>
</li>
<li>
<p>Only <a href="#node_document">node_document</a> and <a href="#node_element">node_element</a> nodes can contain children, so child node adding fails if the target node is not an element or a document;</p>
</li>
<li>
<p><a href="#node_document">node_document</a> and <a href="#node_null">node_null</a> nodes can not be inserted as children, so passing <a href="#node_document">node_document</a> or <a href="#node_null">node_null</a> value as <code>type</code> results in operation failure;</p>
</li>
<li>
<p><a href="#node_declaration">node_declaration</a> nodes can only be added as children of the document node; attempt to insert declaration node as a child of an element node fails;</p>
</li>
<li>
<p>Adding node/attribute results in memory allocation, which may fail;</p>
</li>
<li>
<p>Insertion functions fail if the specified node or attribute is null or is not in the target node’s children/attribute list.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Even if the operation fails, the document remains in consistent state, but the requested node/attribute is not added.</p>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<div class="title">Caution</div>
</td>
<td class="content">
<code>attribute()</code> and <code>child()</code> functions do not add attributes or nodes to the tree, so code like <code>node.attribute("id") = 123;</code> will not do anything if <code>node</code> does not have an attribute with name <code>"id"</code>. Make sure you’re operating with existing attributes/nodes by adding them if necessary.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>This is an example of adding new attributes/nodes to the document (<a href="samples/modify_add.cpp" class="bare">samples/modify_add.cpp</a>):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-c1">// add node with some name</span>
<span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_node</span> <span class="tok-n">node</span> <span class="tok-o">=</span> <span class="tok-n">doc</span><span class="tok-p">.</span><span class="tok-n">append_child</span><span class="tok-p">(</span><span class="tok-s">"node"</span><span class="tok-p">);</span>
<span class="tok-c1">// add description node with text child</span>
<span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_node</span> <span class="tok-n">descr</span> <span class="tok-o">=</span> <span class="tok-n">node</span><span class="tok-p">.</span><span class="tok-n">append_child</span><span class="tok-p">(</span><span class="tok-s">"description"</span><span class="tok-p">);</span>
<span class="tok-n">descr</span><span class="tok-p">.</span><span class="tok-n">append_child</span><span class="tok-p">(</span><span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">node_pcdata</span><span class="tok-p">).</span><span class="tok-n">set_value</span><span class="tok-p">(</span><span class="tok-s">"Simple node"</span><span class="tok-p">);</span>
<span class="tok-c1">// add param node before the description</span>
<span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_node</span> <span class="tok-n">param</span> <span class="tok-o">=</span> <span class="tok-n">node</span><span class="tok-p">.</span><span class="tok-n">insert_child_before</span><span class="tok-p">(</span><span class="tok-s">"param"</span><span class="tok-p">,</span> <span class="tok-n">descr</span><span class="tok-p">);</span>
<span class="tok-c1">// add attributes to param node</span>
<span class="tok-n">param</span><span class="tok-p">.</span><span class="tok-n">append_attribute</span><span class="tok-p">(</span><span class="tok-s">"name"</span><span class="tok-p">)</span> <span class="tok-o">=</span> <span class="tok-s">"version"</span><span class="tok-p">;</span>
<span class="tok-n">param</span><span class="tok-p">.</span><span class="tok-n">append_attribute</span><span class="tok-p">(</span><span class="tok-s">"value"</span><span class="tok-p">)</span> <span class="tok-o">=</span> <span class="tok-mf">1.1</span><span class="tok-p">;</span>
<span class="tok-n">param</span><span class="tok-p">.</span><span class="tok-n">insert_attribute_after</span><span class="tok-p">(</span><span class="tok-s">"type"</span><span class="tok-p">,</span> <span class="tok-n">param</span><span class="tok-p">.</span><span class="tok-n">attribute</span><span class="tok-p">(</span><span class="tok-s">"name"</span><span class="tok-p">))</span> <span class="tok-o">=</span> <span class="tok-s">"float"</span><span class="tok-p">;</span></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="modify.remove"><a class="anchor" href="#modify.remove"></a><a class="link" href="#modify.remove">6.4. Removing nodes/attributes</a></h3>
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
<div class="paragraph">
<p><a id="xml_node::remove_attribute"></a><a id="xml_node::remove_child"></a>
If you do not want your document to contain some node or attribute, you can remove it with one of the following functions:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-kt">bool</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">remove_attribute</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-n">xml_attribute</span><span class="tok-o">&</span> <span class="tok-n">a</span><span class="tok-p">);</span>
<span class="tok-kt">bool</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">remove_child</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-n">xml_node</span><span class="tok-o">&</span> <span class="tok-n">n</span><span class="tok-p">);</span></code></pre>
</div>
</div>
<div class="paragraph">
<p><code>remove_attribute</code> removes the attribute from the attribute list of the node, and returns the operation result. <code>remove_child</code> removes the child node with the entire subtree (including all descendant nodes and attributes) from the document, and returns the operation result. Removing fails if one of the following is true:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The node the function is called on is null;</p>
</li>
<li>
<p>The attribute/node to be removed is null;</p>
</li>
<li>
<p>The attribute/node to be removed is not in the node’s attribute/child list.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Removing the attribute or node invalidates all handles to the same underlying object, and also invalidates all iterators pointing to the same object. Removing node also invalidates all past-the-end iterators to its attribute or child node list. Be careful to ensure that all such handles and iterators either do not exist or are not used after the attribute/node is removed.</p>
</div>
<div class="paragraph">
<p>If you want to remove the attribute or child node by its name, two additional helper functions are available:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-kt">bool</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">remove_attribute</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">name</span><span class="tok-p">);</span>
<span class="tok-kt">bool</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">remove_child</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">name</span><span class="tok-p">);</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>These functions look for the first attribute or child with the specified name, and then remove it, returning the result. If there is no attribute or child with such name, the function returns <code>false</code>; if there are two nodes with the given name, only the first node is deleted. If you want to delete all nodes with the specified name, you can use code like this: <code>while (node.remove_child("tool")) ;</code>.</p>
</div>
<div class="paragraph">
<p>This is an example of removing attributes/nodes from the document (<a href="samples/modify_remove.cpp" class="bare">samples/modify_remove.cpp</a>):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-c1">// remove description node with the whole subtree</span>
<span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_node</span> <span class="tok-n">node</span> <span class="tok-o">=</span> <span class="tok-n">doc</span><span class="tok-p">.</span><span class="tok-n">child</span><span class="tok-p">(</span><span class="tok-s">"node"</span><span class="tok-p">);</span>
<span class="tok-n">node</span><span class="tok-p">.</span><span class="tok-n">remove_child</span><span class="tok-p">(</span><span class="tok-s">"description"</span><span class="tok-p">);</span>
<span class="tok-c1">// remove id attribute</span>
<span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_node</span> <span class="tok-n">param</span> <span class="tok-o">=</span> <span class="tok-n">node</span><span class="tok-p">.</span><span class="tok-n">child</span><span class="tok-p">(</span><span class="tok-s">"param"</span><span class="tok-p">);</span>
<span class="tok-n">param</span><span class="tok-p">.</span><span class="tok-n">remove_attribute</span><span class="tok-p">(</span><span class="tok-s">"value"</span><span class="tok-p">);</span>
<span class="tok-c1">// we can also remove nodes/attributes by handles</span>
<span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_attribute</span> <span class="tok-n">id</span> <span class="tok-o">=</span> <span class="tok-n">param</span><span class="tok-p">.</span><span class="tok-n">attribute</span><span class="tok-p">(</span><span class="tok-s">"name"</span><span class="tok-p">);</span>
<span class="tok-n">param</span><span class="tok-p">.</span><span class="tok-n">remove_attribute</span><span class="tok-p">(</span><span class="tok-n">id</span><span class="tok-p">);</span></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="modify.text"><a class="anchor" href="#modify.text"></a><a class="link" href="#modify.text">6.5. Working with text contents</a></h3>
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
<div class="paragraph">
<p>pugixml provides a special class, <code>xml_text</code>, to work with text contents stored as a value of some node, i.e. <code><node><description>This is a node</description></node></code>. Working with text objects to retrieve data is described in <a href="#access.text">the documentation for accessing document data</a>; this section describes the modification interface of <code>xml_text</code>.</p>
</div>
<div id="xml_text::set" class="paragraph">
<p>Once you have an <code>xml_text</code> object, you can set the text contents using the following function:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-kt">bool</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-n">set</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">rhs</span><span class="tok-p">);</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>This function tries to set the contents to the specified string, and returns the operation result. The operation fails if the text object was retrieved from a node that can not have a value and is not an element node (i.e. it is a <a href="#node_declaration">node_declaration</a> node), if the text object is empty, or if there is insufficient memory to handle the request. The provided string is copied into document managed memory and can be destroyed after the function returns (for example, you can safely pass stack-allocated buffers to this function). Note that if the text object was retrieved from an element node, this function creates the PCDATA child node if necessary (i.e. if the element node does not have a PCDATA/CDATA child already).</p>
</div>
<div id="xml_text::set_value" class="paragraph">
<p>In addition to a string function, several functions are provided for handling text with numbers and booleans as contents:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-kt">bool</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-n">set</span><span class="tok-p">(</span><span class="tok-kt">int</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-kt">bool</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-n">set</span><span class="tok-p">(</span><span class="tok-kt">unsigned</span> <span class="tok-kt">int</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-kt">bool</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-n">set</span><span class="tok-p">(</span><span class="tok-kt">long</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-kt">bool</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-n">set</span><span class="tok-p">(</span><span class="tok-kt">unsigned</span> <span class="tok-kt">long</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-kt">bool</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-n">set</span><span class="tok-p">(</span><span class="tok-kt">double</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-kt">bool</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-n">set</span><span class="tok-p">(</span><span class="tok-kt">float</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-kt">bool</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-n">set</span><span class="tok-p">(</span><span class="tok-kt">bool</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-kt">bool</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-n">set</span><span class="tok-p">(</span><span class="tok-kt">long</span> <span class="tok-kt">long</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-kt">bool</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-n">set</span><span class="tok-p">(</span><span class="tok-kt">unsigned</span> <span class="tok-kt">long</span> <span class="tok-kt">long</span> <span class="tok-n">rhs</span><span class="tok-p">);</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The above functions convert the argument to string and then call the base <code>set</code> function. These functions have the same semantics as similar <code>xml_attribute</code> functions. You can <a href="#xml_attribute::set_value">refer to documentation for the attribute functions</a> for details.</p>
</div>
<div id="xml_text::assign" class="paragraph">
<p>For convenience, all <code>set</code> functions have the corresponding assignment operators:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-n">xml_text</span><span class="tok-o">&</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-k">operator</span><span class="tok-o">=</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-kt">char_t</span><span class="tok-o">*</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-n">xml_text</span><span class="tok-o">&</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-k">operator</span><span class="tok-o">=</span><span class="tok-p">(</span><span class="tok-kt">int</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-n">xml_text</span><span class="tok-o">&</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-k">operator</span><span class="tok-o">=</span><span class="tok-p">(</span><span class="tok-kt">unsigned</span> <span class="tok-kt">int</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-n">xml_text</span><span class="tok-o">&</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-k">operator</span><span class="tok-o">=</span><span class="tok-p">(</span><span class="tok-kt">long</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-n">xml_text</span><span class="tok-o">&</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-k">operator</span><span class="tok-o">=</span><span class="tok-p">(</span><span class="tok-kt">unsigned</span> <span class="tok-kt">long</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
<span class="tok-n">xml_text</span><span class="tok-o">&</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-k">operator</span><span class="tok-o">=</span><span class="tok-p">(</span><span class="tok-kt">double</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-n">xml_text</span><span class="tok-o">&</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-k">operator</span><span class="tok-o">=</span><span class="tok-p">(</span><span class="tok-kt">float</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-n">xml_text</span><span class="tok-o">&</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-k">operator</span><span class="tok-o">=</span><span class="tok-p">(</span><span class="tok-kt">bool</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-n">xml_text</span><span class="tok-o">&</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-k">operator</span><span class="tok-o">=</span><span class="tok-p">(</span><span class="tok-kt">long</span> <span class="tok-kt">long</span> <span class="tok-n">rhs</span><span class="tok-p">);</span>
<span class="tok-n">xml_text</span><span class="tok-o">&</span> <span class="tok-n">xml_text</span><span class="tok-o">::</span><span class="tok-k">operator</span><span class="tok-o">=</span><span class="tok-p">(</span><span class="tok-kt">unsigned</span> <span class="tok-kt">long</span> <span class="tok-kt">long</span> <span class="tok-n">rhs</span><span class="tok-p">);</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>These operators simply call the right <code>set</code> function and return the attribute they’re called on; the return value of <code>set</code> is ignored, so errors are ignored.</p>
</div>
<div class="paragraph">
<p>This is an example of using <code>xml_text</code> object to modify text contents (<a href="samples/text.cpp" class="bare">samples/text.cpp</a>):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-c1">// change project version</span>
<span class="tok-n">project</span><span class="tok-p">.</span><span class="tok-n">child</span><span class="tok-p">(</span><span class="tok-s">"version"</span><span class="tok-p">).</span><span class="tok-n">text</span><span class="tok-p">()</span> <span class="tok-o">=</span> <span class="tok-mf">1.2</span><span class="tok-p">;</span>
<span class="tok-c1">// add description element and set the contents</span>
<span class="tok-c1">// note that we do not have to explicitly add the node_pcdata child</span>
<span class="tok-n">project</span><span class="tok-p">.</span><span class="tok-n">append_child</span><span class="tok-p">(</span><span class="tok-s">"description"</span><span class="tok-p">).</span><span class="tok-n">text</span><span class="tok-p">().</span><span class="tok-n">set</span><span class="tok-p">(</span><span class="tok-s">"a test project"</span><span class="tok-p">);</span></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="modify.clone"><a class="anchor" href="#modify.clone"></a><a class="link" href="#modify.clone">6.6. Cloning nodes/attributes</a></h3>
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
<div class="paragraph">
<p><a id="xml_node::prepend_copy"></a><a id="xml_node::append_copy"></a><a id="xml_node::insert_copy_after"></a><a id="xml_node::insert_copy_before"></a>
With the help of previously described functions, it is possible to create trees with any contents and structure, including cloning the existing data. However since this is an often needed operation, pugixml provides built-in node/attribute cloning facilities. Since nodes and attributes do not exist without a document tree, you can’t create a standalone copy - you have to immediately insert it somewhere in the tree. For this, you can use one of the following functions:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c++"><span class="tok-n">xml_attribute</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">append_copy</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-n">xml_attribute</span><span class="tok-o">&</span> <span class="tok-n">proto</span><span class="tok-p">);</span>
<span class="tok-n">xml_attribute</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">prepend_copy</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-n">xml_attribute</span><span class="tok-o">&</span> <span class="tok-n">proto</span><span class="tok-p">);</span>
<span class="tok-n">xml_attribute</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">insert_copy_after</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-n">xml_attribute</span><span class="tok-o">&</span> <span class="tok-n">proto</span><span class="tok-p">,</span> <span class="tok-k">const</span> <span class="tok-n">xml_attribute</span><span class="tok-o">&</span> <span class="tok-n">attr</span><span class="tok-p">);</span>
<span class="tok-n">xml_attribute</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">insert_copy_before</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-n">xml_attribute</span><span class="tok-o">&</span> <span class="tok-n">proto</span><span class="tok-p">,</span> <span class="tok-k">const</span> <span class="tok-n">xml_attribute</span><span class="tok-o">&</span> <span class="tok-n">attr</span><span class="tok-p">);</span>
<span class="tok-n">xml_node</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">append_copy</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-n">xml_node</span><span class="tok-o">&</span> <span class="tok-n">proto</span><span class="tok-p">);</span>
<span class="tok-n">xml_node</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">prepend_copy</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-n">xml_node</span><span class="tok-o">&</span> <span class="tok-n">proto</span><span class="tok-p">);</span>
<span class="tok-n">xml_node</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">insert_copy_after</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-n">xml_node</span><span class="tok-o">&</span> <span class="tok-n">proto</span><span class="tok-p">,</span> <span class="tok-k">const</span> <span class="tok-n">xml_node</span><span class="tok-o">&</span> <span class="tok-n">node</span><span class="tok-p">);</span>
<span class="tok-n">xml_node</span> <span class="tok-n">xml_node</span><span class="tok-o">::</span><span class="tok-n">insert_copy_before</span><span class="tok-p">(</span><span class="tok-k">const</span> <span class="tok-n">xml_node</span><span class="tok-o">&</span> <span class="tok-n">proto</span><span class="tok-p">,</span> <span class="tok-k">const</span> <span class="tok-n">xml_node</span><span class="tok-o">&</span> <span class="tok-n">node</span><span class="tok-p">);</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>These functions mirror the structure of <code>append_child</code>, <code>prepend_child</code>, <code>insert_child_before</code> and related functions - they take the handle to the prototype object, which is to be cloned, insert a new attribute/node at the appropriate place, and then copy the attribute data or the whole node subtree to the new object. The functions return the handle to the resulting duplicate object, or null handle on failure.</p>
</div>
<div class="paragraph">
<p>The attribute is copied along with the name and value; the node is copied along with its type, name and value; additionally attribute list and all children are recursively cloned, resulting in the deep subtree clone. The prototype object can be a part of the same document, or a part of any other document.</p>
</div>
<div class="paragraph">
<p>The failure conditions resemble those of <code>append_child</code>, <code>insert_child_before</code> and related functions, <a href="#xml_node::append_child">consult their documentation for more information</a>. There are additional caveats specific to cloning functions:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Cloning null handles results in operation failure;</p>
</li>
<li>
<p>Node cloning starts with insertion of the node of the same type as that of the prototype; for this reason, cloning functions can not be directly used to clone entire documents, since <a href="#node_document">node_document</a> is not a valid insertion type. The example below provides a workaround.</p>
</li>
<li>
<p>It is possible to copy a subtree as a child of some node inside this subtree, i.e. <code>node.append_copy(node.parent().parent());</code>. This is a valid operation, and it results in a clone of the subtree in the state before cloning started, i.e. no infinite recursion takes place.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>This is an example with one possible implementation of include tags in XML (<a href="samples/include.cpp" class="bare">samples/include.cpp</a>). It illustrates node cloning and usage of other document modification functions:</p>