XPath

- 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 @@ -72,11 +73,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: @@ -101,30 +102,33 @@ 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: @@ -133,8 +137,9 @@ 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;
@@ -147,9 +152,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;
@@ -173,9 +178,10 @@
         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;
 
@@ -187,10 +193,11 @@
         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);
@@ -205,11 +212,12 @@

- 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_set xml_node::select_nodes(const char_t* query, xpath_variable_set* variables = 0) const;
@@ -228,15 +236,15 @@
 
         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_set xml_node::select_nodes(const xpath_query& query) const;
@@ -249,36 +257,36 @@
         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']");
 
-std::cout << "Tools:";
+std::cout << "Tools:\n";
 
 for (pugi::xpath_node_set::const_iterator it = tools.begin(); it != tools.end(); ++it)
 {
     pugi::xpath_node node = *it;
-    std::cout << " " << node.node().attribute("Filename").value();
+    std::cout << node.node().attribute("Filename").value() << "\n";
 }
 
 pugi::xpath_node build_tool = doc.select_single_node("//Tool[contains(Description, 'build system')]");
 
-std::cout << "\nBuild tool: " << build_tool.node().attribute("Filename").value() << "\n";
+if (build_tool)
+    std::cout << "Build tool: " << build_tool.node().attribute("Filename").value() << "\n";

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

-

You can precompile expressions to query objects to save compilation time if it becomes an issue; @@ -299,23 +307,25 @@ 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;
@@ -330,7 +340,7 @@
         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).
+        in an error if the return type is not node set (see Error handling).
       
 
@@ -342,9 +352,9 @@
           is equivalent to calling xpath_query("query").evaluate_node_set(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:
       
@@ -357,7 +367,7 @@
         is not 0, the resulting buffer is always zero-terminated. You can use this
         function as follows:
       
-
+
 
             First call the function with buffer
             = 0
@@ -376,21 +386,20 @@
         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())
@@ -405,7 +414,7 @@
 
 
 
- Using variables
+Using variables
 
 
         XPath queries may contain references to variables; this is useful if you
@@ -438,12 +447,13 @@
           that the lifetime of the set exceeds that of query object.

- Conformance to W3C specification +Conformance to W3C specification

- 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