Accessing document data

parent function returns the - node's parent; all nodes except the document have non-null parent. first_child and last_child - return the first and last child of the node, respectively; note that only - document nodes and element nodes can have non-empty child node list. If node - has no children, both functions return null nodes. next_sibling + node's parent; all non-null nodes except the document have non-null parent. + first_child and last_child return the first and last child + of the node, respectively; note that only document nodes and element nodes + can have non-empty child node list. If node has no children, both functions + return null nodes. next_sibling and previous_sibling return the node that's immediately to the right/left of this node in the children list, respectively - for example, in <a/><b/><c/>, @@ -93,9 +95,9 @@ results in handle pointing to <a/>. If node does not have next/previous sibling (this happens if it is the last/first node in the list, respectively), the functions return null nodes. first_attribute, last_attribute, - next_attribute and previous_attribute functions behave the - same way as corresponding child node functions and allow to iterate through - attribute list in the same way. + next_attribute and previous_attribute functions behave similarly + to the corresponding child node functions and allow to iterate through attribute + list in the same way.

@@ -111,7 +113,8 @@ Calling any of the functions above on the null handle results in a null handle - i.e. node.first_child().next_sibling() returns the second child of node, - and null handle if there is no children at all or if there is only one. + and null handle if node is + null, has no children at all or if it has only one child node.

With these functions, you can iterate through all child nodes and display @@ -142,12 +145,13 @@

Apart from structural information (parent, child nodes, attributes), nodes can have name and value, both of which are strings. Depending on node type, - name or value may be absent. node_document - nodes do not have name or value, node_element - and node_declaration nodes - always have a name but never have a value, node_pcdata, - node_cdata and node_comment nodes never have a name but - always have a value (it may be empty though), node_pi + name or value may be absent. node_document + nodes do not have a name or value, node_element + and node_declaration nodes always + have a name but never have a value, node_pcdata, + node_cdata, node_comment + and node_doctype nodes never have a name + but always have a value (it may be empty though), node_pi nodes always have a name and a value (again, value may be empty). In order to get node's name or value, you can use the following functions:

@@ -161,18 +165,18 @@

It is common to store data as text contents of some node - i.e. <node><description>This is a node</description></node>. In this case, <description> node does not have a value, but instead - has a child of type node_pcdata - with value "This is a node". - pugixml provides two helper functions to parse such data: + has a child of type node_pcdata with value + "This is a node". pugixml + provides two helper functions to parse such data:

const char_t* xml_node::child_value() const;
 const char_t* xml_node::child_value(const char_t* name) const;

child_value() - returns the value of the first child with type node_pcdata - or node_cdata; child_value(name) is - a simple wrapper for child(name).child_value(). + returns the value of the first child with type node_pcdata + or node_cdata; child_value(name) + is a simple wrapper for child(name).child_value(). For the above example, calling node.child_value("description") and description.child_value() will both produce string "This is a node". If there is no child with relevant type, or if the handle is null, child_value functions return empty string. @@ -194,15 +198,14 @@ const char_t* xml_attribute::value() const;

- In case attribute handle is null, both functions return empty strings - they - never return null pointers. + In case the attribute handle is null, both functions return empty strings + - they never return null pointers.

In many cases attribute values have types that are not strings - i.e. an attribute may always contain values that should be treated as integers, despite the fact that they are represented as strings in XML. pugixml provides several - accessors that convert attribute value to some other type. The accessors - are as follows: + accessors that convert attribute value to some other type:

int xml_attribute::as_int() const;
 unsigned int xml_attribute::as_uint() const;
@@ -241,7 +244,7 @@
         value to boolean as follows: if attribute handle is null or attribute value
         is empty, false is returned.
         Otherwise, true is returned
-        if first character is one of '1', 't',
+        if the first character is one of '1', 't',
         'T', 'y', 'Y'.
         This means that strings like "true"
         and "yes" are recognized
@@ -370,11 +373,11 @@
         return past-the-end iterator for node/attribute list, respectively - this
         iterator can't be dereferenced, but decrementing it results in an iterator
         pointing to the last element in the list (except for empty lists, where decrementing
-        past-the-end iterator is not defined). Past-the-end iterator is commonly
-        used as a termination value for iteration loops (see sample below). If you
-        want to get an iterator that points to an existing handle, you can construct
-        the iterator with the handle as a single constructor argument, like so:
-        xml_node_iterator(node).
+        past-the-end iterator results in undefined behavior). Past-the-end iterator
+        is commonly used as a termination value for iteration loops (see sample below).
+        If you want to get an iterator that points to an existing handle, you can
+        construct the iterator with the handle as a single constructor argument,
+        like so: xml_node_iterator(node).
         For xml_attribute_iterator,
         you'll have to provide both an attribute and its parent node.
       
@@ -527,7 +530,7 @@
 
         While there are existing functions for getting a node/attribute with known
         contents, they are often not sufficient for simple queries. As an alternative
-        to iterating manually through nodes/attributes until the needed one is found,
+        for manual iteration through nodes/attributes until the needed one is found,
         you can make a predicate and call one of find_
         functions:
       
@@ -546,24 +549,24 @@
 
         find_attribute function iterates
         through all attributes of the specified node, and returns the first attribute
-        for which predicate returned true.
-        If predicate returned false
+        for which the predicate returned true.
+        If the predicate returned false
         for all attributes or if there were no attributes (including the case where
         the node is null), null attribute is returned.
       
 
         find_child function iterates
         through all child nodes of the specified node, and returns the first node
-        for which predicate returned true.
-        If predicate returned false
+        for which the predicate returned true.
+        If the predicate returned false
         for all nodes or if there were no child nodes (including the case where the
         node is null), null node is returned.
       
 
         find_node function performs
         a depth-first traversal through the subtree of the specified node (excluding
-        the node itself), and returns the first node for which predicate returned
-        true. If predicate returned
+        the node itself), and returns the first node for which the predicate returned
+        true. If the predicate returned
         false for all nodes or if subtree
         was empty, null node is returned.
       
@@ -622,11 +625,9 @@
 xml_node xml_node::root() const;
 
 
-        This function returns the node with type node_document,
+        This function returns the node with type node_document,
         which is the root node of the document the node belongs to (unless the node
-        is null, in which case null node is returned). Currently this function has
-        logarithmic complexity, since it simply finds such ancestor of the given
-        node which itself has no parent.
+        is null, in which case null node is returned).
       
 
         While pugixml supports complex XPath expressions, sometimes a simple path
@@ -643,9 +644,9 @@
         path returns the path to
         the node from the document root, first_element_by_path
         looks for a node represented by a given path; a path can be an absolute one
-        (absolute paths start with delimiter), in which case the rest of the path
-        is treated as document root relative, and relative to the given node. For
-        example, in the following document: <a><b><c/></b></a>,
+        (absolute paths start with the delimiter), in which case the rest of the
+        path is treated as document root relative, and relative to the given node.
+        For example, in the following document: <a><b><c/></b></a>,
         node <c/> has path "a/b/c";
         calling first_element_by_path
         for document with path "a/b"
@@ -672,7 +673,7 @@

path function returns the - result as STL string, and thus is not available if PUGIXML_NO_STL + result as STL string, and thus is not available if PUGIXML_NO_STL is defined.