diff options
Diffstat (limited to 'docs/manual/access.html')
| -rw-r--r-- | docs/manual/access.html | 900 |
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> · <a href="loading.html">Loading</a> · <b>Accessing</b> · <a href="modify.html">Modifying</a> · <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"><</span><span class="identifier">a</span><span class="special">/><</span><span class="identifier">b</span><span class="special">/><</span><span class="identifier">c</span><span class="special">/></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"><</span><span class="identifier">b</span><span class="special">/></span></code> - results in a handle pointing to <code class="computeroutput"><span class="special"><</span><span class="identifier">c</span><span class="special">/></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"><</span><span class="identifier">a</span><span class="special">/></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"><<</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"><<</span> <span class="string">" "</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="special"><<</span> <span class="string">"="</span> <span class="special"><<</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"><<</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"><</span><span class="identifier">node</span><span class="special">><</span><span class="identifier">description</span><span class="special">></span><span class="identifier">This</span> <span class="identifier">is</span> <span class="identifier">a</span> <span class="identifier">node</span><span class="special"></</span><span class="identifier">description</span><span class="special">></</span><span class="identifier">node</span><span class="special">></span></code>. - In this case, <code class="computeroutput"><span class="special"><</span><span class="identifier">description</span><span class="special">></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"><<</span> <span class="string">"Tool "</span> <span class="special"><<</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"><<</span> <span class="string">": AllowRemote "</span> <span class="special"><<</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"><<</span> <span class="string">", Timeout "</span> <span class="special"><<</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"><<</span> <span class="string">", Description '"</span> <span class="special"><<</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"><<</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"><</span><span class="identifier">group</span><span class="special">><</span><span class="identifier">item</span> <span class="identifier">id</span><span class="special">=</span><span class="string">"1"</span><span class="special">/></span> <span class="special"><</span><span class="identifier">item</span> <span class="identifier">id</span><span class="special">=</span><span class="string">"2"</span><span class="special">/></</span><span class="identifier">group</span><span class="special">></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"><<</span> <span class="string">"Tool for *.dae generation: "</span> <span class="special"><<</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"><<</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"><<</span> <span class="string">"Tool "</span> <span class="special"><<</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"><<</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"><<</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"><<</span> <span class="string">" "</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="special"><<</span> <span class="string">"="</span> <span class="special"><<</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"><<</span> <span class="string">", child "</span> <span class="special"><<</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"><<</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"><<</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">-></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">-></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"><<</span> <span class="string">" "</span> <span class="special"><<</span> <span class="identifier">ait</span><span class="special">-></span><span class="identifier">name</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"="</span> <span class="special"><<</span> <span class="identifier">ait</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"><<</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">&</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">&</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">&</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">&</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">&</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"><</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"><<</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"><<</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"><<</span> <span class="string">": name='"</span> <span class="special"><<</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">name</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"', value='"</span> <span class="special"><<</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</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"><</span><span class="keyword">typename</span> <span class="identifier">Predicate</span><span class="special">></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"><</span><span class="keyword">typename</span> <span class="identifier">Predicate</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</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"><</span><span class="keyword">typename</span> <span class="identifier">Predicate</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_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"><</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"><<</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"><<</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"><<</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"><<</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"><<</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"><<</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"><<</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"><<</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"><</span><span class="identifier">node</span><span class="special">><</span><span class="identifier">description</span><span class="special">></span><span class="identifier">This</span> <span class="identifier">is</span> <span class="identifier">a</span> <span class="identifier">node</span><span class="special"></</span><span class="identifier">description</span><span class="special">></</span><span class="identifier">node</span><span class="special">></span></code>. - In this case, <code class="computeroutput"><span class="special"><</span><span class="identifier">description</span><span class="special">></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"><<</span> <span class="string">"Project name: "</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">"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"><<</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"><<</span> <span class="string">"Project version: "</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">"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"><<</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"><<</span> <span class="string">"Project visibility: "</span> <span class="special"><<</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"><<</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"><<</span> <span class="string">"Project description: "</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">"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"><<</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"><</span><span class="identifier">a</span><span class="special">><</span><span class="identifier">b</span><span class="special">><</span><span class="identifier">c</span><span class="special">/></</span><span class="identifier">b</span><span class="special">></</span><span class="identifier">a</span><span class="special">></span></code>, - node <code class="computeroutput"><span class="special"><</span><span class="identifier">c</span><span class="special">/></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"><</span><span class="identifier">b</span><span class="special">/></span></code>; calling <code class="computeroutput"><span class="identifier">first_element_by_path</span></code> - for node <code class="computeroutput"><span class="special"><</span><span class="identifier">a</span><span class="special">/></span></code> with path <code class="computeroutput"><span class="string">"../a/./b/../."</span></code> - results in node <code class="computeroutput"><span class="special"><</span><span class="identifier">a</span><span class="special">/></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"><</span><span class="identifier">a</span><span class="special">/></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 © 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> · <a href="loading.html">Loading</a> · <b>Accessing</b> · <a href="modify.html">Modifying</a> · <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> |