From 2843f91d008990e9940e19dbdf8cd906ad1c057d Mon Sep 17 00:00:00 2001
From: Arseny Kapoulkine <arseny.kapoulkine@gmail.com>
Date: Sat, 21 Mar 2015 21:04:28 -0700
Subject: docs: Remove old HTML documentation
---
docs/manual/xpath.html | 749 -------------------------------------------------
1 file changed, 749 deletions(-)
delete mode 100644 docs/manual/xpath.html
(limited to 'docs/manual/xpath.html')
diff --git a/docs/manual/xpath.html b/docs/manual/xpath.html
deleted file mode 100644
index 574776d..0000000
--- a/docs/manual/xpath.html
+++ /dev/null
@@ -1,749 +0,0 @@
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
-<title>XPath</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.6">
-<link rel="up" href="../manual.html" title="pugixml 1.6">
-<link rel="prev" href="saving.html" title="Saving document">
-<link rel="next" href="changes.html" title="Changelog">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<table width="100%"><tr>
-<td>
-<a href="http://pugixml.org/">pugixml 1.6</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> · <a href="access.html">Accessing</a> · <a href="modify.html">Modifying</a> · <a href="saving.html">Saving</a> |
- <b>XPath</b> |
- <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="saving.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="changes.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.xpath"></a><a class="link" href="xpath.html" title="XPath"> XPath</a>
-</h2></div></div></div>
-<div class="toc"><dl class="toc">
-<dt><span class="section"><a href="xpath.html#manual.xpath.types"> XPath types</a></span></dt>
-<dt><span class="section"><a href="xpath.html#manual.xpath.select"> Selecting nodes via XPath expression</a></span></dt>
-<dt><span class="section"><a href="xpath.html#manual.xpath.query"> Using query objects</a></span></dt>
-<dt><span class="section"><a href="xpath.html#manual.xpath.variables"> Using variables</a></span></dt>
-<dt><span class="section"><a href="xpath.html#manual.xpath.errors"> Error handling</a></span></dt>
-<dt><span class="section"><a href="xpath.html#manual.xpath.w3c"> Conformance to W3C specification</a></span></dt>
-</dl></div>
-<p>
- If the task at hand is to select a subset of document nodes that match some
- criteria, it is possible to code a function using the existing traversal functionality
- for any practical criteria. However, often either a data-driven approach is
- desirable, in case the criteria are not predefined and come from a file, or
- it is inconvenient to use traversal interfaces and a higher-level DSL is required.
- There is a standard language for XML processing, XPath, that can be useful
- for these cases. pugixml implements an almost complete subset of XPath 1.0.
- Because of differences in document object model and some performance implications,
- there are minor violations of the official specifications, which can be found
- in <a class="xref" href="xpath.html#manual.xpath.w3c" title="Conformance to W3C specification"> Conformance to W3C specification</a>. The rest of this section describes the interface for XPath
- functionality. Please note that if you wish to learn to use XPath language,
- you have to look for other tutorials or manuals; for example, you can read
- <a href="http://www.w3schools.com/xpath/" target="_top">W3Schools XPath tutorial</a>,
- <a href="http://www.tizag.com/xmlTutorial/xpathtutorial.php" target="_top">XPath tutorial
- at tizag.com</a>, and <a href="http://www.w3.org/TR/xpath/" target="_top">the XPath
- 1.0 specification</a>.
- </p>
-<div class="section">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.xpath.types"></a><a class="link" href="xpath.html#manual.xpath.types" title="XPath types"> XPath types</a>
-</h3></div></div></div>
-<a name="xpath_value_type"></a><a name="xpath_type_number"></a><a name="xpath_type_string"></a><a name="xpath_type_boolean"></a><a name="xpath_type_node_set"></a><a name="xpath_type_none"></a><p>
- Each XPath expression can have one of the following types: boolean, number,
- string or node set. Boolean type corresponds to <code class="computeroutput"><span class="keyword">bool</span></code>
- type, number type corresponds to <code class="computeroutput"><span class="keyword">double</span></code>
- type, string type corresponds to either <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code>
- or <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wstring</span></code>, depending on whether <a class="link" href="dom.html#manual.dom.unicode" title="Unicode interface">wide
- character interface is enabled</a>, and node set corresponds to <a class="link" href="xpath.html#xpath_node_set">xpath_node_set</a> type. There is an enumeration,
- <code class="computeroutput"><span class="identifier">xpath_value_type</span></code>, which can
- take the values <code class="computeroutput"><span class="identifier">xpath_type_boolean</span></code>,
- <code class="computeroutput"><span class="identifier">xpath_type_number</span></code>, <code class="computeroutput"><span class="identifier">xpath_type_string</span></code> or <code class="computeroutput"><span class="identifier">xpath_type_node_set</span></code>,
- accordingly.
- </p>
-<a name="xpath_node"></a><a name="xpath_node::node"></a><a name="xpath_node::attribute"></a><a name="xpath_node::parent"></a><p>
- Because an XPath node can be either a node or an attribute, there is a special
- type, <code class="computeroutput"><span class="identifier">xpath_node</span></code>, which is
- a discriminated union of these types. A value of this type contains two node
- handles, one of <code class="computeroutput"><span class="identifier">xml_node</span></code>
- type, and another one of <code class="computeroutput"><span class="identifier">xml_attribute</span></code>
- type; at most one of them can be non-null. The accessors to get these handles
- are available:
- </p>
-<pre class="programlisting"><span class="identifier">xml_node</span> <span class="identifier">xpath_node</span><span class="special">::</span><span class="identifier">node</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="identifier">xml_attribute</span> <span class="identifier">xpath_node</span><span class="special">::</span><span class="identifier">attribute</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- XPath nodes can be null, in which case both accessors return null handles.
- </p>
-<p>
- Note that as per XPath specification, each XPath node has a parent, which
- can be retrieved via this function:
- </p>
-<pre class="programlisting"><span class="identifier">xml_node</span> <span class="identifier">xpath_node</span><span class="special">::</span><span class="identifier">parent</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 if the XPath node corresponds to <code class="computeroutput"><span class="identifier">xml_node</span></code>
- handle (equivalent to <code class="computeroutput"><span class="identifier">node</span><span class="special">().</span><span class="identifier">parent</span><span class="special">()</span></code>), or the node to which the attribute belongs
- to, if the XPath node corresponds to <code class="computeroutput"><span class="identifier">xml_attribute</span></code>
- handle. For null nodes, <code class="computeroutput"><span class="identifier">parent</span></code>
- returns null handle.
- </p>
-<a name="xpath_node::unspecified_bool_type"></a><a name="xpath_node::comparison"></a><p>
- Like node and attribute handles, XPath node handles can be implicitly cast
- to boolean-like object to check if it is a null node, and also can be compared
- for equality with each other.
- </p>
-<a name="xpath_node::ctor"></a><p>
- You can also create XPath nodes with one of the three constructors: the default
- constructor, the constructor that takes node argument, and the constructor
- that takes attribute and node arguments (in which case the attribute must
- belong to the attribute list of the node). The constructor from <code class="computeroutput"><span class="identifier">xml_node</span></code> is implicit, so you can usually
- pass <code class="computeroutput"><span class="identifier">xml_node</span></code> to functions
- that expect <code class="computeroutput"><span class="identifier">xpath_node</span></code>. Apart
- from that you usually don't need to create your own XPath node objects, since
- they are returned to you via selection functions.
- </p>
-<a name="xpath_node_set"></a><p>
- XPath expressions operate not on single nodes, but instead on node sets.
- A node set is a collection of nodes, which can be optionally ordered in either
- a forward document order or a reverse one. Document order is defined in XPath
- specification; an XPath node is before another node in document order if
- it appears before it in XML representation of the corresponding document.
- </p>
-<a name="xpath_node_set::const_iterator"></a><a name="xpath_node_set::begin"></a><a name="xpath_node_set::end"></a><p>
- Node sets are represented by <code class="computeroutput"><span class="identifier">xpath_node_set</span></code>
- object, which has an interface that resembles one of sequential random-access
- containers. It has an iterator type along with usual begin/past-the-end iterator
- accessors:
- </p>
-<pre class="programlisting"><span class="keyword">typedef</span> <span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">*</span> <span class="identifier">xpath_node_set</span><span class="special">::</span><span class="identifier">const_iterator</span><span class="special">;</span>
-<span class="identifier">const_iterator</span> <span class="identifier">xpath_node_set</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">const_iterator</span> <span class="identifier">xpath_node_set</span><span class="special">::</span><span class="identifier">end</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<a name="xpath_node_set::index"></a><a name="xpath_node_set::size"></a><a name="xpath_node_set::empty"></a><p>
- And it also can be iterated via indices, just like <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code>:
- </p>
-<pre class="programlisting"><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span> <span class="identifier">xpath_node_set</span><span class="special">::</span><span class="keyword">operator</span><span class="special">[](</span><span class="identifier">size_t</span> <span class="identifier">index</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="identifier">size_t</span> <span class="identifier">xpath_node_set</span><span class="special">::</span><span class="identifier">size</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="keyword">bool</span> <span class="identifier">xpath_node_set</span><span class="special">::</span><span class="identifier">empty</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- All of the above operations have the same semantics as that of <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code>:
- the iterators are random-access, all of the above operations are constant
- time, and accessing the element at index that is greater or equal than the
- set size results in undefined behavior. You can use both iterator-based and
- index-based access for iteration, however the iterator-based one can be faster.
- </p>
-<a name="xpath_node_set::type"></a><a name="xpath_node_set::type_unsorted"></a><a name="xpath_node_set::type_sorted"></a><a name="xpath_node_set::type_sorted_reverse"></a><a name="xpath_node_set::sort"></a><p>
- The order of iteration depends on the order of nodes inside the set; the
- order can be queried via the following function:
- </p>
-<pre class="programlisting"><span class="keyword">enum</span> <span class="identifier">xpath_node_set</span><span class="special">::</span><span class="identifier">type_t</span> <span class="special">{</span><span class="identifier">type_unsorted</span><span class="special">,</span> <span class="identifier">type_sorted</span><span class="special">,</span> <span class="identifier">type_sorted_reverse</span><span class="special">};</span>
-<span class="identifier">type_t</span> <span class="identifier">xpath_node_set</span><span class="special">::</span><span class="identifier">type</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- <code class="computeroutput"><span class="identifier">type</span></code> function returns the
- current order of nodes; <code class="computeroutput"><span class="identifier">type_sorted</span></code>
- means that the nodes are in forward document order, <code class="computeroutput"><span class="identifier">type_sorted_reverse</span></code>
- means that the nodes are in reverse document order, and <code class="computeroutput"><span class="identifier">type_unsorted</span></code>
- means that neither order is guaranteed (nodes can accidentally be in a sorted
- order even if <code class="computeroutput"><span class="identifier">type</span><span class="special">()</span></code>
- returns <code class="computeroutput"><span class="identifier">type_unsorted</span></code>). If
- you require a specific order of iteration, you can change it via <code class="computeroutput"><span class="identifier">sort</span></code> function:
- </p>
-<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">xpath_node_set</span><span class="special">::</span><span class="identifier">sort</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">reverse</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">);</span>
-</pre>
-<p>
- Calling <code class="computeroutput"><span class="identifier">sort</span></code> sorts the nodes
- in either forward or reverse document order, depending on the argument; after
- this call <code class="computeroutput"><span class="identifier">type</span><span class="special">()</span></code>
- will return <code class="computeroutput"><span class="identifier">type_sorted</span></code> or
- <code class="computeroutput"><span class="identifier">type_sorted_reverse</span></code>.
- </p>
-<a name="xpath_node_set::first"></a><p>
- Often the actual iteration is not needed; instead, only the first element
- in document order is required. For this, a special accessor is provided:
- </p>
-<pre class="programlisting"><span class="identifier">xpath_node</span> <span class="identifier">xpath_node_set</span><span class="special">::</span><span class="identifier">first</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- This function returns the first node in forward document order from the set,
- or null node if the set is empty. Note that while the result of the node
- does not depend on the order of nodes in the set (i.e. on the result of
- <code class="computeroutput"><span class="identifier">type</span><span class="special">()</span></code>),
- the complexity does - if the set is sorted, the complexity is constant, otherwise
- it is linear in the number of elements or worse.
- </p>
-<a name="xpath_node_set::ctor"></a><p>
- While in the majority of cases the node set is returned by XPath functions,
- sometimes there is a need to manually construct a node set. For such cases,
- a constructor is provided which takes an iterator range (<code class="computeroutput"><span class="identifier">const_iterator</span></code>
- is a typedef for <code class="computeroutput"><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">*</span></code>), and an optional type:
- </p>
-<pre class="programlisting"><span class="identifier">xpath_node_set</span><span class="special">::</span><span class="identifier">xpath_node_set</span><span class="special">(</span><span class="identifier">const_iterator</span> <span class="identifier">begin</span><span class="special">,</span> <span class="identifier">const_iterator</span> <span class="identifier">end</span><span class="special">,</span> <span class="identifier">type_t</span> <span class="identifier">type</span> <span class="special">=</span> <span class="identifier">type_unsorted</span><span class="special">);</span>
-</pre>
-<p>
- The constructor copies the specified range and sets the specified type. The
- objects in the range are not checked in any way; you'll have to ensure that
- the range contains no duplicates, and that the objects are sorted according
- to the <code class="computeroutput"><span class="identifier">type</span></code> parameter. Otherwise
- XPath operations with this set may produce unexpected results.
- </p>
-</div>
-<div class="section">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.xpath.select"></a><a class="link" href="xpath.html#manual.xpath.select" title="Selecting nodes via XPath expression"> Selecting nodes via XPath expression</a>
-</h3></div></div></div>
-<a name="xml_node::select_node"></a><a name="xml_node::select_nodes"></a><p>
- If you want to select nodes that match some XPath expression, you can do
- it with the following functions:
- </p>
-<pre class="programlisting"><span class="identifier">xpath_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">select_node</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">query</span><span class="special">,</span> <span class="identifier">xpath_variable_set</span><span class="special">*</span> <span class="identifier">variables</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="identifier">xpath_node_set</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">select_nodes</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">query</span><span class="special">,</span> <span class="identifier">xpath_variable_set</span><span class="special">*</span> <span class="identifier">variables</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">select_nodes</span></code> function compiles
- the expression and then executes it with the node as a context node, and
- returns the resulting node set. <code class="computeroutput"><span class="identifier">select_node</span></code>
- returns only the first node in document order from the result, and is equivalent
- to calling <code class="computeroutput"><span class="identifier">select_nodes</span><span class="special">(</span><span class="identifier">query</span><span class="special">).</span><span class="identifier">first</span><span class="special">()</span></code>.
- If the XPath expression does not match anything, or the node handle is null,
- <code class="computeroutput"><span class="identifier">select_nodes</span></code> returns an empty
- set, and <code class="computeroutput"><span class="identifier">select_node</span></code> returns
- null XPath node.
- </p>
-<p>
- If exception handling is not disabled, both functions throw <a class="link" href="xpath.html#xpath_exception">xpath_exception</a>
- if the query can not be compiled or if it returns a value with type other
- than node set; see <a class="xref" href="xpath.html#manual.xpath.errors" title="Error handling"> Error handling</a> for details.
- </p>
-<a name="xml_node::select_node_precomp"></a><a name="xml_node::select_nodes_precomp"></a><p>
- While compiling expressions is fast, the compilation time can introduce a
- significant overhead if the same expression is used many times on small subtrees.
- If you're doing many similar queries, consider compiling them into query
- objects (see <a class="xref" href="xpath.html#manual.xpath.query" title="Using query objects"> Using query objects</a> for further reference). Once you get a compiled
- query object, you can pass it to select functions instead of an expression
- string:
- </p>
-<pre class="programlisting"><span class="identifier">xpath_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">select_node</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_query</span><span class="special">&</span> <span class="identifier">query</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="identifier">xpath_node_set</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">select_nodes</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_query</span><span class="special">&</span> <span class="identifier">query</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- If exception handling is not disabled, both functions throw <a class="link" href="xpath.html#xpath_exception">xpath_exception</a>
- if the query returns a value with type other than node set.
- </p>
-<p>
- This is an example of selecting nodes using XPath expressions (<a href="../samples/xpath_select.cpp" target="_top">samples/xpath_select.cpp</a>):
- </p>
-<p>
-
-</p>
-<pre class="programlisting"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_node_set</span> <span class="identifier">tools</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">select_nodes</span><span class="special">(</span><span class="string">"/Profile/Tools/Tool[@AllowRemote='true' and @DeriveCaptionFrom='lastparam']"</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">"Tools:\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">xpath_node_set</span><span class="special">::</span><span class="identifier">const_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">pugi</span><span class="special">::</span><span class="identifier">xpath_node</span> <span class="identifier">node</span> <span class="special">=</span> <span class="special">*</span><span class="identifier">it</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">node</span><span class="special">.</span><span class="identifier">node</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>
-
-<span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_node</span> <span class="identifier">build_tool</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">select_node</span><span class="special">(</span><span class="string">"//Tool[contains(Description, 'build system')]"</span><span class="special">);</span>
-
-<span class="keyword">if</span> <span class="special">(</span><span class="identifier">build_tool</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">"Build tool: "</span> <span class="special"><<</span> <span class="identifier">build_tool</span><span class="special">.</span><span class="identifier">node</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>
-</pre>
-<p>
- </p>
-</div>
-<div class="section">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.xpath.query"></a><a class="link" href="xpath.html#manual.xpath.query" title="Using query objects"> Using query objects</a>
-</h3></div></div></div>
-<a name="xpath_query"></a><p>
- When you call <code class="computeroutput"><span class="identifier">select_nodes</span></code>
- with an expression string as an argument, a query object is created behind
- the scenes. A query object represents a compiled XPath expression. Query
- objects can be needed in the following circumstances:
- </p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem">
- You can precompile expressions to query objects to save compilation time
- if it becomes an issue;
- </li>
-<li class="listitem">
- You can use query objects to evaluate XPath expressions which result
- in booleans, numbers or strings;
- </li>
-<li class="listitem">
- You can get the type of expression value via query object.
- </li>
-</ul></div>
-<p>
- Query objects correspond to <code class="computeroutput"><span class="identifier">xpath_query</span></code>
- type. They are immutable and non-copyable: they are bound to the expression
- at creation time and can not be cloned. If you want to put query objects
- in a container, allocate them on heap via <code class="computeroutput"><span class="keyword">new</span></code>
- operator and store pointers to <code class="computeroutput"><span class="identifier">xpath_query</span></code>
- in the container.
- </p>
-<a name="xpath_query::ctor"></a><p>
- You can create a query object with the constructor that takes XPath expression
- as an argument:
- </p>
-<pre class="programlisting"><span class="keyword">explicit</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">xpath_query</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">query</span><span class="special">,</span> <span class="identifier">xpath_variable_set</span><span class="special">*</span> <span class="identifier">variables</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span>
-</pre>
-<a name="xpath_query::return_type"></a><p>
- The expression is compiled and the compiled representation is stored in the
- new query object. If compilation fails, <a class="link" href="xpath.html#xpath_exception">xpath_exception</a>
- is thrown if exception handling is not disabled (see <a class="xref" href="xpath.html#manual.xpath.errors" title="Error handling"> Error handling</a> for
- details). After the query is created, you can query the type of the evaluation
- result using the following function:
- </p>
-<pre class="programlisting"><span class="identifier">xpath_value_type</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">return_type</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<a name="xpath_query::evaluate_boolean"></a><a name="xpath_query::evaluate_number"></a><a name="xpath_query::evaluate_string"></a><a name="xpath_query::evaluate_node_set"></a><a name="xpath_query::evaluate_node"></a><p>
- You can evaluate the query using one of the following functions:
- </p>
-<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">evaluate_boolean</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="keyword">double</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">evaluate_number</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="identifier">string_t</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">evaluate_string</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="identifier">xpath_node_set</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">evaluate_node_set</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="identifier">xpath_node</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">evaluate_node</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- All functions take the context node as an argument, compute the expression
- and return the result, converted to the requested type. According to XPath
- specification, value of any type can be converted to boolean, number or string
- value, but no type other than node set can be converted to node set. Because
- of this, <code class="computeroutput"><span class="identifier">evaluate_boolean</span></code>,
- <code class="computeroutput"><span class="identifier">evaluate_number</span></code> and <code class="computeroutput"><span class="identifier">evaluate_string</span></code> always return a result,
- but <code class="computeroutput"><span class="identifier">evaluate_node_set</span></code> and
- <code class="computeroutput"><span class="identifier">evaluate_node</span></code> result in an
- error if the return type is not node set (see <a class="xref" href="xpath.html#manual.xpath.errors" title="Error handling"> Error handling</a>).
- </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>
- Calling <code class="computeroutput"><span class="identifier">node</span><span class="special">.</span><span class="identifier">select_nodes</span><span class="special">(</span><span class="string">"query"</span><span class="special">)</span></code>
- is equivalent to calling <code class="computeroutput"><span class="identifier">xpath_query</span><span class="special">(</span><span class="string">"query"</span><span class="special">).</span><span class="identifier">evaluate_node_set</span><span class="special">(</span><span class="identifier">node</span><span class="special">)</span></code>. Calling <code class="computeroutput"><span class="identifier">node</span><span class="special">.</span><span class="identifier">select_node</span><span class="special">(</span><span class="string">"query"</span><span class="special">)</span></code> is equivalent to calling <code class="computeroutput"><span class="identifier">xpath_query</span><span class="special">(</span><span class="string">"query"</span><span class="special">).</span><span class="identifier">evaluate_node</span><span class="special">(</span><span class="identifier">node</span><span class="special">)</span></code>.
- </p></td></tr>
-</table></div>
-<a name="xpath_query::evaluate_string_buffer"></a><p>
- Note that <code class="computeroutput"><span class="identifier">evaluate_string</span></code>
- function returns the STL string; as such, it's not available in <a class="link" href="install.html#PUGIXML_NO_STL">PUGIXML_NO_STL</a>
- mode and also usually allocates memory. There is another string evaluation
- function:
- </p>
-<pre class="programlisting"><span class="identifier">size_t</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">evaluate_string</span><span class="special">(</span><span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">size_t</span> <span class="identifier">capacity</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- This function evaluates the string, and then writes the result to <code class="computeroutput"><span class="identifier">buffer</span></code> (but at most <code class="computeroutput"><span class="identifier">capacity</span></code>
- characters); then it returns the full size of the result in characters, including
- the terminating zero. If <code class="computeroutput"><span class="identifier">capacity</span></code>
- is not 0, the resulting buffer is always zero-terminated. You can use this
- function as follows:
- </p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem">
- First call the function with <code class="computeroutput"><span class="identifier">buffer</span>
- <span class="special">=</span> <span class="number">0</span></code>
- and <code class="computeroutput"><span class="identifier">capacity</span> <span class="special">=</span>
- <span class="number">0</span></code>; then allocate the returned amount
- of characters, and call the function again, passing the allocated storage
- and the amount of characters;
- </li>
-<li class="listitem">
- First call the function with small buffer and buffer capacity; then,
- if the result is larger than the capacity, the output has been trimmed,
- so allocate a larger buffer and call the function again.
- </li>
-</ul></div>
-<p>
- This is an example of using query objects (<a href="../samples/xpath_query.cpp" target="_top">samples/xpath_query.cpp</a>):
- </p>
-<p>
-
-</p>
-<pre class="programlisting"><span class="comment">// Select nodes via compiled query
-</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_query</span> <span class="identifier">query_remote_tools</span><span class="special">(</span><span class="string">"/Profile/Tools/Tool[@AllowRemote='true']"</span><span class="special">);</span>
-
-<span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_node_set</span> <span class="identifier">tools</span> <span class="special">=</span> <span class="identifier">query_remote_tools</span><span class="special">.</span><span class="identifier">evaluate_node_set</span><span class="special">(</span><span class="identifier">doc</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">"Remote tool: "</span><span class="special">;</span>
-<span class="identifier">tools</span><span class="special">[</span><span class="number">2</span><span class="special">].</span><span class="identifier">node</span><span class="special">().</span><span class="identifier">print</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="comment">// Evaluate numbers via compiled query
-</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_query</span> <span class="identifier">query_timeouts</span><span class="special">(</span><span class="string">"sum(//Tool/@Timeout)"</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">query_timeouts</span><span class="special">.</span><span class="identifier">evaluate_number</span><span class="special">(</span><span class="identifier">doc</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">// Evaluate strings via compiled query for different context nodes
-</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_query</span> <span class="identifier">query_name_valid</span><span class="special">(</span><span class="string">"string-length(substring-before(@Filename, '_')) > 0 and @OutputFileMasks"</span><span class="special">);</span>
-<span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_query</span> <span class="identifier">query_name</span><span class="special">(</span><span class="string">"concat(substring-before(@Filename, '_'), ' produces ', @OutputFileMasks)"</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">doc</span><span class="special">.</span><span class="identifier">first_element_by_path</span><span class="special">(</span><span class="string">"Profile/Tools/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="special">{</span>
- <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">s</span> <span class="special">=</span> <span class="identifier">query_name</span><span class="special">.</span><span class="identifier">evaluate_string</span><span class="special">(</span><span class="identifier">tool</span><span class="special">);</span>
-
- <span class="keyword">if</span> <span class="special">(</span><span class="identifier">query_name_valid</span><span class="special">.</span><span class="identifier">evaluate_boolean</span><span class="special">(</span><span class="identifier">tool</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">s</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.xpath.variables"></a><a class="link" href="xpath.html#manual.xpath.variables" title="Using variables"> Using variables</a>
-</h3></div></div></div>
-<p>
- XPath queries may contain references to variables; this is useful if you
- want to use queries that depend on some dynamic parameter without manually
- preparing the complete query string, or if you want to reuse the same query
- object for similar queries.
- </p>
-<p>
- Variable references have the form <code class="computeroutput"><span class="identifier">$name</span></code>; in order to use them, you have to provide
- a variable set, which includes all variables present in the query with correct
- types. This set is passed to <code class="computeroutput"><span class="identifier">xpath_query</span></code>
- constructor or to <code class="computeroutput"><span class="identifier">select_nodes</span></code>/<code class="computeroutput"><span class="identifier">select_node</span></code> functions:
- </p>
-<pre class="programlisting"><span class="keyword">explicit</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">xpath_query</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">query</span><span class="special">,</span> <span class="identifier">xpath_variable_set</span><span class="special">*</span> <span class="identifier">variables</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span>
-<span class="identifier">xpath_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">select_node</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">query</span><span class="special">,</span> <span class="identifier">xpath_variable_set</span><span class="special">*</span> <span class="identifier">variables</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="identifier">xpath_node_set</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">select_nodes</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">query</span><span class="special">,</span> <span class="identifier">xpath_variable_set</span><span class="special">*</span> <span class="identifier">variables</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>
- If you're using query objects, you can change the variable values before
- <code class="computeroutput"><span class="identifier">evaluate</span></code>/<code class="computeroutput"><span class="identifier">select</span></code>
- calls to change the query behavior.
- </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>
- The variable set pointer is stored in the query object; you have to ensure
- that the lifetime of the set exceeds that of query object.
- </p></td></tr>
-</table></div>
-<a name="xpath_variable_set"></a><p>
- Variable sets correspond to <code class="computeroutput"><span class="identifier">xpath_variable_set</span></code>
- type, which is essentially a variable container.
- </p>
-<a name="xpath_variable_set::add"></a><p>
- You can add new variables with the following function:
- </p>
-<pre class="programlisting"><span class="identifier">xpath_variable</span><span class="special">*</span> <span class="identifier">xpath_variable_set</span><span class="special">::</span><span class="identifier">add</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="identifier">xpath_value_type</span> <span class="identifier">type</span><span class="special">);</span>
-</pre>
-<p>
- The function tries to add a new variable with the specified name and type;
- if the variable with such name does not exist in the set, the function adds
- a new variable and returns the variable handle; if there is already a variable
- with the specified name, the function returns the variable handle if variable
- has the specified type. Otherwise the function returns null pointer; it also
- returns null pointer on allocation failure.
- </p>
-<p>
- New variables are assigned the default value which depends on the type:
- <code class="computeroutput"><span class="number">0</span></code> for numbers, <code class="computeroutput"><span class="keyword">false</span></code> for booleans, empty string for strings
- and empty set for node sets.
- </p>
-<a name="xpath_variable_set::get"></a><p>
- You can get the existing variables with the following functions:
- </p>
-<pre class="programlisting"><span class="identifier">xpath_variable</span><span class="special">*</span> <span class="identifier">xpath_variable_set</span><span class="special">::</span><span class="identifier">get</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">xpath_variable</span><span class="special">*</span> <span class="identifier">xpath_variable_set</span><span class="special">::</span><span class="identifier">get</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>
- The functions return the variable handle, or null pointer if the variable
- with the specified name is not found.
- </p>
-<a name="xpath_variable_set::set"></a><p>
- Additionally, there are the helper functions for setting the variable value
- by name; they try to add the variable with the corresponding type, if it
- does not exist, and to set the value. If the variable with the same name
- but with different type is already present, they return <code class="computeroutput"><span class="keyword">false</span></code>;
- they also return <code class="computeroutput"><span class="keyword">false</span></code> on allocation
- failure. Note that these functions do not perform any type conversions.
- </p>
-<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xpath_variable_set</span><span class="special">::</span><span class="identifier">set</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">bool</span> <span class="identifier">value</span><span class="special">);</span>
-<span class="keyword">bool</span> <span class="identifier">xpath_variable_set</span><span class="special">::</span><span class="identifier">set</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">double</span> <span class="identifier">value</span><span class="special">);</span>
-<span class="keyword">bool</span> <span class="identifier">xpath_variable_set</span><span class="special">::</span><span class="identifier">set</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">value</span><span class="special">);</span>
-<span class="keyword">bool</span> <span class="identifier">xpath_variable_set</span><span class="special">::</span><span class="identifier">set</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">xpath_node_set</span><span class="special">&</span> <span class="identifier">value</span><span class="special">);</span>
-</pre>
-<p>
- The variable values are copied to the internal variable storage, so you can
- modify or destroy them after the functions return.
- </p>
-<a name="xpath_variable"></a><p>
- If setting variables by name is not efficient enough, or if you have to inspect
- variable information or get variable values, you can use variable handles.
- A variable corresponds to the <code class="computeroutput"><span class="identifier">xpath_variable</span></code>
- type, and a variable handle is simply a pointer to <code class="computeroutput"><span class="identifier">xpath_variable</span></code>.
- </p>
-<a name="xpath_variable::type"></a><a name="xpath_variable::name"></a><p>
- In order to get variable information, you can use one of 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">xpath_variable</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">xpath_value_type</span> <span class="identifier">xpath_variable</span><span class="special">::</span><span class="identifier">type</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- Note that each variable has a distinct type which is specified upon variable
- creation and can not be changed later.
- </p>
-<a name="xpath_variable::get_boolean"></a><a name="xpath_variable::get_number"></a><a name="xpath_variable::get_string"></a><a name="xpath_variable::get_node_set"></a><p>
- In order to get variable value, you should use one of the following functions,
- depending on the variable type:
- </p>
-<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xpath_variable</span><span class="special">::</span><span class="identifier">get_boolean</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="keyword">double</span> <span class="identifier">xpath_variable</span><span class="special">::</span><span class="identifier">get_number</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">xpath_variable</span><span class="special">::</span><span class="identifier">get_string</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="keyword">const</span> <span class="identifier">xpath_node_set</span><span class="special">&</span> <span class="identifier">xpath_variable</span><span class="special">::</span><span class="identifier">get_node_set</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- These functions return the value of the variable. Note that no type conversions
- are performed; if the type mismatch occurs, a dummy value is returned (<code class="computeroutput"><span class="keyword">false</span></code> for booleans, <code class="computeroutput"><span class="identifier">NaN</span></code>
- for numbers, empty string for strings and empty set for node sets).
- </p>
-<a name="xpath_variable::set"></a><p>
- In order to set variable value, you should use one of the following functions,
- depending on the variable type:
- </p>
-<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xpath_variable</span><span class="special">::</span><span class="identifier">set</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">value</span><span class="special">);</span>
-<span class="keyword">bool</span> <span class="identifier">xpath_variable</span><span class="special">::</span><span class="identifier">set</span><span class="special">(</span><span class="keyword">double</span> <span class="identifier">value</span><span class="special">);</span>
-<span class="keyword">bool</span> <span class="identifier">xpath_variable</span><span class="special">::</span><span class="identifier">set</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">value</span><span class="special">);</span>
-<span class="keyword">bool</span> <span class="identifier">xpath_variable</span><span class="special">::</span><span class="identifier">set</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node_set</span><span class="special">&</span> <span class="identifier">value</span><span class="special">);</span>
-</pre>
-<p>
- These functions modify the variable value. Note that no type conversions
- are performed; if the type mismatch occurs, the functions return <code class="computeroutput"><span class="keyword">false</span></code>; they also return <code class="computeroutput"><span class="keyword">false</span></code>
- on allocation failure. The variable values are copied to the internal variable
- storage, so you can modify or destroy them after the functions return.
- </p>
-<p>
- This is an example of using variables in XPath queries (<a href="../samples/xpath_variables.cpp" target="_top">samples/xpath_variables.cpp</a>):
- </p>
-<p>
-
-</p>
-<pre class="programlisting"><span class="comment">// Select nodes via compiled query
-</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_variable_set</span> <span class="identifier">vars</span><span class="special">;</span>
-<span class="identifier">vars</span><span class="special">.</span><span class="identifier">add</span><span class="special">(</span><span class="string">"remote"</span><span class="special">,</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_type_boolean</span><span class="special">);</span>
-
-<span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_query</span> <span class="identifier">query_remote_tools</span><span class="special">(</span><span class="string">"/Profile/Tools/Tool[@AllowRemote = string($remote)]"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">vars</span><span class="special">);</span>
-
-<span class="identifier">vars</span><span class="special">.</span><span class="identifier">set</span><span class="special">(</span><span class="string">"remote"</span><span class="special">,</span> <span class="keyword">true</span><span class="special">);</span>
-<span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_node_set</span> <span class="identifier">tools_remote</span> <span class="special">=</span> <span class="identifier">query_remote_tools</span><span class="special">.</span><span class="identifier">evaluate_node_set</span><span class="special">(</span><span class="identifier">doc</span><span class="special">);</span>
-
-<span class="identifier">vars</span><span class="special">.</span><span class="identifier">set</span><span class="special">(</span><span class="string">"remote"</span><span class="special">,</span> <span class="keyword">false</span><span class="special">);</span>
-<span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_node_set</span> <span class="identifier">tools_local</span> <span class="special">=</span> <span class="identifier">query_remote_tools</span><span class="special">.</span><span class="identifier">evaluate_node_set</span><span class="special">(</span><span class="identifier">doc</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">"Remote tool: "</span><span class="special">;</span>
-<span class="identifier">tools_remote</span><span class="special">[</span><span class="number">2</span><span class="special">].</span><span class="identifier">node</span><span class="special">().</span><span class="identifier">print</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">cout</span> <span class="special"><<</span> <span class="string">"Local tool: "</span><span class="special">;</span>
-<span class="identifier">tools_local</span><span class="special">[</span><span class="number">0</span><span class="special">].</span><span class="identifier">node</span><span class="special">().</span><span class="identifier">print</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="comment">// You can pass the context directly to select_nodes/select_node
-</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_node_set</span> <span class="identifier">tools_local_imm</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">select_nodes</span><span class="special">(</span><span class="string">"/Profile/Tools/Tool[@AllowRemote = string($remote)]"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">vars</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">"Local tool imm: "</span><span class="special">;</span>
-<span class="identifier">tools_local_imm</span><span class="special">[</span><span class="number">0</span><span class="special">].</span><span class="identifier">node</span><span class="special">().</span><span class="identifier">print</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">);</span>
-</pre>
-<p>
- </p>
-</div>
-<div class="section">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.xpath.errors"></a><a class="link" href="xpath.html#manual.xpath.errors" title="Error handling"> Error handling</a>
-</h3></div></div></div>
-<p>
- There are two different mechanisms for error handling in XPath implementation;
- the mechanism used depends on whether exception support is disabled (this
- is controlled with <a class="link" href="install.html#PUGIXML_NO_EXCEPTIONS">PUGIXML_NO_EXCEPTIONS</a>
- define).
- </p>
-<a name="xpath_exception"></a><a name="xpath_exception::result"></a><a name="xpath_exception::what"></a><p>
- By default, XPath functions throw <code class="computeroutput"><span class="identifier">xpath_exception</span></code>
- object in case of errors; additionally, in the event any memory allocation
- fails, an <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bad_alloc</span></code> exception is thrown. Also <code class="computeroutput"><span class="identifier">xpath_exception</span></code> is thrown if the query
- is evaluated to a node set, but the return type is not node set. If the query
- constructor succeeds (i.e. no exception is thrown), the query object is valid.
- Otherwise you can get the error details via one of the following functions:
- </p>
-<pre class="programlisting"><span class="keyword">virtual</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">xpath_exception</span><span class="special">::</span><span class="identifier">what</span><span class="special">()</span> <span class="keyword">const</span> <span class="keyword">throw</span><span class="special">();</span>
-<span class="keyword">const</span> <span class="identifier">xpath_parse_result</span><span class="special">&</span> <span class="identifier">xpath_exception</span><span class="special">::</span><span class="identifier">result</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<a name="xpath_query::unspecified_bool_type"></a><a name="xpath_query::result"></a><p>
- If exceptions are disabled, then in the event of parsing failure the query
- is initialized to invalid state; you can test if the query object is valid
- by using it in a boolean expression: <code class="computeroutput"><span class="keyword">if</span>
- <span class="special">(</span><span class="identifier">query</span><span class="special">)</span> <span class="special">{</span> <span class="special">...</span>
- <span class="special">}</span></code>. Additionally, you can get parsing
- result via the result() accessor:
- </p>
-<pre class="programlisting"><span class="keyword">const</span> <span class="identifier">xpath_parse_result</span><span class="special">&</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">result</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-</pre>
-<p>
- Without exceptions, evaluating invalid query results in <code class="computeroutput"><span class="keyword">false</span></code>,
- empty string, NaN or an empty node set, depending on the type; evaluating
- a query as a node set results in an empty node set if the return type is
- not node set.
- </p>
-<a name="xpath_parse_result"></a><p>
- The information about parsing result is returned via <code class="computeroutput"><span class="identifier">xpath_parse_result</span></code>
- object. It contains parsing status and the offset of last successfully parsed
- character from the beginning of the source stream:
- </p>
-<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">xpath_parse_result</span>
-<span class="special">{</span>
- <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">error</span><span class="special">;</span>
- <span class="identifier">ptrdiff_t</span> <span class="identifier">offset</span><span class="special">;</span>
-
- <span class="keyword">operator</span> <span class="keyword">bool</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
- <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">description</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
-<span class="special">};</span>
-</pre>
-<a name="xpath_parse_result::error"></a><p>
- Parsing result is represented as the error message; it is either a null pointer,
- in case there is no error, or the error message in the form of ASCII zero-terminated
- string.
- </p>
-<a name="xpath_parse_result::description"></a><p>
- <code class="computeroutput"><span class="identifier">description</span><span class="special">()</span></code>
- member function can be used to get the error message; it never returns the
- null pointer, so you can safely use <code class="computeroutput"><span class="identifier">description</span><span class="special">()</span></code> even if query parsing succeeded. Note that
- <code class="computeroutput"><span class="identifier">description</span><span class="special">()</span></code>
- returns a <code class="computeroutput"><span class="keyword">char</span></code> string even in
- <code class="computeroutput"><span class="identifier">PUGIXML_WCHAR_MODE</span></code>; you'll
- have to call <a class="link" href="dom.html#as_wide">as_wide</a> to get the <code class="computeroutput"><span class="keyword">wchar_t</span></code> string.
- </p>
-<a name="xpath_parse_result::offset"></a><p>
- In addition to the error message, parsing result has an <code class="computeroutput"><span class="identifier">offset</span></code>
- member, which contains the offset of last successfully parsed character.
- This offset is in units of <a class="link" href="dom.html#char_t">pugi::char_t</a> (bytes
- for character mode, wide characters for wide character mode).
- </p>
-<a name="xpath_parse_result::bool"></a><p>
- Parsing result object can be implicitly converted to <code class="computeroutput"><span class="keyword">bool</span></code>
- like this: <code class="computeroutput"><span class="keyword">if</span> <span class="special">(</span><span class="identifier">result</span><span class="special">)</span> <span class="special">{</span> <span class="special">...</span> <span class="special">}</span>
- <span class="keyword">else</span> <span class="special">{</span> <span class="special">...</span> <span class="special">}</span></code>.
- </p>
-<p>
- This is an example of XPath error handling (<a href="../samples/xpath_error.cpp" target="_top">samples/xpath_error.cpp</a>):
- </p>
-<p>
-
-</p>
-<pre class="programlisting"><span class="comment">// Exception is thrown for incorrect query syntax
-</span><span class="keyword">try</span>
-<span class="special">{</span>
- <span class="identifier">doc</span><span class="special">.</span><span class="identifier">select_nodes</span><span class="special">(</span><span class="string">"//nodes[#true()]"</span><span class="special">);</span>
-<span class="special">}</span>
-<span class="keyword">catch</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_exception</span><span class="special">&</span> <span class="identifier">e</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">"Select failed: "</span> <span class="special"><<</span> <span class="identifier">e</span><span class="special">.</span><span class="identifier">what</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="special">}</span>
-
-<span class="comment">// Exception is thrown for incorrect query semantics
-</span><span class="keyword">try</span>
-<span class="special">{</span>
- <span class="identifier">doc</span><span class="special">.</span><span class="identifier">select_nodes</span><span class="special">(</span><span class="string">"(123)/next"</span><span class="special">);</span>
-<span class="special">}</span>
-<span class="keyword">catch</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_exception</span><span class="special">&</span> <span class="identifier">e</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">"Select failed: "</span> <span class="special"><<</span> <span class="identifier">e</span><span class="special">.</span><span class="identifier">what</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="special">}</span>
-
-<span class="comment">// Exception is thrown for query with incorrect return type
-</span><span class="keyword">try</span>
-<span class="special">{</span>
- <span class="identifier">doc</span><span class="special">.</span><span class="identifier">select_nodes</span><span class="special">(</span><span class="string">"123"</span><span class="special">);</span>
-<span class="special">}</span>
-<span class="keyword">catch</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_exception</span><span class="special">&</span> <span class="identifier">e</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">"Select failed: "</span> <span class="special"><<</span> <span class="identifier">e</span><span class="special">.</span><span class="identifier">what</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="special">}</span>
-</pre>
-<p>
- </p>
-</div>
-<div class="section">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.xpath.w3c"></a><a class="link" href="xpath.html#manual.xpath.w3c" title="Conformance to W3C specification"> Conformance to W3C specification</a>
-</h3></div></div></div>
-<p>
- Because of the differences in document object models, performance considerations
- and implementation complexity, pugixml does not provide a fully conformant
- XPath 1.0 implementation. This is the current list of incompatibilities:
- </p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem">
- Consecutive text nodes sharing the same parent are not merged, i.e. in
- <code class="computeroutput"><span class="special"><</span><span class="identifier">node</span><span class="special">></span><span class="identifier">text1</span>
- <span class="special"><![</span><span class="identifier">CDATA</span><span class="special">[</span><span class="identifier">data</span><span class="special">]]></span> <span class="identifier">text2</span><span class="special"></</span><span class="identifier">node</span><span class="special">></span></code> node should have one text node child,
- but instead has three.
- </li>
-<li class="listitem">
- Since the document type declaration is not used for parsing, <code class="computeroutput"><span class="identifier">id</span><span class="special">()</span></code>
- function always returns an empty node set.
- </li>
-<li class="listitem">
- Namespace nodes are not supported (affects namespace:: axis).
- </li>
-<li class="listitem">
- Name tests are performed on QNames in XML document instead of expanded
- names; for <code class="computeroutput"><span class="special"><</span><span class="identifier">foo</span>
- <span class="identifier">xmlns</span><span class="special">:</span><span class="identifier">ns1</span><span class="special">=</span><span class="char">'uri'</span> <span class="identifier">xmlns</span><span class="special">:</span><span class="identifier">ns2</span><span class="special">=</span><span class="char">'uri'</span><span class="special">><</span><span class="identifier">ns1</span><span class="special">:</span><span class="identifier">child</span><span class="special">/><</span><span class="identifier">ns2</span><span class="special">:</span><span class="identifier">child</span><span class="special">/></</span><span class="identifier">foo</span><span class="special">></span></code>,
- query <code class="computeroutput"><span class="identifier">foo</span><span class="special">/</span><span class="identifier">ns1</span><span class="special">:*</span></code>
- will return only the first child, not both of them. Compliant XPath implementations
- can return both nodes if the user provides appropriate namespace declarations.
- </li>
-<li class="listitem">
- String functions consider a character to be either a single <code class="computeroutput"><span class="keyword">char</span></code> value or a single <code class="computeroutput"><span class="keyword">wchar_t</span></code>
- value, depending on the library configuration; this means that some string
- functions are not fully Unicode-aware. This affects <code class="computeroutput"><span class="identifier">substring</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">string</span><span class="special">-</span><span class="identifier">length</span><span class="special">()</span></code> and <code class="computeroutput"><span class="identifier">translate</span><span class="special">()</span></code> functions.
- </li>
-</ul></div>
-</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.6</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> · <a href="access.html">Accessing</a> · <a href="modify.html">Modifying</a> · <a href="saving.html">Saving</a> |
- <b>XPath</b> |
- <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="saving.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="changes.html"><img src="../images/next.png" alt="Next"></a>
-</div></td>
-</tr></table>
-</body>
-</html>
--
cgit v1.2.3