manual.html

<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">&lt;&lt;</span> <span class="tok-s">&quot;Tool:&quot;</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">&lt;&lt;</span> <span class="tok-s">&quot; &quot;</span> <span class="tok-o">&lt;&lt;</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">&lt;&lt;</span> <span class="tok-s">&quot;=&quot;</span> <span class="tok-o">&lt;&lt;</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">&lt;&lt;</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>5.2. Getting node data</h3>
<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&#8217;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>&lt;node&gt;&lt;description&gt;This is a node&lt;/description&gt;&lt;/node&gt;</code>. In this case, <code>&lt;description&gt;</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>5.3. Getting attribute data</h3>
<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">&quot;&quot;</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 or attribute value is empty, <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>). Any extra characters are silently discarded, i.e. <code>as_int</code> will return <code>1</code> for string <code>"1abc"</code>.</p>
</div>
<div class="paragraph">
<p>In case the input string contains a number that is out of the target numeric range, the result is undefined.</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 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&#8217;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">&quot;Tool&quot;</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">&quot;Tool&quot;</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">&lt;&lt;</span> <span class="tok-s">&quot;Tool &quot;</span> <span class="tok-o">&lt;&lt;</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">&quot;Filename&quot;</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">&lt;&lt;</span> <span class="tok-s">&quot;: AllowRemote &quot;</span> <span class="tok-o">&lt;&lt;</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">&quot;AllowRemote&quot;</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">&lt;&lt;</span> <span class="tok-s">&quot;, Timeout &quot;</span> <span class="tok-o">&lt;&lt;</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">&quot;Timeout&quot;</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">&lt;&lt;</span> <span class="tok-s">&quot;, Description &#39;&quot;</span> <span class="tok-o">&lt;&lt;</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">&quot;Description&quot;</span><span class="tok-p">)</span> <span class="tok-o">&lt;&lt;</span> <span class="tok-s">&quot;&#39;</span><span class="tok-se">\n</span><span class="tok-s">&quot;</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>5.4. Contents-based traversal functions</h3>
<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">&quot;Tool&quot;</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">&quot;Tool&quot;</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>&lt;group&gt;&lt;item id="1"/&gt; &lt;item id="2"/&gt;&lt;/group&gt;</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">&lt;&lt;</span> <span class="tok-s">&quot;Tool for *.dae generation: &quot;</span> <span class="tok-o">&lt;&lt;</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">&quot;Tool&quot;</span><span class="tok-p">,</span> <span class="tok-s">&quot;OutputFileMasks&quot;</span><span class="tok-p">,</span> <span class="tok-s">&quot;*.dae&quot;</span><span class="tok-p">).</span><span class="tok-n">attribute</span><span class="tok-p">(</span><span class="tok-s">&quot;Filename&quot;</span><span class="tok-p">).</span><span class="tok-n">value</span><span class="tok-p">()</span> <span class="tok-o">&lt;&lt;</span> <span class="tok-s">&quot;</span><span class="tok-se">\n</span><span class="tok-s">&quot;</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">&quot;Tool&quot;</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">&quot;Tool&quot;</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">&lt;&lt;</span> <span class="tok-s">&quot;Tool &quot;</span> <span class="tok-o">&lt;&lt;</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">&quot;Filename&quot;</span><span class="tok-p">).</span><span class="tok-n">value</span><span class="tok-p">()</span> <span class="tok-o">&lt;&lt;</span> <span class="tok-s">&quot;</span><span class="tok-se">\n</span><span class="tok-s">&quot;</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>5.5. Range-based for-loop support</h3>
<div class="paragraph">
<p><a id="xml_node::children"></a><a id="xml_node::attributes"></a>
If your C&#43;&#43; compiler supports range-based for-loop (this is a C&#43;&#43;11 feature, at the time of writing it&#8217;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&#43;&#43;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">&quot;Tool&quot;</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">&lt;&lt;</span> <span class="tok-s">&quot;Tool:&quot;</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">&lt;&lt;</span> <span class="tok-s">&quot; &quot;</span> <span class="tok-o">&lt;&lt;</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">&lt;&lt;</span> <span class="tok-s">&quot;=&quot;</span> <span class="tok-o">&lt;&lt;</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">&lt;&lt;</span> <span class="tok-s">&quot;, child &quot;</span> <span class="tok-o">&lt;&lt;</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">&lt;&lt;</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>5.6. Traversing node/attribute lists via iterators</h3>
<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&#8217;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&#8217;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&#8217;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&#8217;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">&lt;&lt;</span> <span class="tok-s">&quot;Tool:&quot;</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">-&gt;</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">-&gt;</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">&lt;&lt;</span> <span class="tok-s">&quot; &quot;</span> <span class="tok-o">&lt;&lt;</span> <span class="tok-n">ait</span><span class="tok-o">-&gt;</span><span class="tok-n">name</span><span class="tok-p">()</span> <span class="tok-o">&lt;&lt;</span> <span class="tok-s">&quot;=&quot;</span> <span class="tok-o">&lt;&lt;</span> <span class="tok-n">ait</span><span class="tok-o">-&gt;</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">&lt;&lt;</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&#8217;s stored in the iterator.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="access.walker"><a class="anchor" href="#access.walker"></a>5.7. Recursive traversal with xml_tree_walker</h3>
<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&#8217;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">&amp;</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">&amp;</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">&amp;</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">&amp;</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&#8217;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&#8217;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">&amp;</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">&lt;</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">&lt;&lt;</span> <span class="tok-s">&quot;  &quot;</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">&lt;&lt;</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">&lt;&lt;</span> <span class="tok-s">&quot;: name=&#39;&quot;</span> <span class="tok-o">&lt;&lt;</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">&lt;&lt;</span> <span class="tok-s">&quot;&#39;, value=&#39;&quot;</span> <span class="tok-o">&lt;&lt;</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">&lt;&lt;</span> <span class="tok-s">&quot;&#39;</span><span class="tok-se">\n</span><span class="tok-s">&quot;</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>5.8. Searching for nodes/attributes with predicates</h3>
<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">&lt;</span><span class="tok-k">typename</span> <span class="tok-n">Predicate</span><span class="tok-o">&gt;</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">&lt;</span><span class="tok-k">typename</span> <span class="tok-n">Predicate</span><span class="tok-o">&gt;</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">&lt;</span><span class="tok-k">typename</span> <span class="tok-n">Predicate</span><span class="tok-o">&gt;</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">&quot;Timeout&quot;</span><span class="tok-p">).</span><span class="tok-n">as_int</span><span class="tok-p">()</span> <span class="tok-o">&lt;</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">&quot;AllowRemote&quot;</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">&quot;AllowRemote&quot;</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">&lt;&lt;</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">&quot;Filename&quot;</span><span class="tok-p">).</span><span class="tok-n">value</span><span class="tok-p">()</span> <span class="tok-o">&lt;&lt;</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">&lt;&lt;</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">&quot;Filename&quot;</span><span class="tok-p">).</span><span class="tok-n">value</span><span class="tok-p">()</span> <span class="tok-o">&lt;&lt;</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">&lt;&lt;</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">&lt;&lt;</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">&lt;&lt;</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">&quot;Filename&quot;</span><span class="tok-p">).</span><span class="tok-n">value</span><span class="tok-p">()</span> <span class="tok-o">&lt;&lt;</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>5.9. Working with text contents</h3>
<div id="xml_text" class="paragraph">
<p>It is common to store data as text contents of some node - i.e. <code>&lt;node&gt;&lt;description&gt;This is a node&lt;/description&gt;&lt;/node&gt;</code>. In this case, <code>&lt;description&gt;</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) { &#8230;&#8203; }</code> or <code>if (!text) { &#8230;&#8203; }</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">&quot;&quot;</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">&lt;&lt;</span> <span class="tok-s">&quot;Project name: &quot;</span> <span class="tok-o">&lt;&lt;</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">&quot;name&quot;</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">&lt;&lt;</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">&lt;&lt;</span> <span class="tok-s">&quot;Project version: &quot;</span> <span class="tok-o">&lt;&lt;</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">&quot;version&quot;</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">&lt;&lt;</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">&lt;&lt;</span> <span class="tok-s">&quot;Project visibility: &quot;</span> <span class="tok-o">&lt;&lt;</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">&quot;public&quot;</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">&quot;public&quot;</span> <span class="tok-o">:</span> <span class="tok-s">&quot;private&quot;</span><span class="tok-p">)</span> <span class="tok-o">&lt;&lt;</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">&lt;&lt;</span> <span class="tok-s">&quot;Project description: &quot;</span> <span class="tok-o">&lt;&lt;</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">&quot;description&quot;</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">&lt;&lt;</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>5.10. Miscellaneous functions</h3>
<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">&#39;/&#39;</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">&#39;/&#39;</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>&lt;a&gt;&lt;b&gt;&lt;c/&gt;&lt;/b&gt;&lt;/a&gt;</code>, node <code>&lt;c/&gt;</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>&lt;b/&gt;</code>; calling <code>first_element_by_path</code> for node <code>&lt;a/&gt;</code> with path <code>"../a/./b/../."</code> results in node <code>&lt;a/&gt;</code>; calling <code>first_element_by_path</code> with path <code>"/a"</code> results in node <code>&lt;a/&gt;</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&#8217;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>6. Modifying document data</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&amp; 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>6.1. Setting node data</h3>
<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&#8217;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">&quot;node&quot;</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">&lt;&lt;</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">&quot;notnode&quot;</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">&lt;&lt;</span> <span class="tok-s">&quot;, new node name: &quot;</span> <span class="tok-o">&lt;&lt;</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">&lt;&lt;</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">&lt;&lt;</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">&quot;useless comment&quot;</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">&lt;&lt;</span> <span class="tok-s">&quot;, new comment text: &quot;</span> <span class="tok-o">&lt;&lt;</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">&lt;&lt;</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&#39;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">&lt;&lt;</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">&quot;1&quot;</span><span class="tok-p">)</span> <span class="tok-o">&lt;&lt;</span> <span class="tok-s">&quot;, &quot;</span> <span class="tok-o">&lt;&lt;</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">&quot;2&quot;</span><span class="tok-p">)</span> <span class="tok-o">&lt;&lt;</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>6.2. Setting attribute data</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">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">&amp;</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">&amp;</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">&amp;</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">&amp;</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">&amp;</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">&amp;</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">&amp;</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">&amp;</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&#8217;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">&quot;id&quot;</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">&lt;&lt;</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">&quot;key&quot;</span><span class="tok-p">)</span> <span class="tok-o">&lt;&lt;</span> <span class="tok-s">&quot;, &quot;</span> <span class="tok-o">&lt;&lt;</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">&quot;345&quot;</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">&lt;&lt;</span> <span class="tok-s">&quot;, new attribute: &quot;</span> <span class="tok-o">&lt;&lt;</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">&lt;&lt;</span> <span class="tok-s">&quot;=&quot;</span> <span class="tok-o">&lt;&lt;</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">&lt;&lt;</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">&lt;&lt;</span> <span class="tok-s">&quot;new attribute value: &quot;</span> <span class="tok-o">&lt;&lt;</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">&lt;&lt;</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">&lt;&lt;</span> <span class="tok-s">&quot;final attribute value: &quot;</span> <span class="tok-o">&lt;&lt;</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">&lt;&lt;</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>6.3. Adding nodes/attributes</h3>
<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&#8217;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">&amp;</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">&amp;</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">&amp;</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">&amp;</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">&amp;</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">&amp;</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&#8217;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&#8217;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&#8217;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">&quot;node&quot;</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">&quot;description&quot;</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">&quot;Simple node&quot;</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">&quot;param&quot;</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">&quot;name&quot;</span><span class="tok-p">)</span> <span class="tok-o">=</span> <span class="tok-s">&quot;version&quot;</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">&quot;value&quot;</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">&quot;type&quot;</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">&quot;name&quot;</span><span class="tok-p">))</span> <span class="tok-o">=</span> <span class="tok-s">&quot;float&quot;</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>6.4. Removing nodes/attributes</h3>
<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">&amp;</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">&amp;</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&#8217;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">&quot;node&quot;</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">&quot;description&quot;</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">&quot;param&quot;</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">&quot;value&quot;</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">&quot;name&quot;</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>6.5. Working with text contents</h3>
<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>&lt;node&gt;&lt;description&gt;This is a node&lt;/description&gt;&lt;/node&gt;</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">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">&amp;</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">&amp;</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">&amp;</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">&amp;</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">&amp;</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">&amp;</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">&amp;</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">&amp;</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&#8217;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">&quot;version&quot;</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">&quot;description&quot;</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">&quot;a test project&quot;</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>6.6. Cloning nodes/attributes</h3>
<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&#8217;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">&amp;</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">&amp;</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">&amp;</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">&amp;</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">&amp;</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">&amp;</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">&amp;</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">&amp;</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">&amp;</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">&amp;</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">&amp;</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">&amp;</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>
</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">load_preprocess</span><span class="tok-p">(</span><span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_document</span><span class="tok-o">&amp;</span> <span class="tok-n">doc</span><span class="tok-p">,</span> <span class="tok-k">const</span> <span class="tok-kt">char</span><span class="tok-o">*</span> <span class="tok-n">path</span><span class="tok-p">);</span>

<span class="tok-kt">bool</span> <span class="tok-nf">preprocess</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">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">child</span> <span class="tok-o">=</span> <span class="tok-n">node</span><span class="tok-p">.</span><span class="tok-n">first_child</span><span class="tok-p">();</span> <span class="tok-n">child</span><span class="tok-p">;</span> <span class="tok-p">)</span>
    <span class="tok-p">{</span>
        <span class="tok-k">if</span> <span class="tok-p">(</span><span class="tok-n">child</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-n">pugi</span><span class="tok-o">::</span><span class="tok-n">node_pi</span> <span class="tok-o">&amp;&amp;</span> <span class="tok-n">strcmp</span><span class="tok-p">(</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-s">&quot;include&quot;</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-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_node</span> <span class="tok-n">include</span> <span class="tok-o">=</span> <span class="tok-n">child</span><span class="tok-p">;</span>

            <span class="tok-c1">// load new preprocessed document (note: ideally this should handle relative paths)</span>
            <span class="tok-k">const</span> <span class="tok-kt">char</span><span class="tok-o">*</span> <span class="tok-n">path</span> <span class="tok-o">=</span> <span class="tok-n">include</span><span class="tok-p">.</span><span class="tok-n">value</span><span class="tok-p">();</span>

            <span class="tok-n">pugi</span><span class="tok-o">::</span><span class="tok-n">xml_document</span> <span class="tok-n">doc</span><span class="tok-p">;</span>
            <span class="tok-k">if</span> <span class="tok-p">(</span><span class="tok-o">!</span><span class="tok-n">load_preprocess</span><span class="tok-p">(</span><span class="tok-n">doc</span><span class="tok-p">,</span> <span class="tok-n">path</span><span class="tok-p">))</span> <span class="tok-k">return</span> <span class="tok-nb">false</span><span class="tok-p">;</span>

            <span class="tok-c1">// insert the comment marker above include directive</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-n">pugi</span><span class="tok-o">::</span><span class="tok-n">node_comment</span><span class="tok-p">,</span> <span class="tok-n">include</span><span class="tok-p">).</span><span class="tok-n">set_value</span><span class="tok-p">(</span><span class="tok-n">path</span><span class="tok-p">);</span>