summaryrefslogtreecommitdiff
path: root/docs/manual/access.html
diff options
context:
space:
mode:
Diffstat (limited to 'docs/manual/access.html')
-rw-r--r--docs/manual/access.html900
1 files changed, 0 insertions, 900 deletions
diff --git a/docs/manual/access.html b/docs/manual/access.html
deleted file mode 100644
index 8942a26..0000000
--- a/docs/manual/access.html
+++ /dev/null
@@ -1,900 +0,0 @@
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
-<title>Accessing document data</title>
-<link rel="stylesheet" href="../pugixml.css" type="text/css">
-<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
-<link rel="home" href="../manual.html" title="pugixml 1.5">
-<link rel="up" href="../manual.html" title="pugixml 1.5">
-<link rel="prev" href="loading.html" title="Loading document">
-<link rel="next" href="modify.html" title="Modifying document data">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<table width="100%"><tr>
-<td>
-<a href="http://pugixml.org/">pugixml 1.5</a> manual |
- <a href="../manual.html">Overview</a> |
- <a href="install.html">Installation</a> |
- Document:
- <a href="dom.html">Object model</a> &middot; <a href="loading.html">Loading</a> &middot; <b>Accessing</b> &middot; <a href="modify.html">Modifying</a> &middot; <a href="saving.html">Saving</a> |
- <a href="xpath.html">XPath</a> |
- <a href="apiref.html">API Reference</a> |
- <a href="toc.html">Table of Contents</a>
-</td>
-<td width="*" align="right"><div class="spirit-nav">
-<a accesskey="p" href="loading.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../manual.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../manual.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="modify.html"><img src="../images/next.png" alt="Next"></a>
-</div></td>
-</tr></table>
-<hr>
-<div class="section">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="manual.access"></a><a class="link" href="access.html" title="Accessing document data"> Accessing document data</a>
-</h2></div></div></div>
-<div class="toc"><dl class="toc">
-<dt><span class="section"><a href="access.html#manual.access.basic"> Basic traversal functions</a></span></dt>
-<dt><span class="section"><a href="access.html#manual.access.nodedata"> Getting node data</a></span></dt>
-<dt><span class="section"><a href="access.html#manual.access.attrdata"> Getting attribute data</a></span></dt>
-<dt><span class="section"><a href="access.html#manual.access.contents"> Contents-based traversal functions</a></span></dt>
-<dt><span class="section"><a href="access.html#manual.access.rangefor"> Range-based for-loop support</a></span></dt>
-<dt><span class="section"><a href="access.html#manual.access.iterators"> Traversing node/attribute lists
- via iterators</a></span></dt>
-<dt><span class="section"><a href="access.html#manual.access.walker"> Recursive traversal with xml_tree_walker</a></span></dt>
-<dt><span class="section"><a href="access.html#manual.access.predicate"> Searching for nodes/attributes
- with predicates</a></span></dt>
-<dt><span class="section"><a href="access.html#manual.access.text"> Working with text contents</a></span></dt>
-<dt><span class="section"><a href="access.html#manual.access.misc"> Miscellaneous functions</a></span></dt>
-</dl></div>
-<p>
- pugixml features an extensive interface for getting various types of data from
- the document and for traversing the document. This section provides documentation
- for all such functions that do not modify the tree except for XPath-related
- functions; see <a class="xref" href="xpath.html" title="XPath"> XPath</a> for XPath reference. As discussed in <a class="xref" href="dom.html#manual.dom.cpp" title="C++ interface"> C++ interface</a>,
- there are two types of handles to tree data - <a class="link" href="dom.html#xml_node">xml_node</a>
- and <a class="link" href="dom.html#xml_attribute">xml_attribute</a>. The handles have special
- null (empty) values which propagate through various functions and thus are
- useful for writing more concise code; see <a class="link" href="dom.html#node_null">this description</a>
- for details. The documentation in this section will explicitly state the results
- of all function in case of null inputs.
- </p>
-<div class="section">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.access.basic"></a><a class="link" href="access.html#manual.access.basic" title="Basic traversal functions"> Basic traversal functions</a>
-</h3></div></div></div>
-<a name="xml_node::parent"></a><a name="xml_node::first_child"></a><a name="xml_node::last_child"></a><a name="xml_node::next_sibling"></a><a name="xml_node::previous_sibling"></a><a name="xml_node::first_attribute"></a><a name="xml_node::last_attribute"></a><a name="xml_attribute::next_attribute"></a><a name="xml_attribute::previous_attribute"></a><p>
- The internal representation of the document is a tree, where each node has
- a list of child nodes (the order of children corresponds to their order in
- the XML representation), and additionally element nodes have a list of attributes,
- which is also ordered. Several functions are provided in order to let you
- get from one node in the tree to the other. These functions roughly correspond
- to the internal representation, and thus are usually building blocks for
- other methods of traversing (i.e. XPath traversals are based on these functions).
- </p>
-<pre class="programlisting"><span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">parent</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">first_child</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">last_child</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">next_sibling</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">previous_sibling</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-
-<span class="identifier">xml_attribute</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">first_attribute</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="identifier">xml_attribute</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">last_attribute</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="identifier">xml_attribute</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">next_attribute</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="identifier">xml_attribute</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">previous_attribute</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- <code class="computeroutput"><span class="identifier">parent</span></code> function returns the
- node's parent; all non-null nodes except the document have non-null parent.
- <code class="computeroutput"><span class="identifier">first_child</span></code> and <code class="computeroutput"><span class="identifier">last_child</span></code> return the first and last child
- of the node, respectively; note that only document nodes and element nodes
- can have non-empty child node list. If node has no children, both functions
- return null nodes. <code class="computeroutput"><span class="identifier">next_sibling</span></code>
- and <code class="computeroutput"><span class="identifier">previous_sibling</span></code> return
- the node that's immediately to the right/left of this node in the children
- list, respectively - for example, in <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">a</span><span class="special">/&gt;&lt;</span><span class="identifier">b</span><span class="special">/&gt;&lt;</span><span class="identifier">c</span><span class="special">/&gt;</span></code>,
- calling <code class="computeroutput"><span class="identifier">next_sibling</span></code> for
- a handle that points to <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">b</span><span class="special">/&gt;</span></code>
- results in a handle pointing to <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">c</span><span class="special">/&gt;</span></code>,
- and calling <code class="computeroutput"><span class="identifier">previous_sibling</span></code>
- results in handle pointing to <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">a</span><span class="special">/&gt;</span></code>.
- If node does not have next/previous sibling (this happens if it is the last/first
- node in the list, respectively), the functions return null nodes. <code class="computeroutput"><span class="identifier">first_attribute</span></code>, <code class="computeroutput"><span class="identifier">last_attribute</span></code>,
- <code class="computeroutput"><span class="identifier">next_attribute</span></code> and <code class="computeroutput"><span class="identifier">previous_attribute</span></code> functions behave similarly
- to the corresponding child node functions and allow to iterate through attribute
- list in the same way.
- </p>
-<div class="note"><table border="0" summary="Note">
-<tr>
-<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
-<th align="left">Note</th>
-</tr>
-<tr><td align="left" valign="top"><p>
- Because of memory consumption reasons, attributes do not have a link to
- their parent nodes. Thus there is no <code class="computeroutput"><span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">parent</span><span class="special">()</span></code> function.
- </p></td></tr>
-</table></div>
-<p>
- Calling any of the functions above on the null handle results in a null handle
- - i.e. <code class="computeroutput"><span class="identifier">node</span><span class="special">.</span><span class="identifier">first_child</span><span class="special">().</span><span class="identifier">next_sibling</span><span class="special">()</span></code>
- returns the second child of <code class="computeroutput"><span class="identifier">node</span></code>,
- and null handle if <code class="computeroutput"><span class="identifier">node</span></code> is
- null, has no children at all or if it has only one child node.
- </p>
-<p>
- With these functions, you can iterate through all child nodes and display
- all attributes like this (<a href="../samples/traverse_base.cpp" target="_top">samples/traverse_base.cpp</a>):
- </p>
-<p>
-
-</p>
-<pre class="programlisting"><span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">tool</span> <span class="special">=</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">first_child</span><span class="special">();</span> <span class="identifier">tool</span><span class="special">;</span> <span class="identifier">tool</span> <span class="special">=</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">next_sibling</span><span class="special">())</span>
-<span class="special">{</span>
- <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Tool:"</span><span class="special">;</span>
-
- <span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_attribute</span> <span class="identifier">attr</span> <span class="special">=</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">first_attribute</span><span class="special">();</span> <span class="identifier">attr</span><span class="special">;</span> <span class="identifier">attr</span> <span class="special">=</span> <span class="identifier">attr</span><span class="special">.</span><span class="identifier">next_attribute</span><span class="special">())</span>
- <span class="special">{</span>
- <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span> <span class="special">&lt;&lt;</span> <span class="identifier">attr</span><span class="special">.</span><span class="identifier">name</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">"="</span> <span class="special">&lt;&lt;</span> <span class="identifier">attr</span><span class="special">.</span><span class="identifier">value</span><span class="special">();</span>
- <span class="special">}</span>
-
- <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
-<span class="special">}</span>
-</pre>
-<p>
- </p>
-</div>
-<div class="section">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.access.nodedata"></a><a class="link" href="access.html#manual.access.nodedata" title="Getting node data"> Getting node data</a>
-</h3></div></div></div>
-<a name="xml_node::name"></a><a name="xml_node::value"></a><p>
- 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 class="link" href="dom.html#node_document">node_document</a>
- nodes do not have a name or value, <a class="link" href="dom.html#node_element">node_element</a>
- and <a class="link" href="dom.html#node_declaration">node_declaration</a> nodes always
- have a name but never have a value, <a class="link" href="dom.html#node_pcdata">node_pcdata</a>,
- <a class="link" href="dom.html#node_cdata">node_cdata</a>, <a class="link" href="dom.html#node_comment">node_comment</a>
- and <a class="link" href="dom.html#node_doctype">node_doctype</a> nodes never have a name
- but always have a value (it may be empty though), <a class="link" href="dom.html#node_pi">node_pi</a>
- nodes always have a name and a value (again, value may be empty). In order
- to get node's name or value, you can use the following functions:
- </p>
-<pre class="programlisting"><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">name</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">value</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<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>
-<a name="xml_node::child_value"></a><p>
- It is common to store data as text contents of some node - i.e. <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">node</span><span class="special">&gt;&lt;</span><span class="identifier">description</span><span class="special">&gt;</span><span class="identifier">This</span> <span class="identifier">is</span> <span class="identifier">a</span> <span class="identifier">node</span><span class="special">&lt;/</span><span class="identifier">description</span><span class="special">&gt;&lt;/</span><span class="identifier">node</span><span class="special">&gt;</span></code>.
- In this case, <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">description</span><span class="special">&gt;</span></code> node does not have a value, but instead
- has a child of type <a class="link" href="dom.html#node_pcdata">node_pcdata</a> with value
- <code class="computeroutput"><span class="string">"This is a node"</span></code>. pugixml
- provides several helper functions to parse such data:
- </p>
-<pre class="programlisting"><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">child_value</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">child_value</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">name</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="identifier">xml_text</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">text</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- <code class="computeroutput"><span class="identifier">child_value</span><span class="special">()</span></code>
- returns the value of the first child with type <a class="link" href="dom.html#node_pcdata">node_pcdata</a>
- or <a class="link" href="dom.html#node_cdata">node_cdata</a>; <code class="computeroutput"><span class="identifier">child_value</span><span class="special">(</span><span class="identifier">name</span><span class="special">)</span></code>
- is a simple wrapper for <code class="computeroutput"><span class="identifier">child</span><span class="special">(</span><span class="identifier">name</span><span class="special">).</span><span class="identifier">child_value</span><span class="special">()</span></code>.
- For the above example, calling <code class="computeroutput"><span class="identifier">node</span><span class="special">.</span><span class="identifier">child_value</span><span class="special">(</span><span class="string">"description"</span><span class="special">)</span></code> and <code class="computeroutput"><span class="identifier">description</span><span class="special">.</span><span class="identifier">child_value</span><span class="special">()</span></code> will both produce string <code class="computeroutput"><span class="string">"This is a node"</span></code>. If there is no
- child with relevant type, or if the handle is null, <code class="computeroutput"><span class="identifier">child_value</span></code>
- functions return empty string.
- </p>
-<p>
- <code class="computeroutput"><span class="identifier">text</span><span class="special">()</span></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 class="xref" href="access.html#manual.access.text" title="Working with text contents"> Working with text contents</a> sections.
- </p>
-<p>
- There is an example of using some of these functions <a class="link" href="access.html#code_traverse_base_data">at
- the end of the next section</a>.
- </p>
-</div>
-<div class="section">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.access.attrdata"></a><a class="link" href="access.html#manual.access.attrdata" title="Getting attribute data"> Getting attribute data</a>
-</h3></div></div></div>
-<a name="xml_attribute::name"></a><a name="xml_attribute::value"></a><p>
- All attributes have name and value, both of which are strings (value may
- be empty). There are two corresponding accessors, like for <code class="computeroutput"><span class="identifier">xml_node</span></code>:
- </p>
-<pre class="programlisting"><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">name</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">value</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- In case the attribute handle is null, both functions return empty strings
- - they never return null pointers.
- </p>
-<a name="xml_attribute::as_string"></a><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 class="computeroutput"><span class="string">"sorted"</span></code>
- instead of <code class="computeroutput"><span class="string">""</span></code>), you
- can use <code class="computeroutput"><span class="identifier">as_string</span></code> accessor:
- </p>
-<pre class="programlisting"><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">as_string</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">def</span> <span class="special">=</span> <span class="string">""</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- It returns <code class="computeroutput"><span class="identifier">def</span></code> argument if
- the attribute handle is null. If you do not specify the argument, the function
- is equivalent to <code class="computeroutput"><span class="identifier">value</span><span class="special">()</span></code>.
- </p>
-<a name="xml_attribute::as_int"></a><a name="xml_attribute::as_uint"></a><a name="xml_attribute::as_double"></a><a name="xml_attribute::as_float"></a><a name="xml_attribute::as_bool"></a><a name="xml_attribute::as_llong"></a><a name="xml_attribute::as_ullong"></a><p>
- 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>
-<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">as_int</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">def</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">as_uint</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">def</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="keyword">double</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">as_double</span><span class="special">(</span><span class="keyword">double</span> <span class="identifier">def</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="keyword">float</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">as_float</span><span class="special">(</span><span class="keyword">float</span> <span class="identifier">def</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="keyword">bool</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">as_bool</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">def</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="keyword">long</span> <span class="keyword">long</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">as_llong</span><span class="special">(</span><span class="keyword">long</span> <span class="keyword">long</span> <span class="identifier">def</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="keyword">unsigned</span> <span class="keyword">long</span> <span class="keyword">long</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">as_ullong</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="keyword">long</span> <span class="keyword">long</span> <span class="identifier">def</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- <code class="computeroutput"><span class="identifier">as_int</span></code>, <code class="computeroutput"><span class="identifier">as_uint</span></code>,
- <code class="computeroutput"><span class="identifier">as_llong</span></code>, <code class="computeroutput"><span class="identifier">as_ullong</span></code>,
- <code class="computeroutput"><span class="identifier">as_double</span></code> and <code class="computeroutput"><span class="identifier">as_float</span></code> convert attribute values to numbers.
- If attribute handle is null or attribute value is empty, <code class="computeroutput"><span class="identifier">def</span></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 class="computeroutput"><span class="identifier">as_int</span></code>, <code class="computeroutput"><span class="identifier">as_uint</span></code>,
- <code class="computeroutput"><span class="identifier">as_llong</span></code> and <code class="computeroutput"><span class="identifier">as_ullong</span></code>; hexadecimal format is used if
- the number has <code class="computeroutput"><span class="number">0</span><span class="identifier">x</span></code>
- or <code class="computeroutput"><span class="number">0</span><span class="identifier">X</span></code>
- prefix) or as a floating point number in either decimal or scientific form
- (<code class="computeroutput"><span class="identifier">as_double</span></code> or <code class="computeroutput"><span class="identifier">as_float</span></code>). Any extra characters are silently
- discarded, i.e. <code class="computeroutput"><span class="identifier">as_int</span></code> will
- return <code class="computeroutput"><span class="number">1</span></code> for string <code class="computeroutput"><span class="string">"1abc"</span></code>.
- </p>
-<p>
- In case the input string contains a number that is out of the target numeric
- range, the result is undefined.
- </p>
-<div class="caution"><table border="0" summary="Caution">
-<tr>
-<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../images/caution.png"></td>
-<th align="left">Caution</th>
-</tr>
-<tr><td align="left" valign="top"><p>
- Number conversion functions depend on current C locale as set with <code class="computeroutput"><span class="identifier">setlocale</span></code>, so may return unexpected results
- if the locale is different from <code class="computeroutput"><span class="string">"C"</span></code>.
- </p></td></tr>
-</table></div>
-<p>
- <code class="computeroutput"><span class="identifier">as_bool</span></code> converts attribute
- value to boolean as follows: if attribute handle is null, <code class="computeroutput"><span class="identifier">def</span></code>
- argument is returned (which is <code class="computeroutput"><span class="keyword">false</span></code>
- by default). If attribute value is empty, <code class="computeroutput"><span class="keyword">false</span></code>
- is returned. Otherwise, <code class="computeroutput"><span class="keyword">true</span></code>
- is returned if the first character is one of <code class="computeroutput"><span class="char">'1'</span><span class="special">,</span> <span class="char">'t'</span><span class="special">,</span>
- <span class="char">'T'</span><span class="special">,</span> <span class="char">'y'</span><span class="special">,</span> <span class="char">'Y'</span></code>.
- This means that strings like <code class="computeroutput"><span class="string">"true"</span></code>
- and <code class="computeroutput"><span class="string">"yes"</span></code> are recognized
- as <code class="computeroutput"><span class="keyword">true</span></code>, while strings like
- <code class="computeroutput"><span class="string">"false"</span></code> and <code class="computeroutput"><span class="string">"no"</span></code> are recognized as <code class="computeroutput"><span class="keyword">false</span></code>. For more complex matching you'll have
- to write your own function.
- </p>
-<div class="note"><table border="0" summary="Note">
-<tr>
-<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
-<th align="left">Note</th>
-</tr>
-<tr><td align="left" valign="top"><p>
- <code class="computeroutput"><span class="identifier">as_llong</span></code> and <code class="computeroutput"><span class="identifier">as_ullong</span></code> are only available if your
- platform has reliable support for the <code class="computeroutput"><span class="keyword">long</span>
- <span class="keyword">long</span></code> type, including string conversions.
- </p></td></tr>
-</table></div>
-<a name="code_traverse_base_data"></a><p>
- This is an example of using these functions, along with node data retrieval
- ones (<a href="../samples/traverse_base.cpp" target="_top">samples/traverse_base.cpp</a>):
- </p>
-<p>
-
-</p>
-<pre class="programlisting"><span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">tool</span> <span class="special">=</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">child</span><span class="special">(</span><span class="string">"Tool"</span><span class="special">);</span> <span class="identifier">tool</span><span class="special">;</span> <span class="identifier">tool</span> <span class="special">=</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">next_sibling</span><span class="special">(</span><span class="string">"Tool"</span><span class="special">))</span>
-<span class="special">{</span>
- <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Tool "</span> <span class="special">&lt;&lt;</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"Filename"</span><span class="special">).</span><span class="identifier">value</span><span class="special">();</span>
- <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">": AllowRemote "</span> <span class="special">&lt;&lt;</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"AllowRemote"</span><span class="special">).</span><span class="identifier">as_bool</span><span class="special">();</span>
- <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">", Timeout "</span> <span class="special">&lt;&lt;</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"Timeout"</span><span class="special">).</span><span class="identifier">as_int</span><span class="special">();</span>
- <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">", Description '"</span> <span class="special">&lt;&lt;</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">child_value</span><span class="special">(</span><span class="string">"Description"</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"'\n"</span><span class="special">;</span>
-<span class="special">}</span>
-</pre>
-<p>
- </p>
-</div>
-<div class="section">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.access.contents"></a><a class="link" href="access.html#manual.access.contents" title="Contents-based traversal functions"> Contents-based traversal functions</a>
-</h3></div></div></div>
-<a name="xml_node::child"></a><a name="xml_node::attribute"></a><a name="xml_node::next_sibling_name"></a><a name="xml_node::previous_sibling_name"></a><p>
- Since a lot of document traversal consists of finding the node/attribute
- with the correct name, there are special functions for that purpose:
- </p>
-<pre class="programlisting"><span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">child</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">name</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="identifier">xml_attribute</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">attribute</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">name</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">next_sibling</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">name</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">previous_sibling</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">name</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- <code class="computeroutput"><span class="identifier">child</span></code> and <code class="computeroutput"><span class="identifier">attribute</span></code>
- return the first child/attribute with the specified name; <code class="computeroutput"><span class="identifier">next_sibling</span></code>
- and <code class="computeroutput"><span class="identifier">previous_sibling</span></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>
-<p>
- <code class="computeroutput"><span class="identifier">child</span></code> and <code class="computeroutput"><span class="identifier">next_sibling</span></code>
- functions can be used together to loop through all child nodes with the desired
- name like this:
- </p>
-<pre class="programlisting"><span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">tool</span> <span class="special">=</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">child</span><span class="special">(</span><span class="string">"Tool"</span><span class="special">);</span> <span class="identifier">tool</span><span class="special">;</span> <span class="identifier">tool</span> <span class="special">=</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">next_sibling</span><span class="special">(</span><span class="string">"Tool"</span><span class="special">))</span>
-</pre>
-<a name="xml_node::find_child_by_attribute"></a><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 class="computeroutput"><span class="special">&lt;</span><span class="identifier">group</span><span class="special">&gt;&lt;</span><span class="identifier">item</span> <span class="identifier">id</span><span class="special">=</span><span class="string">"1"</span><span class="special">/&gt;</span> <span class="special">&lt;</span><span class="identifier">item</span> <span class="identifier">id</span><span class="special">=</span><span class="string">"2"</span><span class="special">/&gt;&lt;/</span><span class="identifier">group</span><span class="special">&gt;</span></code>. There are two functions for finding
- child nodes based on the attribute values:
- </p>
-<pre class="programlisting"><span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">find_child_by_attribute</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">attr_name</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">attr_value</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">find_child_by_attribute</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">attr_name</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">attr_value</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<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>
-<p>
- In all of the above functions, all arguments have to be valid strings; passing
- null pointers results in undefined behavior.
- </p>
-<p>
- This is an example of using these functions (<a href="../samples/traverse_base.cpp" target="_top">samples/traverse_base.cpp</a>):
- </p>
-<p>
-
-</p>
-<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Tool for *.dae generation: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">find_child_by_attribute</span><span class="special">(</span><span class="string">"Tool"</span><span class="special">,</span> <span class="string">"OutputFileMasks"</span><span class="special">,</span> <span class="string">"*.dae"</span><span class="special">).</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"Filename"</span><span class="special">).</span><span class="identifier">value</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
-
-<span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">tool</span> <span class="special">=</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">child</span><span class="special">(</span><span class="string">"Tool"</span><span class="special">);</span> <span class="identifier">tool</span><span class="special">;</span> <span class="identifier">tool</span> <span class="special">=</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">next_sibling</span><span class="special">(</span><span class="string">"Tool"</span><span class="special">))</span>
-<span class="special">{</span>
- <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Tool "</span> <span class="special">&lt;&lt;</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"Filename"</span><span class="special">).</span><span class="identifier">value</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
-<span class="special">}</span>
-</pre>
-<p>
- </p>
-</div>
-<div class="section">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.access.rangefor"></a><a class="link" href="access.html#manual.access.rangefor" title="Range-based for-loop support"> Range-based for-loop support</a>
-</h3></div></div></div>
-<a name="xml_node::children"></a><a name="xml_node::attributes"></a><p>
- If your C++ compiler supports range-based for-loop (this is a C++11 feature,
- at the time of writing it's supported by Microsoft Visual Studio 11 Beta,
- 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/" target="_top">Boost Foreach</a>,
- and possibly other pre-C++11 foreach facilities.
- </p>
-<pre class="programlisting"><span class="emphasis"><em>implementation-defined type</em></span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">children</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="emphasis"><em>implementation-defined type</em></span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">children</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">name</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="emphasis"><em>implementation-defined type</em></span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">attributes</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- <code class="computeroutput"><span class="identifier">children</span></code> function allows
- you to enumerate all child nodes; <code class="computeroutput"><span class="identifier">children</span></code>
- function with <code class="computeroutput"><span class="identifier">name</span></code> argument
- allows you to enumerate all child nodes with a specific name; <code class="computeroutput"><span class="identifier">attributes</span></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 class="computeroutput"><span class="identifier">children</span><span class="special">()</span></code>.
- </p>
-<p>
- This is an example of using these functions (<a href="../samples/traverse_rangefor.cpp" target="_top">samples/traverse_rangefor.cpp</a>):
- </p>
-<p>
-
-</p>
-<pre class="programlisting"><span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">tool</span><span class="special">:</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">children</span><span class="special">(</span><span class="string">"Tool"</span><span class="special">))</span>
-<span class="special">{</span>
- <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Tool:"</span><span class="special">;</span>
-
- <span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_attribute</span> <span class="identifier">attr</span><span class="special">:</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">attributes</span><span class="special">())</span>
- <span class="special">{</span>
- <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span> <span class="special">&lt;&lt;</span> <span class="identifier">attr</span><span class="special">.</span><span class="identifier">name</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">"="</span> <span class="special">&lt;&lt;</span> <span class="identifier">attr</span><span class="special">.</span><span class="identifier">value</span><span class="special">();</span>
- <span class="special">}</span>
-
- <span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">child</span><span class="special">:</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">children</span><span class="special">())</span>
- <span class="special">{</span>
- <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">", child "</span> <span class="special">&lt;&lt;</span> <span class="identifier">child</span><span class="special">.</span><span class="identifier">name</span><span class="special">();</span>
- <span class="special">}</span>
-
- <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
-<span class="special">}</span>
-</pre>
-<p>
- </p>
-</div>
-<div class="section">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.access.iterators"></a><a class="link" href="access.html#manual.access.iterators" title="Traversing node/attribute lists via iterators"> Traversing node/attribute lists
- via iterators</a>
-</h3></div></div></div>
-<a name="xml_node_iterator"></a><a name="xml_attribute_iterator"></a><a name="xml_node::begin"></a><a name="xml_node::end"></a><a name="xml_node::attributes_begin"></a><a name="xml_node::attributes_end"></a><p>
- Child node lists and attribute lists are simply double-linked lists; while
- you can use <code class="computeroutput"><span class="identifier">previous_sibling</span></code>/<code class="computeroutput"><span class="identifier">next_sibling</span></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>
-<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">xml_node_iterator</span><span class="special">;</span>
-<span class="keyword">class</span> <span class="identifier">xml_attribute_iterator</span><span class="special">;</span>
-
-<span class="keyword">typedef</span> <span class="identifier">xml_node_iterator</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">iterator</span><span class="special">;</span>
-<span class="identifier">iterator</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">begin</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="identifier">iterator</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">end</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-
-<span class="keyword">typedef</span> <span class="identifier">xml_attribute_iterator</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">attribute_iterator</span><span class="special">;</span>
-<span class="identifier">attribute_iterator</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">attributes_begin</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="identifier">attribute_iterator</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">attributes_end</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- <code class="computeroutput"><span class="identifier">begin</span></code> and <code class="computeroutput"><span class="identifier">attributes_begin</span></code>
- return iterators that point to the first node/attribute, respectively; <code class="computeroutput"><span class="identifier">end</span></code> and <code class="computeroutput"><span class="identifier">attributes_end</span></code>
- return past-the-end iterator for node/attribute list, respectively - this
- iterator can't be dereferenced, but decrementing it results in an iterator
- pointing to the last element in the list (except for empty lists, where decrementing
- past-the-end iterator results in undefined behavior). Past-the-end iterator
- is commonly used as a termination value for iteration loops (see sample below).
- If you want to get an iterator that points to an existing handle, you can
- construct the iterator with the handle as a single constructor argument,
- like so: <code class="computeroutput"><span class="identifier">xml_node_iterator</span><span class="special">(</span><span class="identifier">node</span><span class="special">)</span></code>.
- For <code class="computeroutput"><span class="identifier">xml_attribute_iterator</span></code>,
- you'll have to provide both an attribute and its parent node.
- </p>
-<p>
- <code class="computeroutput"><span class="identifier">begin</span></code> and <code class="computeroutput"><span class="identifier">end</span></code>
- return equal iterators if called on null node; such iterators can't be dereferenced.
- <code class="computeroutput"><span class="identifier">attributes_begin</span></code> and <code class="computeroutput"><span class="identifier">attributes_end</span></code> behave the same way. For
- correct iterator usage this means that child node/attribute collections of
- null nodes appear to be empty.
- </p>
-<p>
- Both types of iterators have bidirectional iterator semantics (i.e. they
- can be incremented and decremented, but efficient random access is not supported)
- and support all usual iterator operations - comparison, dereference, etc.
- The iterators are invalidated if the node/attribute objects they're pointing
- to are removed from the tree; adding nodes/attributes does not invalidate
- any iterators.
- </p>
-<p>
- Here is an example of using iterators for document traversal (<a href="../samples/traverse_iter.cpp" target="_top">samples/traverse_iter.cpp</a>):
- </p>
-<p>
-
-</p>
-<pre class="programlisting"><span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node_iterator</span> <span class="identifier">it</span> <span class="special">=</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">begin</span><span class="special">();</span> <span class="identifier">it</span> <span class="special">!=</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">end</span><span class="special">();</span> <span class="special">++</span><span class="identifier">it</span><span class="special">)</span>
-<span class="special">{</span>
- <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Tool:"</span><span class="special">;</span>
-
- <span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_attribute_iterator</span> <span class="identifier">ait</span> <span class="special">=</span> <span class="identifier">it</span><span class="special">-&gt;</span><span class="identifier">attributes_begin</span><span class="special">();</span> <span class="identifier">ait</span> <span class="special">!=</span> <span class="identifier">it</span><span class="special">-&gt;</span><span class="identifier">attributes_end</span><span class="special">();</span> <span class="special">++</span><span class="identifier">ait</span><span class="special">)</span>
- <span class="special">{</span>
- <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span> <span class="special">&lt;&lt;</span> <span class="identifier">ait</span><span class="special">-&gt;</span><span class="identifier">name</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">"="</span> <span class="special">&lt;&lt;</span> <span class="identifier">ait</span><span class="special">-&gt;</span><span class="identifier">value</span><span class="special">();</span>
- <span class="special">}</span>
-
- <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
-<span class="special">}</span>
-</pre>
-<p>
- </p>
-<div class="caution"><table border="0" summary="Caution">
-<tr>
-<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../images/caution.png"></td>
-<th align="left">Caution</th>
-</tr>
-<tr><td align="left" valign="top"><p>
- 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 by assignment - i.e. passing iterators to a function
- like <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">sort</span></code> - will not give expected results,
- as assignment modifies local handle that's stored in the iterator.
- </p></td></tr>
-</table></div>
-</div>
-<div class="section">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.access.walker"></a><a class="link" href="access.html#manual.access.walker" title="Recursive traversal with xml_tree_walker"> Recursive traversal with xml_tree_walker</a>
-</h3></div></div></div>
-<a name="xml_tree_walker"></a><p>
- The methods described above allow traversal of immediate children of some
- node; if you want to do a deep tree traversal, you'll have to do it via a
- recursive function or some equivalent method. However, pugixml provides a
- helper for depth-first traversal of a subtree. In order to use it, you have
- to implement <code class="computeroutput"><span class="identifier">xml_tree_walker</span></code>
- interface and to call <code class="computeroutput"><span class="identifier">traverse</span></code>
- function:
- </p>
-<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">xml_tree_walker</span>
-<span class="special">{</span>
-<span class="keyword">public</span><span class="special">:</span>
- <span class="keyword">virtual</span> <span class="keyword">bool</span> <span class="identifier">begin</span><span class="special">(</span><span class="identifier">xml_node</span><span class="special">&amp;</span> <span class="identifier">node</span><span class="special">);</span>
- <span class="keyword">virtual</span> <span class="keyword">bool</span> <span class="identifier">for_each</span><span class="special">(</span><span class="identifier">xml_node</span><span class="special">&amp;</span> <span class="identifier">node</span><span class="special">)</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
- <span class="keyword">virtual</span> <span class="keyword">bool</span> <span class="identifier">end</span><span class="special">(</span><span class="identifier">xml_node</span><span class="special">&amp;</span> <span class="identifier">node</span><span class="special">);</span>
-
- <span class="keyword">int</span> <span class="identifier">depth</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="special">};</span>
-
-<span class="keyword">bool</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">traverse</span><span class="special">(</span><span class="identifier">xml_tree_walker</span><span class="special">&amp;</span> <span class="identifier">walker</span><span class="special">);</span>
-</pre>
-<a name="xml_tree_walker::begin"></a><a name="xml_tree_walker::for_each"></a><a name="xml_tree_walker::end"></a><a name="xml_node::traverse"></a><p>
- The traversal is launched by calling <code class="computeroutput"><span class="identifier">traverse</span></code>
- function on traversal root and proceeds as follows:
- </p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem">
- First, <code class="computeroutput"><span class="identifier">begin</span></code> function
- is called with traversal root as its argument.
- </li>
-<li class="listitem">
- Then, <code class="computeroutput"><span class="identifier">for_each</span></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.
- </li>
-<li class="listitem">
- Finally, <code class="computeroutput"><span class="identifier">end</span></code> function
- is called with traversal root as its argument.
- </li>
-</ul></div>
-<p>
- If <code class="computeroutput"><span class="identifier">begin</span></code>, <code class="computeroutput"><span class="identifier">end</span></code>
- or any of the <code class="computeroutput"><span class="identifier">for_each</span></code> calls
- return <code class="computeroutput"><span class="keyword">false</span></code>, the traversal
- is terminated and <code class="computeroutput"><span class="keyword">false</span></code> is returned
- as the traversal result; otherwise, the traversal results in <code class="computeroutput"><span class="keyword">true</span></code>. Note that you don't have to override
- <code class="computeroutput"><span class="identifier">begin</span></code> or <code class="computeroutput"><span class="identifier">end</span></code>
- functions; their default implementations return <code class="computeroutput"><span class="keyword">true</span></code>.
- </p>
-<a name="xml_tree_walker::depth"></a><p>
- You can get the node's depth relative to the traversal root at any point
- by calling <code class="computeroutput"><span class="identifier">depth</span></code> function.
- It returns <code class="computeroutput"><span class="special">-</span><span class="number">1</span></code>
- if called from <code class="computeroutput"><span class="identifier">begin</span></code>/<code class="computeroutput"><span class="identifier">end</span></code>, and returns 0-based depth if called
- from <code class="computeroutput"><span class="identifier">for_each</span></code> - depth is
- 0 for all children of the traversal root, 1 for all grandchildren and so
- on.
- </p>
-<p>
- This is an example of traversing tree hierarchy with xml_tree_walker (<a href="../samples/traverse_walker.cpp" target="_top">samples/traverse_walker.cpp</a>):
- </p>
-<p>
-
-</p>
-<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">simple_walker</span><span class="special">:</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_tree_walker</span>
-<span class="special">{</span>
- <span class="keyword">virtual</span> <span class="keyword">bool</span> <span class="identifier">for_each</span><span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span><span class="special">&amp;</span> <span class="identifier">node</span><span class="special">)</span>
- <span class="special">{</span>
- <span class="keyword">for</span> <span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="identifier">depth</span><span class="special">();</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span><span class="special">;</span> <span class="comment">// indentation
-</span>
- <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">node_types</span><span class="special">[</span><span class="identifier">node</span><span class="special">.</span><span class="identifier">type</span><span class="special">()]</span> <span class="special">&lt;&lt;</span> <span class="string">": name='"</span> <span class="special">&lt;&lt;</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">name</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">"', value='"</span> <span class="special">&lt;&lt;</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">value</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">"'\n"</span><span class="special">;</span>
-
- <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> <span class="comment">// continue traversal
-</span> <span class="special">}</span>
-<span class="special">};</span>
-</pre>
-<p>
- </p>
-<p>
-
-</p>
-<pre class="programlisting"><span class="identifier">simple_walker</span> <span class="identifier">walker</span><span class="special">;</span>
-<span class="identifier">doc</span><span class="special">.</span><span class="identifier">traverse</span><span class="special">(</span><span class="identifier">walker</span><span class="special">);</span>
-</pre>
-<p>
- </p>
-</div>
-<div class="section">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.access.predicate"></a><a class="link" href="access.html#manual.access.predicate" title="Searching for nodes/attributes with predicates"> Searching for nodes/attributes
- with predicates</a>
-</h3></div></div></div>
-<a name="xml_node::find_attribute"></a><a name="xml_node::find_child"></a><a name="xml_node::find_node"></a><p>
- 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 class="computeroutput"><span class="identifier">find_</span></code>
- functions:
- </p>
-<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Predicate</span><span class="special">&gt;</span> <span class="identifier">xml_attribute</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">find_attribute</span><span class="special">(</span><span class="identifier">Predicate</span> <span class="identifier">pred</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Predicate</span><span class="special">&gt;</span> <span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">find_child</span><span class="special">(</span><span class="identifier">Predicate</span> <span class="identifier">pred</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Predicate</span><span class="special">&gt;</span> <span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">find_node</span><span class="special">(</span><span class="identifier">Predicate</span> <span class="identifier">pred</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- The predicate should be either a plain function or a function object which
- accepts one argument of type <code class="computeroutput"><span class="identifier">xml_attribute</span></code>
- (for <code class="computeroutput"><span class="identifier">find_attribute</span></code>) or
- <code class="computeroutput"><span class="identifier">xml_node</span></code> (for <code class="computeroutput"><span class="identifier">find_child</span></code> and <code class="computeroutput"><span class="identifier">find_node</span></code>),
- and returns <code class="computeroutput"><span class="keyword">bool</span></code>. The predicate
- is never called with null handle as an argument.
- </p>
-<p>
- <code class="computeroutput"><span class="identifier">find_attribute</span></code> function iterates
- through all attributes of the specified node, and returns the first attribute
- for which the predicate returned <code class="computeroutput"><span class="keyword">true</span></code>.
- If the predicate returned <code class="computeroutput"><span class="keyword">false</span></code>
- for all attributes or if there were no attributes (including the case where
- the node is null), null attribute is returned.
- </p>
-<p>
- <code class="computeroutput"><span class="identifier">find_child</span></code> function iterates
- through all child nodes of the specified node, and returns the first node
- for which the predicate returned <code class="computeroutput"><span class="keyword">true</span></code>.
- If the predicate returned <code class="computeroutput"><span class="keyword">false</span></code>
- for all nodes or if there were no child nodes (including the case where the
- node is null), null node is returned.
- </p>
-<p>
- <code class="computeroutput"><span class="identifier">find_node</span></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 class="computeroutput"><span class="keyword">true</span></code>. If the predicate returned
- <code class="computeroutput"><span class="keyword">false</span></code> for all nodes or if subtree
- was empty, null node is returned.
- </p>
-<p>
- This is an example of using predicate-based functions (<a href="../samples/traverse_predicate.cpp" target="_top">samples/traverse_predicate.cpp</a>):
- </p>
-<p>
-
-</p>
-<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">small_timeout</span><span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">node</span><span class="special">)</span>
-<span class="special">{</span>
- <span class="keyword">return</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"Timeout"</span><span class="special">).</span><span class="identifier">as_int</span><span class="special">()</span> <span class="special">&lt;</span> <span class="number">20</span><span class="special">;</span>
-<span class="special">}</span>
-
-<span class="keyword">struct</span> <span class="identifier">allow_remote_predicate</span>
-<span class="special">{</span>
- <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_attribute</span> <span class="identifier">attr</span><span class="special">)</span> <span class="keyword">const</span>
- <span class="special">{</span>
- <span class="keyword">return</span> <span class="identifier">strcmp</span><span class="special">(</span><span class="identifier">attr</span><span class="special">.</span><span class="identifier">name</span><span class="special">(),</span> <span class="string">"AllowRemote"</span><span class="special">)</span> <span class="special">==</span> <span class="number">0</span><span class="special">;</span>
- <span class="special">}</span>
-
- <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">node</span><span class="special">)</span> <span class="keyword">const</span>
- <span class="special">{</span>
- <span class="keyword">return</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"AllowRemote"</span><span class="special">).</span><span class="identifier">as_bool</span><span class="special">();</span>
- <span class="special">}</span>
-<span class="special">};</span>
-</pre>
-<p>
- </p>
-<p>
-
-</p>
-<pre class="programlisting"><span class="comment">// Find child via predicate (looks for direct children only)
-</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">find_child</span><span class="special">(</span><span class="identifier">allow_remote_predicate</span><span class="special">()).</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"Filename"</span><span class="special">).</span><span class="identifier">value</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
-
-<span class="comment">// Find node via predicate (looks for all descendants in depth-first order)
-</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">find_node</span><span class="special">(</span><span class="identifier">allow_remote_predicate</span><span class="special">()).</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"Filename"</span><span class="special">).</span><span class="identifier">value</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
-
-<span class="comment">// Find attribute via predicate
-</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">last_child</span><span class="special">().</span><span class="identifier">find_attribute</span><span class="special">(</span><span class="identifier">allow_remote_predicate</span><span class="special">()).</span><span class="identifier">value</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
-
-<span class="comment">// We can use simple functions instead of function objects
-</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">find_child</span><span class="special">(</span><span class="identifier">small_timeout</span><span class="special">).</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"Filename"</span><span class="special">).</span><span class="identifier">value</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
-</pre>
-<p>
- </p>
-</div>
-<div class="section">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.access.text"></a><a class="link" href="access.html#manual.access.text" title="Working with text contents"> Working with text contents</a>
-</h3></div></div></div>
-<a name="xml_text"></a><p>
- It is common to store data as text contents of some node - i.e. <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">node</span><span class="special">&gt;&lt;</span><span class="identifier">description</span><span class="special">&gt;</span><span class="identifier">This</span> <span class="identifier">is</span> <span class="identifier">a</span> <span class="identifier">node</span><span class="special">&lt;/</span><span class="identifier">description</span><span class="special">&gt;&lt;/</span><span class="identifier">node</span><span class="special">&gt;</span></code>.
- In this case, <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">description</span><span class="special">&gt;</span></code> node does not have a value, but instead
- has a child of type <a class="link" href="dom.html#node_pcdata">node_pcdata</a> with value
- <code class="computeroutput"><span class="string">"This is a node"</span></code>. pugixml
- provides a special class, <code class="computeroutput"><span class="identifier">xml_text</span></code>,
- to work with such data. Working with text objects to modify data is described
- in <a class="link" href="modify.html#manual.modify.text" title="Working with text contents">the documentation for modifying document
- data</a>; this section describes the access interface of <code class="computeroutput"><span class="identifier">xml_text</span></code>.
- </p>
-<a name="xml_node::text"></a><p>
- You can get the text object from a node by using <code class="computeroutput"><span class="identifier">text</span><span class="special">()</span></code> method:
- </p>
-<pre class="programlisting"><span class="identifier">xml_text</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">text</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- If the node has a type <code class="computeroutput"><span class="identifier">node_pcdata</span></code>
- or <code class="computeroutput"><span class="identifier">node_cdata</span></code>, then the node
- itself is used to return data; otherwise, a first child node of type <code class="computeroutput"><span class="identifier">node_pcdata</span></code> or <code class="computeroutput"><span class="identifier">node_cdata</span></code>
- is used.
- </p>
-<a name="xml_text::empty"></a><a name="xml_text::unspecified_bool_type"></a><p>
- 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 class="computeroutput"><span class="keyword">if</span>
- <span class="special">(</span><span class="identifier">text</span><span class="special">)</span> <span class="special">{</span> <span class="special">...</span>
- <span class="special">}</span></code> or <code class="computeroutput"><span class="keyword">if</span>
- <span class="special">(!</span><span class="identifier">text</span><span class="special">)</span> <span class="special">{</span> <span class="special">...</span>
- <span class="special">}</span></code>. Alternatively you can check it
- by using the <code class="computeroutput"><span class="identifier">empty</span><span class="special">()</span></code>
- method:
- </p>
-<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xml_text</span><span class="special">::</span><span class="identifier">empty</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<a name="xml_text::get"></a><p>
- Given a text object, you can get the contents (i.e. the value of PCDATA/CDATA
- node) by using the following function:
- </p>
-<pre class="programlisting"><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">xml_text</span><span class="special">::</span><span class="identifier">get</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- In case text object is empty, the function returns an empty string - it never
- returns a null pointer.
- </p>
-<a name="xml_text::as_string"></a><a name="xml_text::as_int"></a><a name="xml_text::as_uint"></a><a name="xml_text::as_double"></a><a name="xml_text::as_float"></a><a name="xml_text::as_bool"></a><a name="xml_text::as_llong"></a><a name="xml_text::as_ullong"></a><p>
- 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>
-<pre class="programlisting"><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">xml_text</span><span class="special">::</span><span class="identifier">as_string</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">def</span> <span class="special">=</span> <span class="string">""</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="keyword">int</span> <span class="identifier">xml_text</span><span class="special">::</span><span class="identifier">as_int</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">def</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">xml_text</span><span class="special">::</span><span class="identifier">as_uint</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">def</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="keyword">double</span> <span class="identifier">xml_text</span><span class="special">::</span><span class="identifier">as_double</span><span class="special">(</span><span class="keyword">double</span> <span class="identifier">def</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="keyword">float</span> <span class="identifier">xml_text</span><span class="special">::</span><span class="identifier">as_float</span><span class="special">(</span><span class="keyword">float</span> <span class="identifier">def</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="keyword">bool</span> <span class="identifier">xml_text</span><span class="special">::</span><span class="identifier">as_bool</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">def</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="keyword">long</span> <span class="keyword">long</span> <span class="identifier">xml_text</span><span class="special">::</span><span class="identifier">as_llong</span><span class="special">(</span><span class="keyword">long</span> <span class="keyword">long</span> <span class="identifier">def</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="keyword">unsigned</span> <span class="keyword">long</span> <span class="keyword">long</span> <span class="identifier">xml_text</span><span class="special">::</span><span class="identifier">as_ullong</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="keyword">long</span> <span class="keyword">long</span> <span class="identifier">def</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- All of the above functions have the same semantics as similar <code class="computeroutput"><span class="identifier">xml_attribute</span></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 class="link" href="access.html#xml_attribute::as_int">refer
- to documentation for the attribute functions</a> for details.
- </p>
-<a name="xml_text::data"></a><p>
- <code class="computeroutput"><span class="identifier">xml_text</span></code> is essentially a
- helper class that operates on <code class="computeroutput"><span class="identifier">xml_node</span></code>
- values. It is bound to a node of type <a class="link" href="dom.html#node_pcdata">node_pcdata</a>
- or <a class="link" href="dom.html#node_cdata">node_cdata</a>. You can use the following
- function to retrieve this node:
- </p>
-<pre class="programlisting"><span class="identifier">xml_node</span> <span class="identifier">xml_text</span><span class="special">::</span><span class="identifier">data</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- Essentially, assuming <code class="computeroutput"><span class="identifier">text</span></code>
- is an <code class="computeroutput"><span class="identifier">xml_text</span></code> object, calling
- <code class="computeroutput"><span class="identifier">text</span><span class="special">.</span><span class="identifier">get</span><span class="special">()</span></code> is
- equivalent to calling <code class="computeroutput"><span class="identifier">text</span><span class="special">.</span><span class="identifier">data</span><span class="special">().</span><span class="identifier">value</span><span class="special">()</span></code>.
- </p>
-<p>
- This is an example of using <code class="computeroutput"><span class="identifier">xml_text</span></code>
- object (<a href="../samples/text.cpp" target="_top">samples/text.cpp</a>):
- </p>
-<p>
-
-</p>
-<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Project name: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">project</span><span class="special">.</span><span class="identifier">child</span><span class="special">(</span><span class="string">"name"</span><span class="special">).</span><span class="identifier">text</span><span class="special">().</span><span class="identifier">get</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
-<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Project version: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">project</span><span class="special">.</span><span class="identifier">child</span><span class="special">(</span><span class="string">"version"</span><span class="special">).</span><span class="identifier">text</span><span class="special">().</span><span class="identifier">as_double</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
-<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Project visibility: "</span> <span class="special">&lt;&lt;</span> <span class="special">(</span><span class="identifier">project</span><span class="special">.</span><span class="identifier">child</span><span class="special">(</span><span class="string">"public"</span><span class="special">).</span><span class="identifier">text</span><span class="special">().</span><span class="identifier">as_bool</span><span class="special">(/*</span> <span class="identifier">def</span><span class="special">=</span> <span class="special">*/</span> <span class="keyword">true</span><span class="special">)</span> <span class="special">?</span> <span class="string">"public"</span> <span class="special">:</span> <span class="string">"private"</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
-<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Project description: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">project</span><span class="special">.</span><span class="identifier">child</span><span class="special">(</span><span class="string">"description"</span><span class="special">).</span><span class="identifier">text</span><span class="special">().</span><span class="identifier">get</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
-</pre>
-<p>
- </p>
-</div>
-<div class="section">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.access.misc"></a><a class="link" href="access.html#manual.access.misc" title="Miscellaneous functions"> Miscellaneous functions</a>
-</h3></div></div></div>
-<a name="xml_node::root"></a><p>
- If you need to get the document root of some node, you can use the following
- function:
- </p>
-<pre class="programlisting"><span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">root</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- This function returns the node with type <a class="link" href="dom.html#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>
-<a name="xml_node::path"></a><a name="xml_node::first_element_by_path"></a><p>
- 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>
-<pre class="programlisting"><span class="identifier">string_t</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">path</span><span class="special">(</span><span class="identifier">char_t</span> <span class="identifier">delimiter</span> <span class="special">=</span> <span class="char">'/'</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">first_element_by_path</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">path</span><span class="special">,</span> <span class="identifier">char_t</span> <span class="identifier">delimiter</span> <span class="special">=</span> <span class="char">'/'</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- Node paths consist of node names, separated with a delimiter (which is <code class="computeroutput"><span class="special">/</span></code> by default); also paths can contain self
- (<code class="computeroutput"><span class="special">.</span></code>) and parent (<code class="computeroutput"><span class="special">..</span></code>) pseudo-names, so that this is a valid
- path: <code class="computeroutput"><span class="string">"../../foo/./bar"</span></code>.
- <code class="computeroutput"><span class="identifier">path</span></code> returns the path to
- the node from the document root, <code class="computeroutput"><span class="identifier">first_element_by_path</span></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 class="computeroutput"><span class="special">&lt;</span><span class="identifier">a</span><span class="special">&gt;&lt;</span><span class="identifier">b</span><span class="special">&gt;&lt;</span><span class="identifier">c</span><span class="special">/&gt;&lt;/</span><span class="identifier">b</span><span class="special">&gt;&lt;/</span><span class="identifier">a</span><span class="special">&gt;</span></code>,
- node <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">c</span><span class="special">/&gt;</span></code> has path <code class="computeroutput"><span class="string">"a/b/c"</span></code>;
- calling <code class="computeroutput"><span class="identifier">first_element_by_path</span></code>
- for document with path <code class="computeroutput"><span class="string">"a/b"</span></code>
- results in node <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">b</span><span class="special">/&gt;</span></code>; calling <code class="computeroutput"><span class="identifier">first_element_by_path</span></code>
- for node <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">a</span><span class="special">/&gt;</span></code> with path <code class="computeroutput"><span class="string">"../a/./b/../."</span></code>
- results in node <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">a</span><span class="special">/&gt;</span></code>; calling <code class="computeroutput"><span class="identifier">first_element_by_path</span></code>
- with path <code class="computeroutput"><span class="string">"/a"</span></code> results
- in node <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">a</span><span class="special">/&gt;</span></code> for any node.
- </p>
-<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 class="computeroutput"><span class="identifier">first_element_by_path</span></code>
- is null node; also <code class="computeroutput"><span class="identifier">first_element_by_path</span></code>
- returns null node for null nodes, in which case the path does not matter.
- <code class="computeroutput"><span class="identifier">path</span></code> returns an empty string
- for null nodes.
- </p>
-<div class="note"><table border="0" summary="Note">
-<tr>
-<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
-<th align="left">Note</th>
-</tr>
-<tr><td align="left" valign="top"><p>
- <code class="computeroutput"><span class="identifier">path</span></code> function returns the
- result as STL string, and thus is not available if <a class="link" href="install.html#PUGIXML_NO_STL">PUGIXML_NO_STL</a>
- is defined.
- </p></td></tr>
-</table></div>
-<a name="xml_node::offset_debug"></a><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>
-<pre class="programlisting"><span class="identifier">ptrdiff_t</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">offset_debug</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- If the offset is not available (this happens if the node is null, was not
- originally parsed from a stream, or has changed in a significant way), the
- function returns -1. Otherwise it returns the offset to node's data from
- the beginning of XML buffer in <a class="link" href="dom.html#char_t">pugi::char_t</a>
- units. For more information on parsing offsets, see <a class="link" href="loading.html#xml_parse_result::offset">parsing
- error handling documentation</a>.
- </p>
-</div>
-</div>
-<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left"></td>
-<td align="right"><div class="copyright-footer">Copyright &#169; 2014 Arseny Kapoulkine<p>
- Distributed under the MIT License
- </p>
-</div></td>
-</tr></table>
-<hr>
-<table width="100%"><tr>
-<td>
-<a href="http://pugixml.org/">pugixml 1.5</a> manual |
- <a href="../manual.html">Overview</a> |
- <a href="install.html">Installation</a> |
- Document:
- <a href="dom.html">Object model</a> &middot; <a href="loading.html">Loading</a> &middot; <b>Accessing</b> &middot; <a href="modify.html">Modifying</a> &middot; <a href="saving.html">Saving</a> |
- <a href="xpath.html">XPath</a> |
- <a href="apiref.html">API Reference</a> |
- <a href="toc.html">Table of Contents</a>
-</td>
-<td width="*" align="right"><div class="spirit-nav">
-<a accesskey="p" href="loading.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../manual.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../manual.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="modify.html"><img src="../images/next.png" alt="Next"></a>
-</div></td>
-</tr></table>
-</body>
-</html>