Accessing document data

Date: Tue, 18 Nov 2014 09:30:19 -0800 Subject: docs: Regenerated documentation Also fix documentation jam rules for Windows. --- docs/manual/access.html | 293 +++++++++++++++++++++++------------------------- 1 file changed, 143 insertions(+), 150 deletions(-) (limited to 'docs/manual/access.html') diff --git a/docs/manual/access.html b/docs/manual/access.html index 4d4e9c2..8942a26 100644 --- a/docs/manual/access.html +++ b/docs/manual/access.html @@ -4,15 +4,15 @@ Accessing document data - - + +

-pugixml 1.4 manual | +pugixml 1.5 manual | Overview | Installation | Document: @@ -28,27 +28,27 @@

-Accessing document data + Accessing document data

pugixml features an extensive interface for getting various types of data from the document and for traversing the document. This section provides documentation for all such functions that do not modify the tree except for XPath-related - functions; see XPath for XPath reference. As discussed in C++ interface, + functions; see XPath for XPath reference. As discussed in C++ interface, there are two types of handles to tree data - xml_node and xml_attribute. The handles have special null (empty) values which propagate through various functions and thus are @@ -58,12 +58,11 @@

-Basic traversal functions + Basic traversal functions

- The - internal representation of the document is a tree, where each node has a - list of child nodes (the order of children corresponds to their order in +

+ The internal representation of the document is a tree, where each node has + a list of child nodes (the order of children corresponds to their order in the XML representation), and additionally element nodes have a list of attributes, which is also ordered. Several functions are provided in order to let you get from one node in the tree to the other. These functions roughly correspond @@ -124,6 +123,7 @@ all attributes like this (samples/traverse_base.cpp):

for (pugi::xml_node tool = tools.first_child(); tool; tool = tool.next_sibling())
 {
@@ -142,15 +142,15 @@

-Getting node data + Getting node data

- 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 a name - or value, node_element and node_declaration - nodes always have a name but never have a value, node_pcdata, +

+ 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 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 @@ -164,9 +164,8 @@ In case node does not have a name or value or if the node handle is null, both functions return empty strings - they never return null pointers.

- It is common to store data as text contents - of some node - i.e. <node><description>This is a node</description></node>. +

+ 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 @@ -189,7 +188,7 @@ text() returns a special object that can be used for working with PCDATA contents in more complex cases than just retrieving the value; it is described in - Working with text contents sections. + Working with text contents sections.

There is an example of using some of these functions at @@ -198,12 +197,11 @@

-Getting attribute data + Getting attribute data

- All - attributes have name and value, both of which are strings (value may be empty). - There are two corresponding accessors, like for xml_node: +

+ All attributes have name and value, both of which are strings (value may + be empty). There are two corresponding accessors, like for xml_node:

const char_t* xml_attribute::name() const;
 const char_t* xml_attribute::value() const;
@@ -212,12 +210,12 @@
         In case the attribute handle is null, both functions return empty strings
         - they never return null pointers.
       
-
-        If you need a non-empty string if
-        the attribute handle is null (for example, you need to get the option value
-        from XML attribute, but if it is not specified, you need it to default to
-        "sorted" instead of
-        ""), you can use as_string accessor:
+

+        If you need a non-empty string if the attribute handle is null (for example,
+        you need to get the option value from XML attribute, but if it is not specified,
+        you need it to default to "sorted"
+        instead of ""), you
+        can use as_string accessor:
       
 const char_t* xml_attribute::as_string(const char_t* def = "") const;
 
@@ -226,12 +224,11 @@
         the attribute handle is null. If you do not specify the argument, the function
         is equivalent to value().
       
-
-        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:
+

+        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:
       
 int xml_attribute::as_int(int def = 0) const;
 unsigned int xml_attribute::as_uint(unsigned int def = 0) const;
@@ -296,11 +293,12 @@
           long type, including string conversions.

- This is an example of using these functions, - along with node data retrieval ones (samples/traverse_base.cpp): +

+ This is an example of using these functions, along with node data retrieval + ones (samples/traverse_base.cpp):

for (pugi::xml_node tool = tools.child("Tool"); tool; tool = tool.next_sibling("Tool"))
 {
@@ -315,12 +313,11 @@
 
 
 
-Contents-based traversal functions
+ Contents-based traversal functions
 
-
-        Since a lot of document traversal consists
-        of finding the node/attribute with the correct name, there are special functions
-        for that purpose:
+

+        Since a lot of document traversal consists of finding the node/attribute
+        with the correct name, there are special functions for that purpose:
       
 xml_node xml_node::child(const char_t* name) const;
 xml_attribute xml_node::attribute(const char_t* name) const;
@@ -342,15 +339,11 @@
       
 for (pugi::xml_node tool = tools.child("Tool"); tool; tool = tool.next_sibling("Tool"))
 
-
-        Occasionally the needed node
-        is specified not by the unique name but instead by the value of some attribute;
-        for example, it is common to have node collections with each node having
-        a unique id: <group><item
-        id="1"/>
-        <item
-        id="2"/></group>.
-        There are two functions for finding child nodes based on the attribute values:
+

+        Occasionally the needed node is specified not by the unique name but instead
+        by the value of some attribute; for example, it is common to have node collections
+        with each node having a unique id: <group><item id="1"/> <item id="2"/></group>. There are two functions for finding
+        child nodes based on the attribute values:
       
 xml_node xml_node::find_child_by_attribute(const char_t* name, const char_t* attr_name, const char_t* attr_value) const;
 xml_node xml_node::find_child_by_attribute(const char_t* attr_name, const char_t* attr_value) const;
@@ -370,6 +363,7 @@
         This is an example of using these functions (samples/traverse_base.cpp):
       
 
+        
 
 std::cout << "Tool for *.dae generation: " << tools.find_child_by_attribute("Tool", "OutputFileMasks", "*.dae").attribute("Filename").value() << "\n";
 
@@ -383,13 +377,12 @@
 
 
 
-Range-based for-loop support
+ Range-based for-loop support
 
-
-        If your
-        C++ compiler supports range-based for-loop (this is a C++11 feature, at the
-        time of writing it's supported by Microsoft Visual Studio 11 Beta, GCC 4.6
-        and Clang 3.0), you can use it to enumerate nodes/attributes. Additional
+

+        If your C++ compiler supports range-based for-loop (this is a C++11 feature,
+        at the time of writing it's supported by Microsoft Visual Studio 11 Beta,
+        GCC 4.6 and Clang 3.0), you can use it to enumerate nodes/attributes. Additional
         helpers are provided to support this; note that they are also compatible
         with Boost Foreach,
         and possibly other pre-C++11 foreach facilities.
@@ -410,6 +403,7 @@
         This is an example of using these functions (samples/traverse_rangefor.cpp):
       
 
+        
 
 for (pugi::xml_node tool: tools.children("Tool"))
 {
@@ -433,12 +427,12 @@
 
 
 
-Traversing node/attribute lists
+ Traversing node/attribute lists
       via iterators
 
-
-        Child node lists and attribute lists are simply
-        double-linked lists; while you can use previous_sibling/next_sibling and other such functions for
+

+        Child node lists and attribute lists are simply double-linked lists; while
+        you can use previous_sibling/next_sibling and other such functions for
         iteration, pugixml additionally provides node and attribute iterators, so
         that you can treat nodes as containers of other nodes or attributes:
       
@@ -486,6 +480,7 @@
         Here is an example of using iterators for document traversal (samples/traverse_iter.cpp):
       
 
+        
 
 for (pugi::xml_node_iterator it = tools.begin(); it != tools.end(); ++it)
 {
@@ -518,14 +513,14 @@
 
 
 
-Recursive traversal with xml_tree_walker
+ Recursive traversal with xml_tree_walker
 
-
-        The methods described above allow traversal
-        of immediate children of some node; if you want to do a deep tree traversal,
-        you'll have to do it via a recursive function or some equivalent method.
-        However, pugixml provides a helper for depth-first traversal of a subtree.
-        In order to use it, you have to implement xml_tree_walker
+

+        The methods described above allow traversal of immediate children of some
+        node; if you want to do a deep tree traversal, you'll have to do it via a
+        recursive function or some equivalent method. However, pugixml provides a
+        helper for depth-first traversal of a subtree. In order to use it, you have
+        to implement xml_tree_walker
         interface and to call traverse
         function:
       
@@ -541,9 +536,8 @@
 
 bool xml_node::traverse(xml_tree_walker& walker);

- The traversal - is launched by calling traverse +

+ The traversal is launched by calling traverse function on traversal root and proceeds as follows:

begin

end

true

- You can get the node's depth relative - to the traversal root at any point by calling depth - function. It returns -1 +

+ You can get the node's depth relative to the traversal root at any point + by calling depth function. + It returns -1 if called from begin/end, and returns 0-based depth if called from for_each - depth is 0 for all children of the traversal root, 1 for all grandchildren and so @@ -583,22 +577,24 @@ This is an example of traversing tree hierarchy with xml_tree_walker (samples/traverse_walker.cpp):

struct simple_walker: pugi::xml_tree_walker
 {
     virtual bool for_each(pugi::xml_node& node)
     {
-        for (int i = 0; i < depth(); ++i) std::cout << "  "; // indentation
-
+        for (int i = 0; i < depth(); ++i) std::cout << "  "; // indentation
+
         std::cout << node_types[node.type()] << ": name='" << node.name() << "', value='" << node.value() << "'\n";
 
-        return true; // continue traversal
-    }
+        return true; // continue traversal
+    }
 };

simple_walker walker;
 doc.traverse(walker);
@@ -608,15 +604,15 @@

-Searching for nodes/attributes + Searching for nodes/attributes with predicates

- While there are existing functions for getting - a node/attribute with known contents, they are often not sufficient for simple - queries. As an alternative for manual iteration through nodes/attributes - until the needed one is found, you can make a predicate and call one of - find_ functions: +

+ While there are existing functions for getting a node/attribute with known + contents, they are often not sufficient for simple queries. As an alternative + for manual iteration through nodes/attributes until the needed one is found, + you can make a predicate and call one of find_ + functions:

template <typename Predicate> xml_attribute xml_node::find_attribute(Predicate pred) const;
 template <typename Predicate> xml_node xml_node::find_child(Predicate pred) const;
@@ -658,6 +654,7 @@
         This is an example of using predicate-based functions (samples/traverse_predicate.cpp):
       
 
+        
 
 bool small_timeout(pugi::xml_node node)
 {
@@ -680,29 +677,29 @@
 
       
 
+        
 
-// Find child via predicate (looks for direct children only)
-std::cout << tools.find_child(allow_remote_predicate()).attribute("Filename").value() << std::endl;
+// Find child via predicate (looks for direct children only)
+std::cout << tools.find_child(allow_remote_predicate()).attribute("Filename").value() << std::endl;
 
-// Find node via predicate (looks for all descendants in depth-first order)
-std::cout << doc.find_node(allow_remote_predicate()).attribute("Filename").value() << std::endl;
+// Find node via predicate (looks for all descendants in depth-first order)
+std::cout << doc.find_node(allow_remote_predicate()).attribute("Filename").value() << std::endl;
 
-// Find attribute via predicate
-std::cout << tools.last_child().find_attribute(allow_remote_predicate()).value() << std::endl;
+// Find attribute via predicate
+std::cout << tools.last_child().find_attribute(allow_remote_predicate()).value() << std::endl;
 
-// We can use simple functions instead of function objects
-std::cout << tools.find_child(small_timeout).attribute("Filename").value() << std::endl;
+// We can use simple functions instead of function objects
+std::cout << tools.find_child(small_timeout).attribute("Filename").value() << std::endl;

-Working with text contents + Working with text contents

- It is common to store data as text contents of some - node - i.e. <node><description>This is a node</description></node>. +

+ 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 @@ -711,10 +708,8 @@ in the documentation for modifying document data; this section describes the access interface of xml_text.

- You can get the text object from a node by using - text() - method: +

+ You can get the text object from a node by using text() method:

xml_text xml_node::text() const;

@@ -724,11 +719,11 @@ itself is used to return data; otherwise, a first child node of type node_pcdata or node_cdata is used.

- You - can check if the text object is bound to a valid PCDATA/CDATA node by using - it as a boolean value, i.e. if (text) - { ... } or if +

+ You can check if the text object is bound to a valid PCDATA/CDATA node by + using it as a boolean value, i.e. if + (text) { ... + } or if (!text) { ... }. Alternatively you can check it by using the empty() @@ -736,9 +731,9 @@


 bool xml_text::empty() const;
 
-
-        Given a text object, you can get the contents
-        (i.e. the value of PCDATA/CDATA node) by using the following function:
+

+        Given a text object, you can get the contents (i.e. the value of PCDATA/CDATA
+        node) by using the following function:
       
 const char_t* xml_text::get() const;
 
@@ -746,11 +741,10 @@
         In case text object is empty, the function returns an empty string - it never
         returns a null pointer.
       
-
-        If
-        you need a non-empty string if the text object is empty, or if the text contents
-        is actually a number or a boolean that is stored as a string, you can use
-        the following accessors:
+

+        If you need a non-empty string if the text object is empty, or if the text
+        contents is actually a number or a boolean that is stored as a string, you
+        can use the following accessors:
       
 const char_t* xml_text::as_string(const char_t* def = "") const;
 int xml_text::as_int(int def = 0) const;
@@ -767,9 +761,9 @@
         to a target type using the same rules and restrictions. You can refer
         to documentation for the attribute functions for details.
       
-
-        xml_text
-        is essentially a helper class that operates on xml_node
+

+        xml_text is essentially a
+        helper class that operates on xml_node
         values. It is bound to a node of type node_pcdata
         or node_cdata. You can use the following
         function to retrieve this node:
@@ -787,6 +781,7 @@
         object (samples/text.cpp):
       
 
+        
 
 std::cout << "Project name: " << project.child("name").text().get() << std::endl;
 std::cout << "Project version: " << project.child("version").text().as_double() << std::endl;
@@ -798,11 +793,11 @@


 
 
-Miscellaneous functions
+ Miscellaneous functions
 
-
-        If you need to get the document root of some
-        node, you can use the following function:
+

+        If you need to get the document root of some node, you can use the following
+        function:
       
 xml_node xml_node::root() const;
 
@@ -811,11 +806,10 @@
         which is the root node of the document the node belongs to (unless the node
         is null, in which case null node is returned).
       
-
-        While
-        pugixml supports complex XPath expressions, sometimes a simple path handling
-        facility is needed. There are two functions, for getting node path and for
-        converting path to a node:
+

+        While pugixml supports complex XPath expressions, sometimes a simple path
+        handling facility is needed. There are two functions, for getting node path
+        and for converting path to a node:
       
 string_t xml_node::path(char_t delimiter = '/') const;
 xml_node xml_node::first_element_by_path(const char_t* path, char_t delimiter = '/') const;
@@ -860,13 +854,12 @@
           is defined.
         
 
-
-        pugixml does not record row/column information
-        for nodes upon parsing for efficiency reasons. However, if the node has not
-        changed in a significant way since parsing (the name/value are not changed,
-        and the node itself is the original one, i.e. it was not deleted from the
-        tree and re-added later), it is possible to get the offset from the beginning
-        of XML buffer:
+

+        pugixml does not record row/column information for nodes upon parsing for
+        efficiency reasons. However, if the node has not changed in a significant
+        way since parsing (the name/value are not changed, and the node itself is
+        the original one, i.e. it was not deleted from the tree and re-added later),
+        it is possible to get the offset from the beginning of XML buffer:
       
 ptrdiff_t xml_node::offset_debug() const;
 
@@ -890,7 +883,7 @@
 
 
 
-pugixml 1.4 manual |
+pugixml 1.5 manual |
 		Overview |
 		Installation |
 		Document:
-- 
cgit v1.2.3