XPath

-XPath + XPath

XPath types
Selecting nodes via XPath expression
Using query objects
Using variables
Error handling
Conformance to W3C specification
XPath types
Selecting nodes via XPath expression
Using query objects
Using variables
Error handling
Conformance to W3C specification

If the task at hand is to select a subset of document nodes that match some @@ -48,7 +48,7 @@ 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 Conformance to W3C specification. The rest of this section describes the interface for XPath + in Conformance to W3C specification. 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 W3Schools XPath tutorial, @@ -58,12 +58,11 @@

-XPath types + XPath types

- Each - XPath expression can have one of the following types: boolean, number, string - or node set. Boolean type corresponds to bool +

+ Each XPath expression can have one of the following types: boolean, number, + string or node set. Boolean type corresponds to bool type, number type corresponds to double type, string type corresponds to either std::string or std::wstring, depending on whether wide @@ -73,11 +72,11 @@ xpath_type_number, xpath_type_string or xpath_type_node_set, accordingly.

- Because an XPath node can be either a node or an - attribute, there is a special type, xpath_node, - which is a discriminated union of these types. A value of this type contains - two node handles, one of xml_node +

+ Because an XPath node can be either a node or an attribute, there is a special + type, xpath_node, which is + a discriminated union of these types. A value of this type contains two node + handles, one of xml_node type, and another one of xml_attribute type; at most one of them can be non-null. The accessors to get these handles are available: @@ -102,33 +101,30 @@ handle. For null nodes, parent returns null handle.

- 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 +

+ 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.

- 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 xml_node - is implicit, so you can usually pass xml_node - to functions that expect xpath_node. - Apart from that you usually don't need to create your own XPath node objects, - since they are returned to you via selection functions. -

- 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. -

- Node sets are represented by xpath_node_set +

+ 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 xml_node is implicit, so you can usually + pass xml_node to functions + that expect xpath_node. Apart + from that you usually don't need to create your own XPath node objects, since + they are returned to you via selection functions. +

+ 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. +

+ Node sets are represented by xpath_node_set 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: @@ -137,9 +133,8 @@ const_iterator xpath_node_set::begin() const; const_iterator xpath_node_set::end() const; -

- And it also can be iterated via indices, just - like std::vector: +

+ And it also can be iterated via indices, just like std::vector:

const xpath_node& xpath_node_set::operator[](size_t index) const;
 size_t xpath_node_set::size() const;
@@ -152,9 +147,9 @@
         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.
       
-
-        The order of iteration depends on the order of
-        nodes inside the set; the order can be queried via the following function:
+

+        The order of iteration depends on the order of nodes inside the set; the
+        order can be queried via the following function:
       
 enum xpath_node_set::type_t {type_unsorted, type_sorted, type_sorted_reverse};
 type_t xpath_node_set::type() const;
@@ -178,10 +173,9 @@
         will return type_sorted or
         type_sorted_reverse.
       
-
-        Often the actual iteration is not needed;
-        instead, only the first element in document order is required. For this,
-        a special accessor is provided:
+

+        Often the actual iteration is not needed; instead, only the first element
+        in document order is required. For this, a special accessor is provided:
       
 xpath_node xpath_node_set::first() const;
 
@@ -193,11 +187,10 @@
         the complexity does - if the set is sorted, the complexity is constant, otherwise
         it is linear in the number of elements or worse.
       
-
-        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 (const_iterator
+

+        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 (const_iterator
         is a typedef for const xpath_node*), and an optional type:
       
 xpath_node_set::xpath_node_set(const_iterator begin, const_iterator end, type_t type = type_unsorted);
@@ -212,41 +205,40 @@

-Selecting nodes via XPath expression + Selecting nodes via XPath expression

- If - you want to select nodes that match some XPath expression, you can do it - with the following functions: +

+ If you want to select nodes that match some XPath expression, you can do + it with the following functions:

xpath_node xml_node::select_single_node(const char_t* query, xpath_variable_set* variables = 0) const;
+xpath_node xml_node::select_node(const char_t* query, xpath_variable_set* variables = 0) const;
 xpath_node_set xml_node::select_nodes(const char_t* query, xpath_variable_set* variables = 0) const;
 
 
         select_nodes function compiles
         the expression and then executes it with the node as a context node, and
-        returns the resulting node set. select_single_node
+        returns the resulting node set. select_node
         returns only the first node in document order from the result, and is equivalent
         to calling select_nodes(query).first().
         If the XPath expression does not match anything, or the node handle is null,
         select_nodes returns an empty
-        set, and select_single_node
-        returns null XPath node.
+        set, and select_node returns
+        null XPath node.
       
 
         If exception handling is not disabled, both functions throw xpath_exception
         if the query can not be compiled or if it returns a value with type other
-        than node set; see Error handling for details.
+        than node set; see  Error handling for details.
       
-
-        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 Using query objects for further reference). Once you get a compiled query
-        object, you can pass it to select functions instead of an expression string:
+

+        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  Using query objects for further reference). Once you get a compiled
+        query object, you can pass it to select functions instead of an expression
+        string:
       
-xpath_node xml_node::select_single_node(const xpath_query& query) const;
+xpath_node xml_node::select_node(const xpath_query& query) const;
 xpath_node_set xml_node::select_nodes(const xpath_query& query) const;
 
 
@@ -257,6 +249,7 @@
         This is an example of selecting nodes using XPath expressions (samples/xpath_select.cpp):
       
 
