pugixml is a light-weight C++ XML
@@ -69,7 +69,7 @@
No documentation is perfect, neither is this one. If you encounter a description
- that is unclear, please file an issue as described in Feedback.
+ that is unclear, please file an issue as described in Feedback.
Also if you can spare the time for a full proof-reading, including spelling
and grammar, that would be great! Please send me
an e-mail; as a token of appreciation, your name will be included
@@ -80,7 +80,7 @@
If you believe you've found a bug in pugixml (bugs include compilation problems
@@ -107,14 +107,14 @@
Your contribution has to be distributed under the terms of a license that's
compatible with pugixml license; i.e. GPL/LGPL licensed code is not accepted.
-
- If filing an issue is not possible due to privacy or other concerns, you
- can contact pugixml author by e-mail directly: arseny.kapoulkine@gmail.com.
+
+ If filing an issue is not possible due to privacy or
+ other concerns, you can contact pugixml author by e-mail directly: arseny.kapoulkine@gmail.com.
Permission is hereby granted, free of charge, to any person obtaining a
@@ -179,18 +179,18 @@
This software is based on pugixml library (http://pugixml.org).
pugixml
- is Copyright (C) 2006-2012 Arseny Kapoulkine.
+ is Copyright (C) 2006-2014 Arseny Kapoulkine.
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):
- 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>Thisisanode</description></node>.
+
+ It is common to store data as text contents
+ of some node - i.e. <node><description>Thisisanode</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.
- 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:
constchar_t*xml_attribute::name()const;constchar_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:
@@ -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:
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):
- 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><itemid="1"/><itemid="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_nodexml_node::find_child_by_attribute(constchar_t*name,constchar_t*attr_name,constchar_t*attr_value)const;xml_nodexml_node::find_child_by_attribute(constchar_t*attr_name,constchar_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):
- 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):
- 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:
+ The traversal
+ is launched by calling traverse
function on traversal root and proceeds as follows:
-
+
First, begin function
is called with traversal root as its argument.
@@ -558,10 +570,10 @@
begin or end
functions; their default implementations return 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
@@ -571,24 +583,22 @@
This is an example of traversing tree hierarchy with xml_tree_walker (samples/traverse_walker.cpp):
- 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<typenamePredicate>xml_attributexml_node::find_attribute(Predicatepred)const;template<typenamePredicate>xml_nodexml_node::find_child(Predicatepred)const;
@@ -648,7 +658,6 @@
This is an example of using predicate-based functions (samples/traverse_predicate.cpp):
// 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;
- It is common to store data as text contents of some node - i.e. <node><description>Thisisanode</description></node>.
+
+ It is common to store data as text contents of some
+ node - i.e. <node><description>Thisisanode</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
@@ -702,8 +711,10 @@
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_textxml_node::text()const;
@@ -713,11 +724,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()
@@ -725,9 +736,9 @@
boolxml_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:
constchar_t*xml_text::get()const;
@@ -735,10 +746,11 @@
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:
All of the above functions have the same semantics as similar xml_attribute members: they return the
@@ -753,9 +767,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:
@@ -773,7 +787,6 @@
object (samples/text.cpp):
- 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_nodexml_node::root()const;
@@ -798,10 +811,11 @@
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_txml_node::path(char_tdelimiter='/')const;xml_nodexml_node::first_element_by_path(constchar_t*path,char_tdelimiter='/')const;
@@ -846,12 +860,13 @@
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: