From 2094a4fd3da85c1972f215cb5977f6157590ff79 Mon Sep 17 00:00:00 2001 From: Arseny Kapoulkine Date: Fri, 28 Feb 2014 06:01:16 +0000 Subject: docs: Regenerate HTML documentation git-svn-id: https://pugixml.googlecode.com/svn/trunk@993 99668b35-9821-0410-8761-19e4c4f06640 --- docs/manual/access.html | 327 +++++++++++++++++++++++++----------------------- 1 file changed, 171 insertions(+), 156 deletions(-) (limited to 'docs/manual/access.html') diff --git a/docs/manual/access.html b/docs/manual/access.html index c6abd05..4d4e9c2 100644 --- a/docs/manual/access.html +++ b/docs/manual/access.html @@ -3,16 +3,16 @@ Accessing document data - - - + + +
-pugixml 1.2 manual | +pugixml 1.4 manual | Overview | Installation | Document: @@ -28,27 +28,27 @@
-
-
Basic traversal functions
-
Getting node data
-
Getting attribute data
-
Contents-based traversal functions
-
Range-based for-loop support
-
Traversing node/attribute lists +
+
Basic traversal functions
+
Getting node data
+
Getting attribute data
+
Contents-based traversal functions
+
Range-based for-loop support
+
Traversing node/attribute lists via iterators
-
Recursive traversal with xml_tree_walker
-
Searching for nodes/attributes +
Recursive traversal with xml_tree_walker
+
Searching for nodes/attributes with predicates
-
Working with text contents
-
Miscellaneous functions
+
Working with text contents
+
Miscellaneous functions

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,11 +58,12 @@

-

- 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 @@ -123,7 +124,6 @@ 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 @@
-

- 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,8 +164,9 @@ 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 @@ -188,7 +189,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 @@ -197,11 +198,12 @@

-

- 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;
@@ -210,12 +212,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;
 

@@ -224,29 +226,36 @@
         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;
 double xml_attribute::as_double(double def = 0) const;
 float xml_attribute::as_float(float def = 0) const;
 bool xml_attribute::as_bool(bool def = false) const;
+long long xml_attribute::as_llong(long long def = 0) const;
+unsigned long long xml_attribute::as_ullong(unsigned long long def = 0) const;
 

 

         as_int, as_uint,
+        as_llong, as_ullong,
         as_double and as_float convert attribute values to numbers.
         If attribute handle is null or attribute value is empty, def
         argument is returned (which is 0 by default). Otherwise, all leading whitespace
-        characters are truncated, and the remaining string is parsed as a decimal
-        number (as_int or as_uint) or as a floating point number
-        in either decimal or scientific form (as_double
-        or as_float). Any extra characters
-        are silently discarded, i.e. as_int
-        will return 1 for string "1abc".
+        characters are truncated, and the remaining string is parsed as an integer
+        number in either decimal or hexadecimal form (applicable to as_int, as_uint,
+        as_llong and as_ullong; hexadecimal format is used if
+        the number has 0x
+        or 0X
+        prefix) or as a floating point number in either decimal or scientific form
+        (as_double or as_float). Any extra characters are silently
+        discarded, i.e. as_int will
+        return 1 for string "1abc".
       

 

         In case the input string contains a number that is out of the target numeric
@@ -282,17 +291,16 @@
Note

- There are no portable 64-bit types in C++, so there is no corresponding - conversion function. If your platform has a 64-bit integer, you can easily - write a conversion function yourself. + as_llong and as_ullong are only available if your + platform has reliable support for the long + 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"))
 {
@@ -307,11 +315,12 @@
 
 

 

-

-        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;
@@ -333,11 +342,15 @@
       

 
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;
@@ -357,7 +370,6 @@
         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";
 
@@ -371,12 +383,13 @@
 

 

 

-

-        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.
@@ -397,7 +410,6 @@
         This is an example of using these functions (samples/traverse_rangefor.cpp):
       

 

-        
 

 
for (pugi::xml_node tool: tools.children("Tool"))
 {
@@ -421,12 +433,12 @@
 

 

 

-

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

@@ -474,7 +486,6 @@
         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)
 {
@@ -507,14 +518,14 @@
 

 

 

-

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

@@ -530,11 +541,12 @@
 
 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:

-
- @@ -875,7 +890,7 @@
Copyright © 2012 Arseny Kapoulkine

+

Copyright © 2014 Arseny Kapoulkine

Distributed under the MIT License

-pugixml 1.2 manual | +pugixml 1.4 manual | Overview | Installation | Document: -- cgit v1.2.3