+        
 
 pugi::xpath_node_set tools = doc.select_nodes("/Profile/Tools/Tool[@AllowRemote='true' and @DeriveCaptionFrom='lastparam']");
 
@@ -268,7 +261,7 @@
     std::cout << node.node().attribute("Filename").value() << "\n";
 }
 
-pugi::xpath_node build_tool = doc.select_single_node("//Tool[contains(Description, 'build system')]");
+pugi::xpath_node build_tool = doc.select_node("//Tool[contains(Description, 'build system')]");
 
 if (build_tool)
     std::cout << "Build tool: " << build_tool.node().attribute("Filename").value() << "\n";
@@ -278,10 +271,10 @@

-Using query objects + Using query objects

- When you call select_nodes +

+ When you call select_nodes 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: @@ -307,30 +300,29 @@ operator and store pointers to xpath_query in the container.

- You can create a query object with the constructor - that takes XPath expression as an argument: +

+ You can create a query object with the constructor that takes XPath expression + as an argument:

explicit xpath_query::xpath_query(const char_t* query, xpath_variable_set* variables = 0);

- The expression is compiled and the - compiled representation is stored in the new query object. If compilation - fails, xpath_exception is thrown if - exception handling is not disabled (see Error handling for details). - After the query is created, you can query the type of the evaluation result - using the following function: +

+ The expression is compiled and the compiled representation is stored in the + new query object. If compilation fails, xpath_exception + is thrown if exception handling is not disabled (see Error handling for + details). After the query is created, you can query the type of the evaluation + result using the following function:

xpath_value_type xpath_query::return_type() const;

- You - can evaluate the query using one of the following functions: +

+ You can evaluate the query using one of the following functions:

bool xpath_query::evaluate_boolean(const xpath_node& n) const;
 double xpath_query::evaluate_number(const xpath_node& n) const;
 string_t xpath_query::evaluate_string(const xpath_node& n) const;
 xpath_node_set xpath_query::evaluate_node_set(const xpath_node& n) const;
+xpath_node xpath_query::evaluate_node(const xpath_node& n) const;

All functions take the context node as an argument, compute the expression @@ -339,8 +331,9 @@ value, but no type other than node set can be converted to node set. Because of this, evaluate_boolean, evaluate_number and evaluate_string always return a result, - but evaluate_node_set results - in an error if the return type is not node set (see Error handling). + but evaluate_node_set and + evaluate_node result in an + error if the return type is not node set (see Error handling).

@@ -349,12 +342,12 @@

Calling node.select_nodes("query") - is equivalent to calling xpath_query("query").evaluate_node_set(node). + is equivalent to calling xpath_query("query").evaluate_node_set(node). Calling node.select_node("query") is equivalent to calling xpath_query("query").evaluate_node(node).

- Note that evaluate_string function returns the STL - string; as such, it's not available in PUGIXML_NO_STL +

+ Note that evaluate_string + function returns the STL string; as such, it's not available in PUGIXML_NO_STL mode and also usually allocates memory. There is another string evaluation function:

@@ -386,20 +379,21 @@ This is an example of using query objects (samples/xpath_query.cpp):

// Select nodes via compiled query
-pugi::xpath_query query_remote_tools("/Profile/Tools/Tool[@AllowRemote='true']");
+// Select nodes via compiled query
+pugi::xpath_query query_remote_tools("/Profile/Tools/Tool[@AllowRemote='true']");
 
 pugi::xpath_node_set tools = query_remote_tools.evaluate_node_set(doc);
 std::cout << "Remote tool: ";
 tools[2].node().print(std::cout);
 
-// Evaluate numbers via compiled query
-pugi::xpath_query query_timeouts("sum(//Tool/@Timeout)");
+// Evaluate numbers via compiled query
+pugi::xpath_query query_timeouts("sum(//Tool/@Timeout)");
 std::cout << query_timeouts.evaluate_number(doc) << std::endl;
 
-// Evaluate strings via compiled query for different context nodes
-pugi::xpath_query query_name_valid("string-length(substring-before(@Filename, '_')) > 0 and @OutputFileMasks");
+// Evaluate strings via compiled query for different context nodes
+pugi::xpath_query query_name_valid("string-length(substring-before(@Filename, '_')) > 0 and @OutputFileMasks");
 pugi::xpath_query query_name("concat(substring-before(@Filename, '_'), ' produces ', @OutputFileMasks)");
 
 for (pugi::xml_node tool = doc.first_element_by_path("Profile/Tools/Tool"); tool; tool = tool.next_sibling())
@@ -414,7 +408,7 @@

-Using variables + Using variables

XPath queries may contain references to variables; this is useful if you @@ -426,10 +420,10 @@ Variable references have the form $name; 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 xpath_query - constructor or to select_nodes/select_single_node functions: + constructor or to select_nodes/select_node functions:

explicit xpath_query::xpath_query(const char_t* query, xpath_variable_set* variables = 0);
-xpath_node xml_node::select_single_node(const char_t* query, xpath_variable_set* variables = 0) const;
+xpath_node xml_node::select_node(const char_t* query, xpath_variable_set* variables = 0) const;
 xpath_node_set xml_node::select_nodes(const char_t* query, xpath_variable_set* variables = 0) const;

@@ -447,13 +441,12 @@ that the lifetime of the set exceeds that of query object.

-XPath + XPath

-XPath types + XPath types

-Selecting nodes via XPath expression + Selecting nodes via XPath expression

-Using query objects + Using query objects

-Using variables + Using variables

-Error handling + Error handling

-Conformance to W3C specification + Conformance to W3C specification