docs: Regenerated HTML documentation
git-svn-id: http://pugixml.googlecode.com/svn/trunk@790 99668b35-9821-0410-8761-19e4c4f06640
This commit is contained in:
arseny.kapoulkine
parent
07043107c7
commit
186e491d1e
12 changed files with 1402 additions and 626 deletions
|
|
@ -1,15 +1,16 @@
|
|||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>pugixml 0.9</title>
|
||||
<title>pugixml 1.0</title>
|
||||
<link rel="stylesheet" href="pugixml.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
|
||||
<link rel="home" href="manual.html" title="pugixml 0.9">
|
||||
<link rel="home" href="manual.html" title="pugixml 1.0">
|
||||
<link rel="next" href="manual/install.html" title="Installation">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table width="100%"><tr>
|
||||
<td>pugixml 0.9 manual |
|
||||
<td>
|
||||
<a href="http://pugixml.org/">pugixml 1.0</a> manual |
|
||||
<b>Overview</b> |
|
||||
<a href="manual/install.html">Installation</a> |
|
||||
Document:
|
||||
|
|
@ -36,22 +37,24 @@
|
|||
<a name="manual.overview.introduction"></a><a class="link" href="manual.html#manual.overview.introduction" title="Introduction"> Introduction</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
pugixml is a light-weight C++ XML processing library. It consists of a DOM-like
|
||||
interface with rich traversal/modification capabilities, an extremely fast
|
||||
XML parser which constructs the DOM tree from an XML file/buffer, and an
|
||||
XPath 1.0 implementation for complex data-driven tree queries. Full Unicode
|
||||
support is also available, with <a class="link" href="manual/dom.html#manual.dom.unicode" title="Unicode interface">two Unicode
|
||||
interface variants</a> and conversions between different Unicode encodings
|
||||
(which happen automatically during parsing/saving). The library is <a class="link" href="manual/install.html#manual.install.portability" title="Portability">extremely portable</a> and easy to
|
||||
integrate and use. pugixml is developed and maintained since 2006 and has
|
||||
many users. All code is distributed under the MIT license, making it completely
|
||||
free to use in both open-source and proprietary applications.
|
||||
<a href="http://pugixml.org/" target="_top">pugixml</a> is a light-weight C++ XML
|
||||
processing library. It consists of a DOM-like interface with rich traversal/modification
|
||||
capabilities, an extremely fast XML parser which constructs the DOM tree
|
||||
from an XML file/buffer, and an <a class="link" href="manual/xpath.html" title="XPath">XPath 1.0 implementation</a>
|
||||
for complex data-driven tree queries. Full Unicode support is also available,
|
||||
with <a class="link" href="manual/dom.html#manual.dom.unicode" title="Unicode interface">two Unicode interface variants</a>
|
||||
and conversions between different Unicode encodings (which happen automatically
|
||||
during parsing/saving). The library is <a class="link" href="manual/install.html#manual.install.portability" title="Portability">extremely
|
||||
portable</a> and easy to integrate and use. pugixml is developed and maintained
|
||||
since 2006 and has many users. All code is distributed under the <a class="link" href="manual.html#manual.overview.license" title="License">MIT
|
||||
license</a>, making it completely free to use in both open-source and
|
||||
proprietary applications.
|
||||
</p>
|
||||
<p>
|
||||
pugixml enables very fast, convenient and memory-efficient XML document processing.
|
||||
However, since pugixml has a DOM parser, it can't process XML documents that
|
||||
do not fit in memory; also the parser is a non-validating one, so if you
|
||||
need DTD/Schema validation, the library is not for you.
|
||||
need DTD or XML Schema validation, the library is not for you.
|
||||
</p>
|
||||
<p>
|
||||
This is the complete manual for pugixml, which describes all features of
|
||||
|
|
@ -90,19 +93,19 @@
|
|||
<p>
|
||||
Feature requests can be reported the same way as bugs, so if you're missing
|
||||
some functionality in pugixml or if the API is rough in some places and you
|
||||
can suggest an improvement, file an issue. However please note that there
|
||||
are many factors when considering API changes (compatibility with previous
|
||||
versions, API redundancy, etc.), so generally features that can be implemented
|
||||
via a small function without pugixml modification are not accepted. However,
|
||||
all rules have exceptions.
|
||||
can suggest an improvement, <a href="http://code.google.com/p/pugixml/issues/entry?template=Feature%20request" target="_top">file
|
||||
an issue</a>. However please note that there are many factors when considering
|
||||
API changes (compatibility with previous versions, API redundancy, etc.),
|
||||
so generally features that can be implemented via a small function without
|
||||
pugixml modification are not accepted. However, all rules have exceptions.
|
||||
</p>
|
||||
<p>
|
||||
If you have a contribution to pugixml, such as build script for some build
|
||||
system/IDE, or a well-designed set of helper functions, or a binding to some
|
||||
language other than C++, please file an issue. You can include the relevant
|
||||
patches as issue attachments. 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.
|
||||
language other than C++, please <a href="http://code.google.com/p/pugixml/issues/entry?template=Feature%20request" target="_top">file
|
||||
an issue</a>. You can include the relevant patches as issue attachments.
|
||||
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.
|
||||
</p>
|
||||
<a name="email"></a><p>
|
||||
If filing an issue is not possible due to privacy or other concerns, you
|
||||
|
|
@ -168,15 +171,26 @@
|
|||
IN THE SOFTWARE.
|
||||
</p>
|
||||
</blockquote></div>
|
||||
<p>
|
||||
This means that you can freely use pugixml in your applications, both open-source
|
||||
and proprietary. If you use pugixml in a product, it is sufficient to add
|
||||
an acknowledgment like this to the product distribution:
|
||||
</p>
|
||||
<div class="blockquote"><blockquote class="blockquote"><p>
|
||||
This software is based on pugixml library (http://pugixml.org).<br>
|
||||
pugixml
|
||||
is Copyright (C) 2006-2010 Arseny Kapoulkine.
|
||||
</p></blockquote></div>
|
||||
</div>
|
||||
</div></div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"><p><small>Last revised: July 15, 2010 at 17:02:03 GMT</small></p></td>
|
||||
<td align="left"><p><small>Last revised: October 31, 2010 at 07:44:52 GMT</small></p></td>
|
||||
<td align="right"><div class="copyright-footer"></div></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<table width="100%"><tr>
|
||||
<td>pugixml 0.9 manual |
|
||||
<td>
|
||||
<a href="http://pugixml.org/">pugixml 1.0</a> manual |
|
||||
<b>Overview</b> |
|
||||
<a href="manual/install.html">Installation</a> |
|
||||
Document:
|
||||
|
|
|
|||
|
|
@ -4,14 +4,15 @@
|
|||
<title>Accessing document data</title>
|
||||
<link rel="stylesheet" href="../pugixml.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
|
||||
<link rel="home" href="../manual.html" title="pugixml 0.9">
|
||||
<link rel="up" href="../manual.html" title="pugixml 0.9">
|
||||
<link rel="home" href="../manual.html" title="pugixml 1.0">
|
||||
<link rel="up" href="../manual.html" title="pugixml 1.0">
|
||||
<link rel="prev" href="loading.html" title="Loading document">
|
||||
<link rel="next" href="modify.html" title="Modifying document data">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table width="100%"><tr>
|
||||
<td>pugixml 0.9 manual |
|
||||
<td>
|
||||
<a href="http://pugixml.org/">pugixml 1.0</a> manual |
|
||||
<a href="../manual.html">Overview</a> |
|
||||
<a href="install.html">Installation</a> |
|
||||
Document:
|
||||
|
|
@ -79,10 +80,11 @@
|
|||
</pre>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">parent</span></code> function returns the
|
||||
node's parent; all nodes except the document have non-null parent. <code class="computeroutput"><span class="identifier">first_child</span></code> and <code class="computeroutput"><span class="identifier">last_child</span></code>
|
||||
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. <code class="computeroutput"><span class="identifier">next_sibling</span></code>
|
||||
node's parent; all non-null nodes except the document have non-null parent.
|
||||
<code class="computeroutput"><span class="identifier">first_child</span></code> and <code class="computeroutput"><span class="identifier">last_child</span></code> 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. <code class="computeroutput"><span class="identifier">next_sibling</span></code>
|
||||
and <code class="computeroutput"><span class="identifier">previous_sibling</span></code> return
|
||||
the node that's immediately to the right/left of this node in the children
|
||||
list, respectively - for example, in <code class="computeroutput"><span class="special"><</span><span class="identifier">a</span><span class="special">/><</span><span class="identifier">b</span><span class="special">/><</span><span class="identifier">c</span><span class="special">/></span></code>,
|
||||
|
|
@ -93,9 +95,9 @@
|
|||
results in handle pointing to <code class="computeroutput"><span class="special"><</span><span class="identifier">a</span><span class="special">/></span></code>.
|
||||
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. <code class="computeroutput"><span class="identifier">first_attribute</span></code>, <code class="computeroutput"><span class="identifier">last_attribute</span></code>,
|
||||
<code class="computeroutput"><span class="identifier">next_attribute</span></code> and <code class="computeroutput"><span class="identifier">previous_attribute</span></code> functions behave the
|
||||
same way as corresponding child node functions and allow to iterate through
|
||||
attribute list in the same way.
|
||||
<code class="computeroutput"><span class="identifier">next_attribute</span></code> and <code class="computeroutput"><span class="identifier">previous_attribute</span></code> functions behave similarly
|
||||
to the corresponding child node functions and allow to iterate through attribute
|
||||
list in the same way.
|
||||
</p>
|
||||
<div class="note"><table border="0" summary="Note">
|
||||
<tr>
|
||||
|
|
@ -111,7 +113,8 @@
|
|||
Calling any of the functions above on the null handle results in a null handle
|
||||
- i.e. <code class="computeroutput"><span class="identifier">node</span><span class="special">.</span><span class="identifier">first_child</span><span class="special">().</span><span class="identifier">next_sibling</span><span class="special">()</span></code>
|
||||
returns the second child of <code class="computeroutput"><span class="identifier">node</span></code>,
|
||||
and null handle if there is no children at all or if there is only one.
|
||||
and null handle if <code class="computeroutput"><span class="identifier">node</span></code> is
|
||||
null, has no children at all or if it has only one child node.
|
||||
</p>
|
||||
<p>
|
||||
With these functions, you can iterate through all child nodes and display
|
||||
|
|
@ -142,12 +145,13 @@
|
|||
<a name="xml_node::name"></a><a name="xml_node::value"></a><p>
|
||||
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. <code class="computeroutput"><span class="identifier">node_document</span></code>
|
||||
nodes do not have name or value, <code class="computeroutput"><span class="identifier">node_element</span></code>
|
||||
and <code class="computeroutput"><span class="identifier">node_declaration</span></code> nodes
|
||||
always have a name but never have a value, <code class="computeroutput"><span class="identifier">node_pcdata</span></code>,
|
||||
<code class="computeroutput"><span class="identifier">node_cdata</span></code> and <code class="computeroutput"><span class="identifier">node_comment</span></code> nodes never have a name but
|
||||
always have a value (it may be empty though), <code class="computeroutput"><span class="identifier">node_pi</span></code>
|
||||
name or value may be absent. <a class="link" href="dom.html#node_document">node_document</a>
|
||||
nodes do not have a name or value, <a class="link" href="dom.html#node_element">node_element</a>
|
||||
and <a class="link" href="dom.html#node_declaration">node_declaration</a> nodes always
|
||||
have a name but never have a value, <a class="link" href="dom.html#node_pcdata">node_pcdata</a>,
|
||||
<a class="link" href="dom.html#node_cdata">node_cdata</a>, <a class="link" href="dom.html#node_comment">node_comment</a>
|
||||
and <a class="link" href="dom.html#node_doctype">node_doctype</a> nodes never have a name
|
||||
but always have a value (it may be empty though), <a class="link" href="dom.html#node_pi">node_pi</a>
|
||||
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:
|
||||
</p>
|
||||
|
|
@ -161,18 +165,18 @@
|
|||
<a name="xml_node::child_value"></a><p>
|
||||
It is common to store data as text contents of some node - i.e. <code class="computeroutput"><span class="special"><</span><span class="identifier">node</span><span class="special">><</span><span class="identifier">description</span><span class="special">></span><span class="identifier">This</span> <span class="identifier">is</span> <span class="identifier">a</span> <span class="identifier">node</span><span class="special"></</span><span class="identifier">description</span><span class="special">></</span><span class="identifier">node</span><span class="special">></span></code>.
|
||||
In this case, <code class="computeroutput"><span class="special"><</span><span class="identifier">description</span><span class="special">></span></code> node does not have a value, but instead
|
||||
has a child of type <code class="computeroutput"><span class="identifier">node_pcdata</span></code>
|
||||
with value <code class="computeroutput"><span class="string">"This is a node"</span></code>.
|
||||
pugixml provides two helper functions to parse such data:
|
||||
has a child of type <a class="link" href="dom.html#node_pcdata">node_pcdata</a> with value
|
||||
<code class="computeroutput"><span class="string">"This is a node"</span></code>. pugixml
|
||||
provides two helper functions to parse such data:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">child_value</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
<span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">child_value</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">name</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">child_value</span><span class="special">()</span></code>
|
||||
returns the value of the first child with type <code class="computeroutput"><span class="identifier">node_pcdata</span></code>
|
||||
or <code class="computeroutput"><span class="identifier">node_cdata</span></code>; <code class="computeroutput"><span class="identifier">child_value</span><span class="special">(</span><span class="identifier">name</span><span class="special">)</span></code> is
|
||||
a simple wrapper for <code class="computeroutput"><span class="identifier">child</span><span class="special">(</span><span class="identifier">name</span><span class="special">).</span><span class="identifier">child_value</span><span class="special">()</span></code>.
|
||||
returns the value of the first child with type <a class="link" href="dom.html#node_pcdata">node_pcdata</a>
|
||||
or <a class="link" href="dom.html#node_cdata">node_cdata</a>; <code class="computeroutput"><span class="identifier">child_value</span><span class="special">(</span><span class="identifier">name</span><span class="special">)</span></code>
|
||||
is a simple wrapper for <code class="computeroutput"><span class="identifier">child</span><span class="special">(</span><span class="identifier">name</span><span class="special">).</span><span class="identifier">child_value</span><span class="special">()</span></code>.
|
||||
For the above example, calling <code class="computeroutput"><span class="identifier">node</span><span class="special">.</span><span class="identifier">child_value</span><span class="special">(</span><span class="string">"description"</span><span class="special">)</span></code> and <code class="computeroutput"><span class="identifier">description</span><span class="special">.</span><span class="identifier">child_value</span><span class="special">()</span></code> will both produce string <code class="computeroutput"><span class="string">"This is a node"</span></code>. If there is no
|
||||
child with relevant type, or if the handle is null, <code class="computeroutput"><span class="identifier">child_value</span></code>
|
||||
functions return empty string.
|
||||
|
|
@ -194,15 +198,14 @@
|
|||
<span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">value</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
<a name="xml_attribute::as_int"></a><a name="xml_attribute::as_uint"></a><a name="xml_attribute::as_double"></a><a name="xml_attribute::as_float"></a><a name="xml_attribute::as_bool"></a><p>
|
||||
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:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">as_int</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
<span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">as_uint</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
|
|
@ -241,7 +244,7 @@
|
|||
value to boolean as follows: if attribute handle is null or attribute value
|
||||
is empty, <code class="computeroutput"><span class="keyword">false</span></code> is returned.
|
||||
Otherwise, <code class="computeroutput"><span class="keyword">true</span></code> is returned
|
||||
if first character is one of <code class="computeroutput"><span class="char">'1'</span><span class="special">,</span> <span class="char">'t'</span><span class="special">,</span>
|
||||
if the first character is one of <code class="computeroutput"><span class="char">'1'</span><span class="special">,</span> <span class="char">'t'</span><span class="special">,</span>
|
||||
<span class="char">'T'</span><span class="special">,</span> <span class="char">'y'</span><span class="special">,</span> <span class="char">'Y'</span></code>.
|
||||
This means that strings like <code class="computeroutput"><span class="string">"true"</span></code>
|
||||
and <code class="computeroutput"><span class="string">"yes"</span></code> 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:
|
||||
<code class="computeroutput"><span class="identifier">xml_node_iterator</span><span class="special">(</span><span class="identifier">node</span><span class="special">)</span></code>.
|
||||
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: <code class="computeroutput"><span class="identifier">xml_node_iterator</span><span class="special">(</span><span class="identifier">node</span><span class="special">)</span></code>.
|
||||
For <code class="computeroutput"><span class="identifier">xml_attribute_iterator</span></code>,
|
||||
you'll have to provide both an attribute and its parent node.
|
||||
</p>
|
||||
|
|
@ -527,7 +530,7 @@
|
|||
<a name="xml_node::find_attribute"></a><a name="xml_node::find_child"></a><a name="xml_node::find_node"></a><p>
|
||||
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 <code class="computeroutput"><span class="identifier">find_</span></code>
|
||||
functions:
|
||||
</p>
|
||||
|
|
@ -546,24 +549,24 @@
|
|||
<p>
|
||||
<code class="computeroutput"><span class="identifier">find_attribute</span></code> function iterates
|
||||
through all attributes of the specified node, and returns the first attribute
|
||||
for which predicate returned <code class="computeroutput"><span class="keyword">true</span></code>.
|
||||
If predicate returned <code class="computeroutput"><span class="keyword">false</span></code>
|
||||
for which the predicate returned <code class="computeroutput"><span class="keyword">true</span></code>.
|
||||
If the predicate returned <code class="computeroutput"><span class="keyword">false</span></code>
|
||||
for all attributes or if there were no attributes (including the case where
|
||||
the node is null), null attribute is returned.
|
||||
</p>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">find_child</span></code> function iterates
|
||||
through all child nodes of the specified node, and returns the first node
|
||||
for which predicate returned <code class="computeroutput"><span class="keyword">true</span></code>.
|
||||
If predicate returned <code class="computeroutput"><span class="keyword">false</span></code>
|
||||
for which the predicate returned <code class="computeroutput"><span class="keyword">true</span></code>.
|
||||
If the predicate returned <code class="computeroutput"><span class="keyword">false</span></code>
|
||||
for all nodes or if there were no child nodes (including the case where the
|
||||
node is null), null node is returned.
|
||||
</p>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">find_node</span></code> 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
|
||||
<code class="computeroutput"><span class="keyword">true</span></code>. If predicate returned
|
||||
the node itself), and returns the first node for which the predicate returned
|
||||
<code class="computeroutput"><span class="keyword">true</span></code>. If the predicate returned
|
||||
<code class="computeroutput"><span class="keyword">false</span></code> for all nodes or if subtree
|
||||
was empty, null node is returned.
|
||||
</p>
|
||||
|
|
@ -622,11 +625,9 @@
|
|||
<pre class="programlisting"><span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">root</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
This function returns the node with type <code class="computeroutput"><span class="identifier">node_document</span></code>,
|
||||
This function returns the node with type <a class="link" href="dom.html#node_document">node_document</a>,
|
||||
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).
|
||||
</p>
|
||||
<a name="xml_node::path"></a><a name="xml_node::first_element_by_path"></a><p>
|
||||
While pugixml supports complex XPath expressions, sometimes a simple path
|
||||
|
|
@ -643,9 +644,9 @@
|
|||
<code class="computeroutput"><span class="identifier">path</span></code> returns the path to
|
||||
the node from the document root, <code class="computeroutput"><span class="identifier">first_element_by_path</span></code>
|
||||
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: <code class="computeroutput"><span class="special"><</span><span class="identifier">a</span><span class="special">><</span><span class="identifier">b</span><span class="special">><</span><span class="identifier">c</span><span class="special">/></</span><span class="identifier">b</span><span class="special">></</span><span class="identifier">a</span><span class="special">></span></code>,
|
||||
(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: <code class="computeroutput"><span class="special"><</span><span class="identifier">a</span><span class="special">><</span><span class="identifier">b</span><span class="special">><</span><span class="identifier">c</span><span class="special">/></</span><span class="identifier">b</span><span class="special">></</span><span class="identifier">a</span><span class="special">></span></code>,
|
||||
node <code class="computeroutput"><span class="special"><</span><span class="identifier">c</span><span class="special">/></span></code> has path <code class="computeroutput"><span class="string">"a/b/c"</span></code>;
|
||||
calling <code class="computeroutput"><span class="identifier">first_element_by_path</span></code>
|
||||
for document with path <code class="computeroutput"><span class="string">"a/b"</span></code>
|
||||
|
|
@ -672,7 +673,7 @@
|
|||
</tr>
|
||||
<tr><td align="left" valign="top"><p>
|
||||
<code class="computeroutput"><span class="identifier">path</span></code> function returns the
|
||||
result as STL string, and thus is not available if <code class="computeroutput"><span class="identifier">PUGIXML_NO_STL</span></code>
|
||||
result as STL string, and thus is not available if <a class="link" href="install.html#PUGIXML_NO_STL">PUGIXML_NO_STL</a>
|
||||
is defined.
|
||||
</p></td></tr>
|
||||
</table></div>
|
||||
|
|
@ -689,7 +690,7 @@
|
|||
If the offset is not available (this happens if the node is null, was not
|
||||
originally parsed from a stream, or has changed in a significant way), the
|
||||
function returns -1. Otherwise it returns the offset to node's data from
|
||||
the beginning of XML buffer in <code class="computeroutput"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">char_t</span></code>
|
||||
the beginning of XML buffer in <a class="link" href="dom.html#char_t">pugi::char_t</a>
|
||||
units. For more information on parsing offsets, see <a class="link" href="loading.html#xml_parse_result::offset">parsing
|
||||
error handling documentation</a>.
|
||||
</p>
|
||||
|
|
@ -704,7 +705,8 @@
|
|||
</tr></table>
|
||||
<hr>
|
||||
<table width="100%"><tr>
|
||||
<td>pugixml 0.9 manual |
|
||||
<td>
|
||||
<a href="http://pugixml.org/">pugixml 1.0</a> manual |
|
||||
<a href="../manual.html">Overview</a> |
|
||||
<a href="install.html">Installation</a> |
|
||||
Document:
|
||||
|
|
|
|||
|
|
@ -4,14 +4,15 @@
|
|||
<title>API Reference</title>
|
||||
<link rel="stylesheet" href="../pugixml.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
|
||||
<link rel="home" href="../manual.html" title="pugixml 0.9">
|
||||
<link rel="up" href="../manual.html" title="pugixml 0.9">
|
||||
<link rel="home" href="../manual.html" title="pugixml 1.0">
|
||||
<link rel="up" href="../manual.html" title="pugixml 1.0">
|
||||
<link rel="prev" href="changes.html" title="Changelog">
|
||||
<link rel="next" href="toc.html" title="Table of Contents">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table width="100%"><tr>
|
||||
<td>pugixml 0.9 manual |
|
||||
<td>
|
||||
<a href="http://pugixml.org/">pugixml 1.0</a> manual |
|
||||
<a href="../manual.html">Overview</a> |
|
||||
<a href="install.html">Installation</a> |
|
||||
Document:
|
||||
|
|
@ -110,7 +111,10 @@
|
|||
<a class="link" href="dom.html#node_pi">node_pi</a>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<a class="link" href="dom.html#node_declaration">node_declaration</a> <br><br>
|
||||
<a class="link" href="dom.html#node_declaration">node_declaration</a>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<a class="link" href="dom.html#node_doctype">node_doctype</a> <br><br>
|
||||
|
||||
</li>
|
||||
</ul></div>
|
||||
|
|
@ -261,12 +265,18 @@
|
|||
<li class="listitem">
|
||||
<a class="link" href="loading.html#parse_default">parse_default</a>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<a class="link" href="loading.html#parse_doctype">parse_doctype</a>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<a class="link" href="loading.html#parse_eol">parse_eol</a>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<a class="link" href="loading.html#parse_escapes">parse_escapes</a>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<a class="link" href="loading.html#parse_full">parse_full</a>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<a class="link" href="loading.html#parse_minimal">parse_minimal</a>
|
||||
</li>
|
||||
|
|
@ -334,6 +344,10 @@
|
|||
<span class="keyword">const</span><span class="special">;</span></code>
|
||||
<br><br>
|
||||
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">size_t</span> </code><a class="link" href="dom.html#xml_attribute::hash_value">hash_value</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code> <br><br>
|
||||
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xml_attribute</span> </code><a class="link" href="access.html#xml_attribute::next_attribute">next_attribute</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code>
|
||||
|
|
@ -463,6 +477,10 @@
|
|||
<span class="keyword">const</span><span class="special">;</span></code>
|
||||
<br><br>
|
||||
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">size_t</span> </code><a class="link" href="dom.html#xml_node::hash_value">hash_value</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code> <br><br>
|
||||
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xml_node_type</span> </code><a class="link" href="dom.html#xml_node::type">type</a><code class="computeroutput"><span class="special">()</span>
|
||||
|
|
@ -621,6 +639,10 @@
|
|||
<code class="computeroutput"><span class="identifier">xml_attribute</span> </code><a class="link" href="modify.html#xml_node::append_attribute">append_attribute</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span>
|
||||
<span class="identifier">name</span><span class="special">);</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xml_attribute</span> </code><a class="link" href="modify.html#xml_node::prepend_attribute">prepend_attribute</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span>
|
||||
<span class="identifier">name</span><span class="special">);</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xml_attribute</span> </code><a class="link" href="modify.html#xml_node::insert_attribute_after">insert_attribute_after</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span>
|
||||
<span class="identifier">name</span><span class="special">,</span>
|
||||
|
|
@ -637,6 +659,11 @@
|
|||
<span class="identifier">type</span> <span class="special">=</span>
|
||||
<span class="identifier">node_element</span><span class="special">);</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xml_node</span> </code><a class="link" href="modify.html#xml_node::prepend_child">prepend_child</a><code class="computeroutput"><span class="special">(</span><span class="identifier">xml_node_type</span>
|
||||
<span class="identifier">type</span> <span class="special">=</span>
|
||||
<span class="identifier">node_element</span><span class="special">);</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xml_node</span> </code><a class="link" href="modify.html#xml_node::insert_child_after">insert_child_after</a><code class="computeroutput"><span class="special">(</span><span class="identifier">xml_node_type</span>
|
||||
<span class="identifier">type</span><span class="special">,</span>
|
||||
|
|
@ -647,10 +674,33 @@
|
|||
<span class="identifier">type</span><span class="special">,</span>
|
||||
<span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">node</span><span class="special">);</span></code> <br><br>
|
||||
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xml_node</span> </code><a class="link" href="modify.html#xml_node::append_child">append_child</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span>
|
||||
<span class="identifier">name</span><span class="special">);</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xml_node</span> </code><a class="link" href="modify.html#xml_node::prepend_child">prepend_child</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span>
|
||||
<span class="identifier">name</span><span class="special">);</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xml_node</span> </code><a class="link" href="modify.html#xml_node::insert_child_after">insert_child_after</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span>
|
||||
<span class="identifier">name</span><span class="special">,</span>
|
||||
<span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">node</span><span class="special">);</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xml_node</span> </code><a class="link" href="modify.html#xml_node::insert_child_before">insert_child_before</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span>
|
||||
<span class="identifier">name</span><span class="special">,</span>
|
||||
<span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">node</span><span class="special">);</span></code> <br><br>
|
||||
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xml_attribute</span> </code><a class="link" href="modify.html#xml_node::append_copy">append_copy</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">proto</span><span class="special">);</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xml_attribute</span> </code><a class="link" href="modify.html#xml_node::prepend_copy">prepend_copy</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&</span>
|
||||
<span class="identifier">proto</span><span class="special">);</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xml_attribute</span> </code><a class="link" href="modify.html#xml_node::insert_copy_after">insert_copy_after</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&</span>
|
||||
<span class="identifier">proto</span><span class="special">,</span>
|
||||
|
|
@ -666,6 +716,10 @@
|
|||
<code class="computeroutput"><span class="identifier">xml_node</span> </code><a class="link" href="modify.html#xml_node::append_copy">append_copy</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span>
|
||||
<span class="identifier">proto</span><span class="special">);</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xml_node</span> </code><a class="link" href="modify.html#xml_node::prepend_copy">prepend_copy</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span>
|
||||
<span class="identifier">proto</span><span class="special">);</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xml_node</span> </code><a class="link" href="modify.html#xml_node::insert_copy_after">insert_copy_after</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span>
|
||||
<span class="identifier">proto</span><span class="special">,</span>
|
||||
|
|
@ -738,7 +792,10 @@
|
|||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xpath_node</span> </code><a class="link" href="xpath.html#xml_node::select_single_node">select_single_node</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span>
|
||||
<span class="identifier">query</span><span class="special">)</span>
|
||||
<span class="identifier">query</span><span class="special">,</span>
|
||||
<span class="identifier">xpath_variable_set</span><span class="special">*</span>
|
||||
<span class="identifier">variables</span> <span class="special">=</span>
|
||||
<span class="number">0</span><span class="special">)</span>
|
||||
<span class="keyword">const</span><span class="special">;</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
|
|
@ -748,7 +805,10 @@
|
|||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xpath_node_set</span> </code><a class="link" href="xpath.html#xml_node::select_nodes">select_nodes</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span>
|
||||
<span class="identifier">query</span><span class="special">)</span>
|
||||
<span class="identifier">query</span><span class="special">,</span>
|
||||
<span class="identifier">xpath_variable_set</span><span class="special">*</span>
|
||||
<span class="identifier">variables</span> <span class="special">=</span>
|
||||
<span class="number">0</span><span class="special">)</span>
|
||||
<span class="keyword">const</span><span class="special">;</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
|
|
@ -769,6 +829,15 @@
|
|||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="special">~</span></code><a class="link" href="dom.html#xml_document::dtor">xml_document</a><code class="computeroutput"><span class="special">();</span></code> <br><br>
|
||||
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">void</span> </code><a class="link" href="dom.html#xml_document::reset">reset</a><code class="computeroutput"><span class="special">();</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">void</span> </code><a class="link" href="dom.html#xml_document::reset">reset</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_document</span><span class="special">&</span>
|
||||
<span class="identifier">proto</span><span class="special">);</span></code>
|
||||
<br><br>
|
||||
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xml_parse_result</span> </code><a class="link" href="loading.html#xml_document::load_stream">load</a><code class="computeroutput"><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">istream</span><span class="special">&</span>
|
||||
|
|
@ -800,7 +869,15 @@
|
|||
<span class="special">=</span> <span class="identifier">parse_default</span><span class="special">,</span> <span class="identifier">xml_encoding</span>
|
||||
<span class="identifier">encoding</span> <span class="special">=</span>
|
||||
<span class="identifier">encoding_auto</span><span class="special">);</span></code>
|
||||
<br><br>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xml_parse_result</span> </code><a class="link" href="loading.html#xml_document::load_file_wide">load_file</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="keyword">wchar_t</span><span class="special">*</span>
|
||||
<span class="identifier">path</span><span class="special">,</span>
|
||||
<span class="keyword">unsigned</span> <span class="keyword">int</span>
|
||||
<span class="identifier">options</span> <span class="special">=</span>
|
||||
<span class="identifier">parse_default</span><span class="special">,</span>
|
||||
<span class="identifier">xml_encoding</span> <span class="identifier">encoding</span>
|
||||
<span class="special">=</span> <span class="identifier">encoding_auto</span><span class="special">);</span></code> <br><br>
|
||||
|
||||
</li>
|
||||
<li class="listitem">
|
||||
|
|
@ -839,6 +916,17 @@
|
|||
<span class="identifier">encoding</span> <span class="special">=</span>
|
||||
<span class="identifier">encoding_auto</span><span class="special">)</span>
|
||||
<span class="keyword">const</span><span class="special">;</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="saving.html#xml_document::save_file_wide">save_file</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="keyword">wchar_t</span><span class="special">*</span>
|
||||
<span class="identifier">path</span><span class="special">,</span>
|
||||
<span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">indent</span>
|
||||
<span class="special">=</span> <span class="string">"\t"</span><span class="special">,</span> <span class="keyword">unsigned</span>
|
||||
<span class="keyword">int</span> <span class="identifier">flags</span>
|
||||
<span class="special">=</span> <span class="identifier">format_default</span><span class="special">,</span> <span class="identifier">xml_encoding</span>
|
||||
<span class="identifier">encoding</span> <span class="special">=</span>
|
||||
<span class="identifier">encoding_auto</span><span class="special">)</span>
|
||||
<span class="keyword">const</span><span class="special">;</span></code>
|
||||
<br><br>
|
||||
|
||||
</li>
|
||||
|
|
@ -876,6 +964,10 @@
|
|||
<span class="identifier">xml_encoding</span> <span class="identifier">encoding</span>
|
||||
<span class="special">=</span> <span class="identifier">encoding_auto</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span></code> <br><br>
|
||||
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xml_node</span> </code><a class="link" href="dom.html#xml_document::document_element">document_element</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code> <br><br>
|
||||
|
||||
</li>
|
||||
</ul></div>
|
||||
</li>
|
||||
|
|
@ -960,32 +1052,58 @@
|
|||
</li>
|
||||
</ul></div>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">struct</span> </code><a class="link" href="xpath.html#xpath_parse_result">xpath_parse_result</a>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="circle">
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> </code><a class="link" href="xpath.html#xpath_parse_result::error">error</a><code class="computeroutput"><span class="special">;</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">ptrdiff_t</span> </code><a class="link" href="xpath.html#xpath_parse_result::offset">offset</a><code class="computeroutput"><span class="special">;</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">operator</span> </code><a class="link" href="xpath.html#xpath_parse_result::bool">bool</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> </code><a class="link" href="xpath.html#xpath_parse_result::description">description</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code> <br><br>
|
||||
|
||||
</li>
|
||||
</ul></div>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">class</span> </code><a class="link" href="xpath.html#xpath_query">xpath_query</a>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="circle">
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">explicit</span> </code><a class="link" href="xpath.html#xpath_query::ctor">xpath_query</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span>
|
||||
<span class="identifier">query</span><span class="special">);</span></code>
|
||||
<span class="identifier">query</span><span class="special">,</span>
|
||||
<span class="identifier">xpath_variable_set</span><span class="special">*</span>
|
||||
<span class="identifier">variables</span> <span class="special">=</span>
|
||||
<span class="number">0</span><span class="special">);</span></code>
|
||||
<br><br>
|
||||
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="xpath.html#xpath_query::evaluate_boolean">evaluate_boolean</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span>
|
||||
<code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="xpath.html#xpath_query::evaluate_boolean">evaluate_boolean</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span>
|
||||
<span class="identifier">n</span><span class="special">)</span>
|
||||
<span class="keyword">const</span><span class="special">;</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">double</span> </code><a class="link" href="xpath.html#xpath_query::evaluate_number">evaluate_number</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span>
|
||||
<code class="computeroutput"><span class="keyword">double</span> </code><a class="link" href="xpath.html#xpath_query::evaluate_number">evaluate_number</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span>
|
||||
<span class="identifier">n</span><span class="special">)</span>
|
||||
<span class="keyword">const</span><span class="special">;</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">string_t</span> </code><a class="link" href="xpath.html#xpath_query::evaluate_string">evaluate_string</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span>
|
||||
<code class="computeroutput"><span class="identifier">string_t</span> </code><a class="link" href="xpath.html#xpath_query::evaluate_string">evaluate_string</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span>
|
||||
<span class="identifier">n</span><span class="special">)</span>
|
||||
<span class="keyword">const</span><span class="special">;</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xpath_node_set</span> </code><a class="link" href="xpath.html#xpath_query::evaluate_node_set">evaluate_node_set</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span>
|
||||
<code class="computeroutput"><span class="identifier">size_t</span> </code><a class="link" href="xpath.html#xpath_query::evaluate_string_buffer">evaluate_string</a><code class="computeroutput"><span class="special">(</span><span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">size_t</span>
|
||||
<span class="identifier">capacity</span><span class="special">,</span>
|
||||
<span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xpath_node_set</span> </code><a class="link" href="xpath.html#xpath_query::evaluate_node_set">evaluate_node_set</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span>
|
||||
<span class="identifier">n</span><span class="special">)</span>
|
||||
<span class="keyword">const</span><span class="special">;</span></code>
|
||||
<br><br>
|
||||
|
|
@ -994,19 +1112,32 @@
|
|||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xpath_value_type</span> </code><a class="link" href="xpath.html#xpath_query::return_type">return_type</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code> <br><br>
|
||||
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">const</span> <span class="identifier">xpath_parse_result</span><span class="special">&</span> </code><a class="link" href="xpath.html#xpath_query::result">result</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">operator</span> </code><a class="link" href="xpath.html#xpath_query::unspecified_bool_type">unspecified_bool_type</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code> <br><br>
|
||||
|
||||
</li>
|
||||
</ul></div>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">class</span> </code><a class="link" href="xpath.html#xpath_exception">xpath_exception</a><code class="computeroutput"><span class="special">:</span> <span class="keyword">public</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span></code>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem">
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="circle">
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">virtual</span> <span class="keyword">const</span>
|
||||
<span class="keyword">char</span><span class="special">*</span>
|
||||
</code><a class="link" href="xpath.html#xpath_exception::what">what</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span>
|
||||
<span class="keyword">throw</span><span class="special">();</span></code>
|
||||
<br><br>
|
||||
|
||||
</li></ul></div>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">const</span> <span class="identifier">xpath_parse_result</span><span class="special">&</span> </code><a class="link" href="xpath.html#xpath_exception::result">result</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code> <br><br>
|
||||
|
||||
</li>
|
||||
</ul></div>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">class</span> </code><a class="link" href="xpath.html#xpath_node">xpath_node</a>
|
||||
|
|
@ -1055,6 +1186,18 @@
|
|||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">class</span> </code><a class="link" href="xpath.html#xpath_node_set">xpath_node_set</a>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="circle">
|
||||
<li class="listitem">
|
||||
<a class="link" href="xpath.html#xpath_node_set::ctor">xpath_node_set</a><code class="computeroutput"><span class="special">();</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<a class="link" href="xpath.html#xpath_node_set::ctor">xpath_node_set</a><code class="computeroutput"><span class="special">(</span><span class="identifier">const_iterator</span>
|
||||
<span class="identifier">begin</span><span class="special">,</span>
|
||||
<span class="identifier">const_iterator</span> <span class="identifier">end</span><span class="special">,</span> <span class="identifier">type_t</span>
|
||||
<span class="identifier">type</span> <span class="special">=</span>
|
||||
<span class="identifier">type_unsorted</span><span class="special">);</span></code>
|
||||
<br><br>
|
||||
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">typedef</span> <span class="keyword">const</span>
|
||||
<span class="identifier">xpath_node</span><span class="special">*</span>
|
||||
|
|
@ -1100,6 +1243,97 @@
|
|||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">void</span> </code><a class="link" href="xpath.html#xpath_node_set::sort">sort</a><code class="computeroutput"><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">reverse</span> <span class="special">=</span>
|
||||
<span class="keyword">false</span><span class="special">);</span></code>
|
||||
<br><br>
|
||||
|
||||
</li>
|
||||
</ul></div>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">class</span> </code><a class="link" href="xpath.html#xpath_variable">xpath_variable</a>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="circle">
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> </code><a class="link" href="xpath.html#xpath_variable::name">name</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xpath_value_type</span> </code><a class="link" href="xpath.html#xpath_variable::type">type</a><code class="computeroutput"><span class="special">()</span>
|
||||
<span class="keyword">const</span><span class="special">;</span></code>
|
||||
<br><br>
|
||||
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="xpath.html#xpath_variable::get_boolean">get_boolean</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">double</span> </code><a class="link" href="xpath.html#xpath_variable::get_number">get_number</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> </code><a class="link" href="xpath.html#xpath_variable::get_string">get_string</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">const</span> <span class="identifier">xpath_node_set</span><span class="special">&</span> </code><a class="link" href="xpath.html#xpath_variable::get_node_set">get_node_set</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code> <br><br>
|
||||
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="xpath.html#xpath_variable::set">set</a><code class="computeroutput"><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">value</span><span class="special">);</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="xpath.html#xpath_variable::set">set</a><code class="computeroutput"><span class="special">(</span><span class="keyword">double</span>
|
||||
<span class="identifier">value</span><span class="special">);</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="xpath.html#xpath_variable::set">set</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span>
|
||||
<span class="identifier">value</span><span class="special">);</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="xpath.html#xpath_variable::set">set</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node_set</span><span class="special">&</span>
|
||||
<span class="identifier">value</span><span class="special">);</span></code>
|
||||
<br><br>
|
||||
|
||||
</li>
|
||||
</ul></div>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">class</span> </code><a class="link" href="xpath.html#xpath_variable_set">xpath_variable_set</a>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="circle">
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xpath_variable</span><span class="special">*</span>
|
||||
</code><a class="link" href="xpath.html#xpath_variable_set::add">add</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span>
|
||||
<span class="identifier">name</span><span class="special">,</span>
|
||||
<span class="identifier">xpath_value_type</span> <span class="identifier">type</span><span class="special">);</span></code> <br><br>
|
||||
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="xpath.html#xpath_variable_set::set">set</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span>
|
||||
<span class="identifier">name</span><span class="special">,</span>
|
||||
<span class="keyword">bool</span> <span class="identifier">value</span><span class="special">);</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="xpath.html#xpath_variable_set::set">set</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span>
|
||||
<span class="identifier">name</span><span class="special">,</span>
|
||||
<span class="keyword">double</span> <span class="identifier">value</span><span class="special">);</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="xpath.html#xpath_variable_set::set">set</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span>
|
||||
<span class="identifier">name</span><span class="special">,</span>
|
||||
<span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">value</span><span class="special">);</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="xpath.html#xpath_variable_set::set">set</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span>
|
||||
<span class="identifier">name</span><span class="special">,</span>
|
||||
<span class="keyword">const</span> <span class="identifier">xpath_node_set</span><span class="special">&</span> <span class="identifier">value</span><span class="special">);</span></code> <br><br>
|
||||
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">xpath_variable</span><span class="special">*</span>
|
||||
</code><a class="link" href="xpath.html#xpath_variable_set::get">get</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span>
|
||||
<span class="identifier">name</span><span class="special">);</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="keyword">const</span> <span class="identifier">xpath_variable</span><span class="special">*</span> </code><a class="link" href="xpath.html#xpath_variable_set::get">get</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span>
|
||||
<span class="identifier">name</span><span class="special">)</span>
|
||||
<span class="keyword">const</span><span class="special">;</span></code>
|
||||
<br><br>
|
||||
|
||||
</li>
|
||||
</ul></div>
|
||||
</li>
|
||||
|
|
@ -1109,19 +1343,29 @@
|
|||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||||
<li class="listitem">
|
||||
<a class="link" href="dom.html#as_utf8">as_utf8</a>
|
||||
<code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> </code><a class="link" href="dom.html#as_utf8">as_utf8</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="keyword">wchar_t</span><span class="special">*</span> <span class="identifier">str</span><span class="special">);</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<a class="link" href="dom.html#as_wide">as_wide</a>
|
||||
<code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> </code><a class="link" href="dom.html#as_utf8">as_utf8</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">wstring</span><span class="special">&</span>
|
||||
<span class="identifier">str</span><span class="special">);</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<a class="link" href="dom.html#get_memory_allocation_function">get_memory_allocation_function</a>
|
||||
<code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wstring</span> </code><a class="link" href="dom.html#as_wide">as_wide</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">str</span><span class="special">);</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<a class="link" href="dom.html#get_memory_deallocation_function">get_memory_deallocation_function</a>
|
||||
<code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wstring</span> </code><a class="link" href="dom.html#as_wide">as_wide</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&</span>
|
||||
<span class="identifier">str</span><span class="special">);</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<a class="link" href="dom.html#set_memory_management_functions">set_memory_management_functions</a>
|
||||
<code class="computeroutput"><span class="keyword">void</span> </code><a class="link" href="dom.html#set_memory_management_functions">set_memory_management_functions</a><code class="computeroutput"><span class="special">(</span><span class="identifier">allocation_function</span>
|
||||
<span class="identifier">allocate</span><span class="special">,</span>
|
||||
<span class="identifier">deallocation_function</span> <span class="identifier">deallocate</span><span class="special">);</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">allocation_function</span> </code><a class="link" href="dom.html#get_memory_allocation_function">get_memory_allocation_function</a><code class="computeroutput"><span class="special">();</span></code>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">deallocation_function</span> </code><a class="link" href="dom.html#get_memory_deallocation_function">get_memory_deallocation_function</a><code class="computeroutput"><span class="special">();</span></code>
|
||||
</li>
|
||||
</ul></div>
|
||||
</div>
|
||||
|
|
@ -1134,7 +1378,8 @@
|
|||
</tr></table>
|
||||
<hr>
|
||||
<table width="100%"><tr>
|
||||
<td>pugixml 0.9 manual |
|
||||
<td>
|
||||
<a href="http://pugixml.org/">pugixml 1.0</a> manual |
|
||||
<a href="../manual.html">Overview</a> |
|
||||
<a href="install.html">Installation</a> |
|
||||
Document:
|
||||
|
|
|
|||
|
|
@ -4,14 +4,15 @@
|
|||
<title>Changelog</title>
|
||||
<link rel="stylesheet" href="../pugixml.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
|
||||
<link rel="home" href="../manual.html" title="pugixml 0.9">
|
||||
<link rel="up" href="../manual.html" title="pugixml 0.9">
|
||||
<link rel="home" href="../manual.html" title="pugixml 1.0">
|
||||
<link rel="up" href="../manual.html" title="pugixml 1.0">
|
||||
<link rel="prev" href="xpath.html" title="XPath">
|
||||
<link rel="next" href="apiref.html" title="API Reference">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table width="100%"><tr>
|
||||
<td>pugixml 0.9 manual |
|
||||
<td>
|
||||
<a href="http://pugixml.org/">pugixml 1.0</a> manual |
|
||||
<a href="../manual.html">Overview</a> |
|
||||
<a href="install.html">Installation</a> |
|
||||
Document:
|
||||
|
|
@ -29,6 +30,224 @@
|
|||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="manual.changes"></a><a class="link" href="changes.html" title="Changelog"> Changelog</a>
|
||||
</h2></div></div></div>
|
||||
<a name="manual.changes.1_11_2010___version_1_0"></a><h6>
|
||||
<a class="link" href="changes.html#manual.changes.1_11_2010___version_1_0">1.11.2010 - version
|
||||
1.0</a>
|
||||
</h6>
|
||||
<p>
|
||||
Major release, featuring many XPath enhancements, wide character filename support,
|
||||
miscellaneous performance improvements, bug fixes and more.
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||||
<li class="listitem">
|
||||
XPath:
|
||||
<div class="orderedlist"><ol class="orderedlist" type="1">
|
||||
<li class="listitem">
|
||||
XPath implementation is moved to pugixml.cpp (which is the only source
|
||||
file now); use PUGIXML_NO_XPATH if you want to disable XPath to reduce
|
||||
code size
|
||||
</li>
|
||||
<li class="listitem">
|
||||
XPath is now supported without exceptions (PUGIXML_NO_EXCEPTIONS);
|
||||
the error handling mechanism depends on the presence of exception
|
||||
support
|
||||
</li>
|
||||
<li class="listitem">
|
||||
XPath is now supported without STL (PUGIXML_NO_STL)
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Introduced variable support
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Introduced new xpath_query::evaluate_string, which works without
|
||||
STL
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Introduced new xpath_node_set constructor (from an iterator range)
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Evaluation function now accept attribute context nodes
|
||||
</li>
|
||||
<li class="listitem">
|
||||
All internal allocations use custom allocation functions
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Improved error reporting; now a last parsed offset is returned together
|
||||
with the parsing error
|
||||
</li>
|
||||
</ol></div>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Bug fixes:
|
||||
<div class="orderedlist"><ol class="orderedlist" type="1">
|
||||
<li class="listitem">
|
||||
Fixed memory leak for loading from streams with stream exceptions
|
||||
turned on
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Fixed custom deallocation function calling with null pointer in one
|
||||
case
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Fixed missing attributes for iterator category functions; all functions/classes
|
||||
can now be DLL-exported
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Worked around Digital Mars compiler bug, which lead to minor read
|
||||
overfetches in several functions
|
||||
</li>
|
||||
<li class="listitem">
|
||||
load_file now works with 2+ Gb files in MSVC/MinGW
|
||||
</li>
|
||||
<li class="listitem">
|
||||
XPath: fixed memory leaks for incorrect queries
|
||||
</li>
|
||||
<li class="listitem">
|
||||
XPath: fixed xpath_node() attribute constructor with empty attribute
|
||||
argument
|
||||
</li>
|
||||
<li class="listitem">
|
||||
XPath: fixed lang() function for non-ASCII arguments
|
||||
</li>
|
||||
</ol></div>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Specification changes:
|
||||
<div class="orderedlist"><ol class="orderedlist" type="1">
|
||||
<li class="listitem">
|
||||
CDATA nodes containing ]]> are printed as several nodes; while
|
||||
this changes the internal structure, this is the only way to escape
|
||||
CDATA contents
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Memory allocation errors during parsing now preserve last parsed
|
||||
offset (to give an idea about parsing progress)
|
||||
</li>
|
||||
<li class="listitem">
|
||||
If an element node has the only child, and it is of CDATA type, then
|
||||
the extra indentation is omitted (previously this behavior only held
|
||||
for PCDATA children)
|
||||
</li>
|
||||
</ol></div>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Additional functionality:
|
||||
<div class="orderedlist"><ol class="orderedlist" type="1">
|
||||
<li class="listitem">
|
||||
Added xml_parse_result default constructor
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Added xml_document::load_file and xml_document::save_file with wide
|
||||
character paths
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Added as_utf8 and as_wide overloads for std::wstring/std::string
|
||||
arguments
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Added DOCTYPE node type (node_doctype) and a special parse flag,
|
||||
parse_doctype, to add such nodes to the document during parsing
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Added parse_full parse flag mask, which extends parse_default with
|
||||
all node type parsing flags except parse_ws_pcdata
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Added xml_node::hash_value() and xml_attribute::hash_value() functions
|
||||
for use in hash-based containers
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Added internal_object() and additional constructor for both xml_node
|
||||
and xml_attribute for easier marshalling (useful for language bindings)
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Added xml_document::document_element() function
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Added xml_node::prepend_attribute, xml_node::prepend_child and xml_node::prepend_copy
|
||||
functions
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Added xml_node::append_child, xml_node::prepend_child, xml_node::insert_child_before
|
||||
and xml_node::insert_child_after overloads for element nodes (with
|
||||
name instead of type)
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Added xml_document::reset() function
|
||||
</li>
|
||||
</ol></div>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Performance improvements:
|
||||
<div class="orderedlist"><ol class="orderedlist" type="1">
|
||||
<li class="listitem">
|
||||
xml_node::root() and xml_node::offset_debug() are now O(1) instead
|
||||
of O(logN)
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Minor parsing optimizations
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Minor memory optimization for strings in DOM tree (set_name/set_value)
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Memory optimization for string memory reclaiming in DOM tree (set_name/set_value
|
||||
now reallocate the buffer if memory waste is too big)
|
||||
</li>
|
||||
<li class="listitem">
|
||||
XPath: optimized document order sorting
|
||||
</li>
|
||||
<li class="listitem">
|
||||
XPath: optimized child/attribute axis step
|
||||
</li>
|
||||
<li class="listitem">
|
||||
XPath: optimized number-to-string conversions in MSVC
|
||||
</li>
|
||||
<li class="listitem">
|
||||
XPath: optimized concat for many arguments
|
||||
</li>
|
||||
<li class="listitem">
|
||||
XPath: optimized evaluation allocation mechanism: constant and document
|
||||
strings are not heap-allocated
|
||||
</li>
|
||||
<li class="listitem">
|
||||
XPath: optimized evaluation allocation mechanism: all temporaries'
|
||||
allocations use fast stack-like allocator
|
||||
</li>
|
||||
</ol></div>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Compatibility:
|
||||
<div class="orderedlist"><ol class="orderedlist" type="1">
|
||||
<li class="listitem">
|
||||
Removed wildcard functions (xml_node::child_w, xml_node::attribute_w,
|
||||
etc.)
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Removed xml_node::all_elements_by_name
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Removed xpath_type_t enumeration; use xpath_value_type instead
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Removed format_write_bom_utf8 enumeration; use format_write_bom instead
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Removed xml_document::precompute_document_order, xml_attribute::document_order
|
||||
and xml_node::document_order functions; document order sort optimization
|
||||
is now automatic
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Removed xml_document::parse functions and transfer_ownership struct;
|
||||
use xml_document::load_buffer_inplace and xml_document::load_buffer_inplace_own
|
||||
instead
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Removed as_utf16 function; use as_wide instead
|
||||
</li>
|
||||
</ol></div>
|
||||
</li>
|
||||
</ul></div>
|
||||
<a name="manual.changes.1_07_2010___version_0_9"></a><h6>
|
||||
<a class="link" href="changes.html#manual.changes.1_07_2010___version_0_9">1.07.2010 - version
|
||||
0.9</a>
|
||||
|
|
@ -548,7 +767,8 @@
|
|||
</tr></table>
|
||||
<hr>
|
||||
<table width="100%"><tr>
|
||||
<td>pugixml 0.9 manual |
|
||||
<td>
|
||||
<a href="http://pugixml.org/">pugixml 1.0</a> manual |
|
||||
<a href="../manual.html">Overview</a> |
|
||||
<a href="install.html">Installation</a> |
|
||||
Document:
|
||||
|
|
|
|||
|
|
@ -4,14 +4,15 @@
|
|||
<title>Document object model</title>
|
||||
<link rel="stylesheet" href="../pugixml.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
|
||||
<link rel="home" href="../manual.html" title="pugixml 0.9">
|
||||
<link rel="up" href="../manual.html" title="pugixml 0.9">
|
||||
<link rel="home" href="../manual.html" title="pugixml 1.0">
|
||||
<link rel="up" href="../manual.html" title="pugixml 1.0">
|
||||
<link rel="prev" href="install.html" title="Installation">
|
||||
<link rel="next" href="loading.html" title="Loading document">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table width="100%"><tr>
|
||||
<td>pugixml 0.9 manual |
|
||||
<td>
|
||||
<a href="http://pugixml.org/">pugixml 1.0</a> manual |
|
||||
<a href="../manual.html">Overview</a> |
|
||||
<a href="install.html">Installation</a> |
|
||||
Document:
|
||||
|
|
@ -46,10 +47,10 @@
|
|||
<p>
|
||||
pugixml stores XML data in DOM-like way: the entire XML document (both document
|
||||
structure and element data) is stored in memory as a tree. The tree can be
|
||||
loaded from character stream (file, string, C++ I/O stream), then traversed
|
||||
via special API or XPath expressions. The whole tree is mutable: both node
|
||||
structure and node/attribute data can be changed at any time. Finally, the
|
||||
result of document transformations can be saved to a character stream (file,
|
||||
loaded from a character stream (file, string, C++ I/O stream), then traversed
|
||||
with the special API or XPath expressions. The whole tree is mutable: both
|
||||
node structure and node/attribute data can be changed at any time. Finally,
|
||||
the result of document transformations can be saved to a character stream (file,
|
||||
C++ I/O stream or custom transport).
|
||||
</p>
|
||||
<div class="section">
|
||||
|
|
@ -58,12 +59,11 @@
|
|||
</h3></div></div></div>
|
||||
<p>
|
||||
The XML document is represented with a tree data structure. The root of the
|
||||
tree is the document itself, which corresponds to C++ type <code class="computeroutput"><span class="identifier">xml_document</span></code>. Document has one or more
|
||||
child nodes, which correspond to C++ type <code class="computeroutput"><span class="identifier">xml_node</span></code>.
|
||||
Nodes have different types; depending on a type, a node can have a collection
|
||||
of child nodes, a collection of attributes, which correspond to C++ type
|
||||
<code class="computeroutput"><span class="identifier">xml_attribute</span></code>, and some additional
|
||||
data (i.e. name).
|
||||
tree is the document itself, which corresponds to C++ type <a class="link" href="dom.html#xml_document">xml_document</a>.
|
||||
Document has one or more child nodes, which correspond to C++ type <a class="link" href="dom.html#xml_node">xml_node</a>. Nodes have different types; depending
|
||||
on a type, a node can have a collection of child nodes, a collection of attributes,
|
||||
which correspond to C++ type <a class="link" href="dom.html#xml_attribute">xml_attribute</a>,
|
||||
and some additional data (i.e. name).
|
||||
</p>
|
||||
<a name="xml_node_type"></a><p>
|
||||
The tree nodes can be of one of the following types (which together form
|
||||
|
|
@ -73,13 +73,13 @@
|
|||
<li class="listitem">
|
||||
Document node (<a name="node_document"></a><code class="literal">node_document</code>) - this
|
||||
is the root of the tree, which consists of several child nodes. This
|
||||
node corresponds to <code class="computeroutput"><span class="identifier">xml_document</span></code>
|
||||
class; note that <code class="computeroutput"><span class="identifier">xml_document</span></code>
|
||||
is a sub-class of <code class="computeroutput"><span class="identifier">xml_node</span></code>,
|
||||
so the entire node interface is also available. However, document node
|
||||
is special in several ways, which will be covered below. There can be
|
||||
only one document node in the tree; document node does not have any XML
|
||||
representation. <br><br>
|
||||
node corresponds to <a class="link" href="dom.html#xml_document">xml_document</a>
|
||||
class; note that <a class="link" href="dom.html#xml_document">xml_document</a> is
|
||||
a sub-class of <a class="link" href="dom.html#xml_node">xml_node</a>, so the entire
|
||||
node interface is also available. However, document node is special in
|
||||
several ways, which are covered below. There can be only one document
|
||||
node in the tree; document node does not have any XML representation.
|
||||
<br><br>
|
||||
|
||||
</li>
|
||||
<li class="listitem">
|
||||
|
|
@ -87,13 +87,13 @@
|
|||
is the most common type of node, which represents XML elements. Element
|
||||
nodes have a name, a collection of attributes and a collection of child
|
||||
nodes (both of which may be empty). The attribute is a simple name/value
|
||||
pair. The example XML representation of element node is as follows:
|
||||
pair. The example XML representation of element nodes is as follows:
|
||||
</li>
|
||||
</ul></div>
|
||||
<pre class="programlisting"><span class="special"><</span><span class="identifier">node</span> <span class="identifier">attr</span><span class="special">=</span><span class="string">"value"</span><span class="special">><</span><span class="identifier">child</span><span class="special">/></</span><span class="identifier">node</span><span class="special">></span>
|
||||
</pre>
|
||||
<div class="blockquote"><blockquote class="blockquote"><p>
|
||||
There are two element nodes here; one has name <code class="computeroutput"><span class="string">"node"</span></code>,
|
||||
There are two element nodes here: one has name <code class="computeroutput"><span class="string">"node"</span></code>,
|
||||
single attribute <code class="computeroutput"><span class="string">"attr"</span></code>
|
||||
and single child <code class="computeroutput"><span class="string">"child"</span></code>,
|
||||
another has name <code class="computeroutput"><span class="string">"child"</span></code>
|
||||
|
|
@ -102,10 +102,10 @@
|
|||
<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
|
||||
Plain character data nodes (<a name="node_pcdata"></a><code class="literal">node_pcdata</code>)
|
||||
represent plain text in XML. PCDATA nodes have a value, but do not have
|
||||
name or children/attributes. Note that plain character data is not a
|
||||
part of the element node but instead has its own node; for example, an
|
||||
element node can have several child PCDATA nodes. The example XML representation
|
||||
of text node is as follows:
|
||||
a name or children/attributes. Note that plain character data is not
|
||||
a part of the element node but instead has its own node; for example,
|
||||
an element node can have several child PCDATA nodes. The example XML
|
||||
representation of text nodes is as follows:
|
||||
</li></ul></div>
|
||||
<pre class="programlisting"><span class="special"><</span><span class="identifier">node</span><span class="special">></span> <span class="identifier">text1</span> <span class="special"><</span><span class="identifier">child</span><span class="special">/></span> <span class="identifier">text2</span> <span class="special"></</span><span class="identifier">node</span><span class="special">></span>
|
||||
</pre>
|
||||
|
|
@ -128,9 +128,9 @@
|
|||
</p></blockquote></div>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
|
||||
Comment nodes (<a name="node_comment"></a><code class="literal">node_comment</code>) represent
|
||||
comments in XML. Comment nodes have a value, but do not have name or
|
||||
children/attributes. The example XML representation of comment node is
|
||||
as follows:
|
||||
comments in XML. Comment nodes have a value, but do not have a name or
|
||||
children/attributes. The example XML representation of a comment node
|
||||
is as follows:
|
||||
</li></ul></div>
|
||||
<pre class="programlisting"><span class="special"><!--</span> <span class="identifier">comment</span> <span class="identifier">text</span> <span class="special">--></span>
|
||||
</pre>
|
||||
|
|
@ -138,14 +138,14 @@
|
|||
Here the comment node has value <code class="computeroutput"><span class="string">"comment
|
||||
text"</span></code>. By default comment nodes are treated as non-essential
|
||||
part of XML markup and are not loaded during XML parsing. You can override
|
||||
this behavior by adding <code class="computeroutput"><span class="identifier">parse_comments</span></code>
|
||||
this behavior with <a class="link" href="loading.html#parse_comments">parse_comments</a>
|
||||
flag.
|
||||
</p></blockquote></div>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
|
||||
Processing instruction node (<a name="node_pi"></a><code class="literal">node_pi</code>) represent
|
||||
processing instructions (PI) in XML. PI nodes have a name and an optional
|
||||
value, but do not have children/attributes. The example XML representation
|
||||
of PI node is as follows:
|
||||
of a PI node is as follows:
|
||||
</li></ul></div>
|
||||
<pre class="programlisting"><span class="special"><?</span><span class="identifier">name</span> <span class="identifier">value</span><span class="special">?></span>
|
||||
</pre>
|
||||
|
|
@ -153,17 +153,17 @@
|
|||
Here the name (also called PI target) is <code class="computeroutput"><span class="string">"name"</span></code>,
|
||||
and the value is <code class="computeroutput"><span class="string">"value"</span></code>.
|
||||
By default PI nodes are treated as non-essential part of XML markup and
|
||||
are not loaded during XML parsing. You can override this behavior by adding
|
||||
<code class="computeroutput"><span class="identifier">parse_pi</span></code> flag.
|
||||
are not loaded during XML parsing. You can override this behavior with
|
||||
<a class="link" href="loading.html#parse_pi">parse_pi</a> flag.
|
||||
</p></blockquote></div>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
|
||||
Declaration node (<a name="node_declaration"></a><code class="literal">node_declaration</code>)
|
||||
represents document declarations in XML. Declaration nodes have a name
|
||||
(<code class="computeroutput"><span class="string">"xml"</span></code>) and an
|
||||
optional collection of attributes, but does not have value or children.
|
||||
optional collection of attributes, but do not have value or children.
|
||||
There can be only one declaration node in a document; moreover, it should
|
||||
be the topmost node (its parent should be the document). The example
|
||||
XML representation of declaration node is as follows:
|
||||
XML representation of a declaration node is as follows:
|
||||
</li></ul></div>
|
||||
<pre class="programlisting"><span class="special"><?</span><span class="identifier">xml</span> <span class="identifier">version</span><span class="special">=</span><span class="string">"1.0"</span><span class="special">?></span>
|
||||
</pre>
|
||||
|
|
@ -172,12 +172,28 @@
|
|||
and a single attribute with name <code class="computeroutput"><span class="string">"version"</span></code>
|
||||
and value <code class="computeroutput"><span class="string">"1.0"</span></code>.
|
||||
By default declaration nodes are treated as non-essential part of XML markup
|
||||
and are not loaded during XML parsing. You can override this behavior by
|
||||
adding <code class="computeroutput"><span class="identifier">parse_declaration</span></code>
|
||||
flag. Also, by default a dummy declaration is output when XML document
|
||||
is saved unless there is already a declaration in the document; you can
|
||||
disable this by adding <code class="computeroutput"><span class="identifier">format_no_declaration</span></code>
|
||||
flag.
|
||||
and are not loaded during XML parsing. You can override this behavior with
|
||||
<a class="link" href="loading.html#parse_declaration">parse_declaration</a> flag. Also,
|
||||
by default a dummy declaration is output when XML document is saved unless
|
||||
there is already a declaration in the document; you can disable this with
|
||||
<a class="link" href="saving.html#format_no_declaration">format_no_declaration</a> flag.
|
||||
</p></blockquote></div>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
|
||||
Document type declaration node (<a name="node_doctype"></a><code class="literal">node_doctype</code>)
|
||||
represents document type declarations in XML. Document type declaration
|
||||
nodes have a value, which corresponds to the entire document type contents;
|
||||
no additional nodes are created for inner elements like <code class="computeroutput"><span class="special"><!</span><span class="identifier">ENTITY</span><span class="special">></span></code>. There can be only one document type
|
||||
declaration node in a document; moreover, it should be the topmost node
|
||||
(its parent should be the document). The example XML representation of
|
||||
a document type declaration node is as follows:
|
||||
</li></ul></div>
|
||||
<pre class="programlisting"><span class="special"><!</span><span class="identifier">DOCTYPE</span> <span class="identifier">greeting</span> <span class="special">[</span> <span class="special"><!</span><span class="identifier">ELEMENT</span> <span class="identifier">greeting</span> <span class="special">(</span><span class="preprocessor">#PCDATA</span><span class="special">)></span> <span class="special">]></span>
|
||||
</pre>
|
||||
<div class="blockquote"><blockquote class="blockquote"><p>
|
||||
Here the node has value <code class="computeroutput"><span class="string">"greeting [ <!ELEMENT
|
||||
greeting (#PCDATA)> ]"</span></code>. By default document type
|
||||
declaration nodes are treated as non-essential part of XML markup and are
|
||||
not loaded during XML parsing. You can override this behavior with <a class="link" href="loading.html#parse_doctype">parse_doctype</a> flag.
|
||||
</p></blockquote></div>
|
||||
<p>
|
||||
Finally, here is a complete example of XML document and the corresponding
|
||||
|
|
@ -227,40 +243,45 @@
|
|||
<th align="left">Note</th>
|
||||
</tr>
|
||||
<tr><td align="left" valign="top"><p>
|
||||
All pugixml classes and functions are located in <code class="computeroutput"><span class="identifier">pugi</span></code>
|
||||
All pugixml classes and functions are located in the <code class="computeroutput"><span class="identifier">pugi</span></code>
|
||||
namespace; you have to either use explicit name qualification (i.e. <code class="computeroutput"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span></code>), or to gain access to relevant
|
||||
symbols via <code class="computeroutput"><span class="keyword">using</span></code> directive
|
||||
(i.e. <code class="computeroutput"><span class="keyword">using</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span><span class="special">;</span></code> or <code class="computeroutput"><span class="keyword">using</span>
|
||||
<span class="keyword">namespace</span> <span class="identifier">pugi</span><span class="special">;</span></code>). The namespace will be omitted from declarations
|
||||
in this documentation hereafter; all code examples will use fully-qualified
|
||||
names.
|
||||
<span class="keyword">namespace</span> <span class="identifier">pugi</span><span class="special">;</span></code>). The namespace will be omitted from all
|
||||
declarations in this documentation hereafter; all code examples will use
|
||||
fully qualified names.
|
||||
</p></td></tr>
|
||||
</table></div>
|
||||
<p>
|
||||
Despite the fact that there are several node types, there are only three
|
||||
C++ types representing the tree (<code class="computeroutput"><span class="identifier">xml_document</span></code>,
|
||||
C++ classes representing the tree (<code class="computeroutput"><span class="identifier">xml_document</span></code>,
|
||||
<code class="computeroutput"><span class="identifier">xml_node</span></code>, <code class="computeroutput"><span class="identifier">xml_attribute</span></code>);
|
||||
some operations on <code class="computeroutput"><span class="identifier">xml_node</span></code>
|
||||
are only valid for certain node types. They are described below.
|
||||
are only valid for certain node types. The classes are described below.
|
||||
</p>
|
||||
<a name="xml_document"></a><p>
|
||||
<a name="xml_document"></a><a name="xml_document::document_element"></a><p>
|
||||
<code class="computeroutput"><span class="identifier">xml_document</span></code> is the owner
|
||||
of the entire document structure; it is a non-copyable class. The interface
|
||||
of <code class="computeroutput"><span class="identifier">xml_document</span></code> consists
|
||||
of loading functions (see <a class="xref" href="loading.html" title="Loading document"> Loading document</a>), saving functions (see <a class="xref" href="saving.html" title="Saving document"> Saving document</a>)
|
||||
and the interface of <code class="computeroutput"><span class="identifier">xml_node</span></code>,
|
||||
and the entire interface of <code class="computeroutput"><span class="identifier">xml_node</span></code>,
|
||||
which allows for document inspection and/or modification. Note that while
|
||||
<code class="computeroutput"><span class="identifier">xml_document</span></code> is a sub-class
|
||||
of <code class="computeroutput"><span class="identifier">xml_node</span></code>, <code class="computeroutput"><span class="identifier">xml_node</span></code> is not a polymorphic type; the
|
||||
inheritance is only used to simplify usage.
|
||||
inheritance is present only to simplify usage. Alternatively you can use
|
||||
the <code class="computeroutput"><span class="identifier">document_element</span></code> function
|
||||
to get the element node that's the immediate child of the document.
|
||||
</p>
|
||||
<a name="xml_document::ctor"></a><a name="xml_document::dtor"></a><p>
|
||||
<a name="xml_document::ctor"></a><a name="xml_document::dtor"></a><a name="xml_document::reset"></a><p>
|
||||
Default constructor of <code class="computeroutput"><span class="identifier">xml_document</span></code>
|
||||
initializes the document to the tree with only a root node (document node).
|
||||
You can then populate it with data using either tree modification functions
|
||||
or loading functions; all loading functions destroy the previous tree with
|
||||
all occupied memory, which puts existing nodes/attributes from this document
|
||||
to invalid state. Destructor of <code class="computeroutput"><span class="identifier">xml_document</span></code>
|
||||
all occupied memory, which puts existing node/attribute handles for this
|
||||
document to invalid state. If you want to destroy the previous tree, you
|
||||
can use the <code class="computeroutput"><span class="identifier">xml_document</span><span class="special">::</span><span class="identifier">reset</span></code>
|
||||
function; it destroys the tree and replaces it with either an empty one or
|
||||
a copy of the specified document. Destructor of <code class="computeroutput"><span class="identifier">xml_document</span></code>
|
||||
also destroys the tree, thus the lifetime of the document object should exceed
|
||||
the lifetimes of any node/attribute handles that point to the tree.
|
||||
</p>
|
||||
|
|
@ -271,7 +292,7 @@
|
|||
</tr>
|
||||
<tr><td align="left" valign="top"><p>
|
||||
While technically node/attribute handles can be alive when the tree they're
|
||||
referring to is destroyed, calling any member function of these handles
|
||||
referring to is destroyed, calling any member function for these handles
|
||||
results in undefined behavior. Thus it is recommended to make sure that
|
||||
the document is destroyed only after all references to its nodes/attributes
|
||||
are destroyed.
|
||||
|
|
@ -279,16 +300,17 @@
|
|||
</table></div>
|
||||
<a name="xml_node"></a><a name="xml_node::type"></a><p>
|
||||
<code class="computeroutput"><span class="identifier">xml_node</span></code> is the handle to
|
||||
document node; it can point to any node in the document, including document
|
||||
itself. There is a common interface for nodes of all types; the actual node
|
||||
type can be queried via <code class="computeroutput"><span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">type</span><span class="special">()</span></code> method. Note that <code class="computeroutput"><span class="identifier">xml_node</span></code>
|
||||
document node; it can point to any node in the document, including the document
|
||||
node itself. There is a common interface for nodes of all types; the actual
|
||||
<a class="link" href="dom.html#xml_node_type">node type</a> can be queried via the <code class="computeroutput"><span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">type</span><span class="special">()</span></code>
|
||||
method. Note that <code class="computeroutput"><span class="identifier">xml_node</span></code>
|
||||
is only a handle to the actual node, not the node itself - you can have several
|
||||
<code class="computeroutput"><span class="identifier">xml_node</span></code> handles pointing
|
||||
to the same underlying object. Destroying <code class="computeroutput"><span class="identifier">xml_node</span></code>
|
||||
handle does not destroy the node and does not remove it from the tree. The
|
||||
size of <code class="computeroutput"><span class="identifier">xml_node</span></code> is equal
|
||||
to that of a pointer, so it is nothing more than a lightweight wrapper around
|
||||
pointer; you can safely pass or return <code class="computeroutput"><span class="identifier">xml_node</span></code>
|
||||
a pointer; you can safely pass or return <code class="computeroutput"><span class="identifier">xml_node</span></code>
|
||||
objects by value without additional overhead.
|
||||
</p>
|
||||
<a name="node_null"></a><p>
|
||||
|
|
@ -300,14 +322,14 @@
|
|||
for specific functions for more detailed information). This is useful for
|
||||
chaining calls; i.e. you can get the grandparent of a node like so: <code class="computeroutput"><span class="identifier">node</span><span class="special">.</span><span class="identifier">parent</span><span class="special">().</span><span class="identifier">parent</span><span class="special">()</span></code>; if a node is a null node or it does not
|
||||
have a parent, the first <code class="computeroutput"><span class="identifier">parent</span><span class="special">()</span></code> call returns null node; the second <code class="computeroutput"><span class="identifier">parent</span><span class="special">()</span></code>
|
||||
call then also returns null node, so you don't have to check for errors twice.
|
||||
call then also returns null node, which makes error handling easier.
|
||||
</p>
|
||||
<a name="xml_attribute"></a><p>
|
||||
<code class="computeroutput"><span class="identifier">xml_attribute</span></code> is the handle
|
||||
to an XML attribute; it has the same semantics as <code class="computeroutput"><span class="identifier">xml_node</span></code>,
|
||||
i.e. there can be several <code class="computeroutput"><span class="identifier">xml_attribute</span></code>
|
||||
handles pointing to the same underlying object, there is a special null attribute
|
||||
value, which propagates to function results.
|
||||
handles pointing to the same underlying object and there is a special null
|
||||
attribute value, which propagates to function results.
|
||||
</p>
|
||||
<a name="xml_attribute::ctor"></a><a name="xml_node::ctor"></a><p>
|
||||
Both <code class="computeroutput"><span class="identifier">xml_node</span></code> and <code class="computeroutput"><span class="identifier">xml_attribute</span></code> have the default constructor
|
||||
|
|
@ -316,16 +338,23 @@
|
|||
<a name="xml_attribute::comparison"></a><a name="xml_node::comparison"></a><p>
|
||||
<code class="computeroutput"><span class="identifier">xml_node</span></code> and <code class="computeroutput"><span class="identifier">xml_attribute</span></code> try to behave like pointers,
|
||||
that is, they can be compared with other objects of the same type, making
|
||||
it possible to use them as keys of associative containers. All handles to
|
||||
it possible to use them as keys in associative containers. All handles to
|
||||
the same underlying object are equal, and any two handles to different underlying
|
||||
objects are not equal. Null handles only compare as equal to themselves.
|
||||
The result of relational comparison can not be reliably determined from the
|
||||
order of nodes in file or other ways. Do not use relational comparison operators
|
||||
except for search optimization (i.e. associative container keys).
|
||||
order of nodes in file or in any other way. Do not use relational comparison
|
||||
operators except for search optimization (i.e. associative container keys).
|
||||
</p>
|
||||
<a name="xml_attribute::hash_value"></a><a name="xml_node::hash_value"></a><p>
|
||||
If you want to use <code class="computeroutput"><span class="identifier">xml_node</span></code>
|
||||
or <code class="computeroutput"><span class="identifier">xml_attribute</span></code> objects
|
||||
as keys in hash-based associative containers, you can use the <code class="computeroutput"><span class="identifier">hash_value</span></code> member functions. They return
|
||||
the hash values that are guaranteed to be the same for all handles to the
|
||||
same underlying object. The hash value for null handles is 0.
|
||||
</p>
|
||||
<a name="xml_attribute::unspecified_bool_type"></a><a name="xml_node::unspecified_bool_type"></a><a name="xml_attribute::empty"></a><a name="xml_node::empty"></a><p>
|
||||
Additionally handles they can be implicitly cast to boolean-like objects,
|
||||
so that you can test if the node/attribute is empty by just doing <code class="computeroutput"><span class="keyword">if</span> <span class="special">(</span><span class="identifier">node</span><span class="special">)</span> <span class="special">{</span> <span class="special">...</span>
|
||||
Finally handles can be implicitly cast to boolean-like objects, so that you
|
||||
can test if the node/attribute is empty with the following code: <code class="computeroutput"><span class="keyword">if</span> <span class="special">(</span><span class="identifier">node</span><span class="special">)</span> <span class="special">{</span> <span class="special">...</span>
|
||||
<span class="special">}</span></code> or <code class="computeroutput"><span class="keyword">if</span>
|
||||
<span class="special">(!</span><span class="identifier">node</span><span class="special">)</span> <span class="special">{</span> <span class="special">...</span>
|
||||
<span class="special">}</span> <span class="keyword">else</span> <span class="special">{</span> <span class="special">...</span> <span class="special">}</span></code>.
|
||||
|
|
@ -336,13 +365,14 @@
|
|||
<span class="keyword">bool</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">empty</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
Nodes and attributes do not exist outside of document tree, so you can't
|
||||
create them without adding them to some document. Once underlying node/attribute
|
||||
Nodes and attributes do not exist without a document tree, so you can't create
|
||||
them without adding them to some document. Once underlying node/attribute
|
||||
objects are destroyed, the handles to those objects become invalid. While
|
||||
this means that destruction of the entire tree invalidates all node/attribute
|
||||
handles, it also means that destroying a subtree (by calling <code class="computeroutput"><span class="identifier">remove_child</span></code>) or removing an attribute
|
||||
invalidates the corresponding handles. There is no way to check handle validity;
|
||||
you have to ensure correctness through external mechanisms.
|
||||
handles, it also means that destroying a subtree (by calling <a class="link" href="modify.html#xml_node::remove_child">xml_node::remove_child</a>)
|
||||
or removing an attribute invalidates the corresponding handles. There is
|
||||
no way to check handle validity; you have to ensure correctness through external
|
||||
mechanisms.
|
||||
</p>
|
||||
</div>
|
||||
<div class="section">
|
||||
|
|
@ -352,12 +382,14 @@
|
|||
<p>
|
||||
There are two choices of interface and internal representation when configuring
|
||||
pugixml: you can either choose the UTF-8 (also called char) interface or
|
||||
UTF-16/32 (also called wchar_t) one. The choice is controlled via <code class="computeroutput"><span class="identifier">PUGIXML_WCHAR_MODE</span></code> define; you can set
|
||||
it via <code class="filename">pugiconfig.hpp</code> or via preprocessor options, as discussed in <a class="xref" href="install.html#manual.install.building.config" title="Additional configuration options"> Additional configuration
|
||||
options</a>.
|
||||
If this define is set, the wchar_t interface is used; otherwise (by default)
|
||||
the char interface is used. The exact wide character encoding is assumed
|
||||
to be either UTF-16 or UTF-32 and is determined based on size of <code class="computeroutput"><span class="keyword">wchar_t</span></code> type.
|
||||
UTF-16/32 (also called wchar_t) one. The choice is controlled via <a class="link" href="install.html#PUGIXML_WCHAR_MODE">PUGIXML_WCHAR_MODE</a>
|
||||
define; you can set it via <code class="filename">pugiconfig.hpp</code> or via preprocessor options, as
|
||||
discussed in <a class="xref" href="install.html#manual.install.building.config" title="Additional configuration options"> Additional configuration
|
||||
options</a>. If this define is set, the wchar_t
|
||||
interface is used; otherwise (by default) the char interface is used. The
|
||||
exact wide character encoding is assumed to be either UTF-16 or UTF-32 and
|
||||
is determined based on the size of <code class="computeroutput"><span class="keyword">wchar_t</span></code>
|
||||
type.
|
||||
</p>
|
||||
<div class="note"><table border="0" summary="Note">
|
||||
<tr>
|
||||
|
|
@ -365,9 +397,9 @@
|
|||
<th align="left">Note</th>
|
||||
</tr>
|
||||
<tr><td align="left" valign="top"><p>
|
||||
If size of <code class="computeroutput"><span class="keyword">wchar_t</span></code> is 2, pugixml
|
||||
assumes UTF-16 encoding instead of UCS-2, which means that some characters
|
||||
are represented as two code points.
|
||||
If the size of <code class="computeroutput"><span class="keyword">wchar_t</span></code> is
|
||||
2, pugixml assumes UTF-16 encoding instead of UCS-2, which means that some
|
||||
characters are represented as two code points.
|
||||
</p></td></tr>
|
||||
</table></div>
|
||||
<p>
|
||||
|
|
@ -399,7 +431,7 @@
|
|||
<code class="computeroutput"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">char_t</span></code> upon document saving happen automatically,
|
||||
which also carries minor performance penalty. The general advice however
|
||||
is to select the character mode based on usage scenario, i.e. if UTF-8 is
|
||||
inconvenient to process and most of your XML data is localized, wchar_t mode
|
||||
inconvenient to process and most of your XML data is non-ASCII, wchar_t mode
|
||||
is probably a better choice.
|
||||
</p>
|
||||
<a name="as_utf8"></a><a name="as_wide"></a><p>
|
||||
|
|
@ -410,13 +442,18 @@
|
|||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">wstring</span> <span class="identifier">as_wide</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">str</span><span class="special">);</span>
|
||||
</pre>
|
||||
<p>
|
||||
Both functions accept null-terminated string as an argument <code class="computeroutput"><span class="identifier">str</span></code>, and return the converted string.
|
||||
Both functions accept a null-terminated string as an argument <code class="computeroutput"><span class="identifier">str</span></code>, and return the converted string.
|
||||
<code class="computeroutput"><span class="identifier">as_utf8</span></code> performs conversion
|
||||
from UTF-16/32 to UTF-8; <code class="computeroutput"><span class="identifier">as_wide</span></code>
|
||||
performs conversion from UTF-8 to UTF-16/32. Invalid UTF sequences are silently
|
||||
discarded upon conversion. <code class="computeroutput"><span class="identifier">str</span></code>
|
||||
has to be a valid string; passing null pointer results in undefined behavior.
|
||||
There are also two overloads with the same semantics which accept a string
|
||||
as an argument:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">as_utf8</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">wstring</span><span class="special">&</span> <span class="identifier">str</span><span class="special">);</span>
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">wstring</span> <span class="identifier">as_wide</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&</span> <span class="identifier">str</span><span class="special">);</span>
|
||||
</pre>
|
||||
<div class="note"><table border="0" summary="Note">
|
||||
<tr>
|
||||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
|
||||
|
|
@ -425,8 +462,8 @@
|
|||
<tr><td align="left" valign="top">
|
||||
<p>
|
||||
Most examples in this documentation assume char interface and therefore
|
||||
will not compile with <code class="computeroutput"><span class="identifier">PUGIXML_WCHAR_MODE</span></code>.
|
||||
This is to simplify the documentation; usually the only changes you'll
|
||||
will not compile with <a class="link" href="install.html#PUGIXML_WCHAR_MODE">PUGIXML_WCHAR_MODE</a>.
|
||||
This is done to simplify the documentation; usually the only changes you'll
|
||||
have to make is to pass <code class="computeroutput"><span class="keyword">wchar_t</span></code>
|
||||
string literals, i.e. instead of
|
||||
</p>
|
||||
|
|
@ -453,7 +490,7 @@
|
|||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||||
<li class="listitem">
|
||||
it is safe to call free functions from multiple threads
|
||||
it is safe to call free (non-member) functions from multiple threads
|
||||
</li>
|
||||
<li class="listitem">
|
||||
it is safe to perform concurrent read-only accesses to the same tree
|
||||
|
|
@ -470,7 +507,7 @@
|
|||
structure and altering individual node/attribute data, i.e. changing names/values.
|
||||
</p>
|
||||
<p>
|
||||
The only exception is <code class="computeroutput"><span class="identifier">set_memory_management_functions</span></code>;
|
||||
The only exception is <a class="link" href="dom.html#set_memory_management_functions">set_memory_management_functions</a>;
|
||||
it modifies global variables and as such is not thread-safe. Its usage policy
|
||||
has more restrictions, see <a class="xref" href="dom.html#manual.dom.memory.custom" title="Custom memory allocation/deallocation functions"> Custom memory allocation/deallocation
|
||||
functions</a>.
|
||||
|
|
@ -488,15 +525,16 @@
|
|||
This is not applicable to functions that operate on STL strings or IOstreams;
|
||||
such functions have either strong guarantee (functions that operate on strings)
|
||||
or basic guarantee (functions that operate on streams). Also functions that
|
||||
call user-defined callbacks (i.e. <code class="computeroutput"><span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">traverse</span></code>
|
||||
or <code class="computeroutput"><span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">find_node</span></code>) do not provide any exception
|
||||
guarantees beyond the ones provided by callback.
|
||||
call user-defined callbacks (i.e. <a class="link" href="access.html#xml_node::traverse">xml_node::traverse</a>
|
||||
or <a class="link" href="access.html#xml_node::find_node">xml_node::find_node</a>) do not
|
||||
provide any exception guarantees beyond the ones provided by the callback.
|
||||
</p>
|
||||
<p>
|
||||
XPath functions may throw <code class="computeroutput"><span class="identifier">xpath_exception</span></code>
|
||||
on parsing error; also, XPath implementation uses STL, and thus may throw
|
||||
i.e. <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bad_alloc</span></code> in low memory conditions. Still,
|
||||
XPath functions provide strong exception guarantee.
|
||||
If exception handling is not disabled with <a class="link" href="install.html#PUGIXML_NO_EXCEPTIONS">PUGIXML_NO_EXCEPTIONS</a>
|
||||
define, XPath functions may throw <a class="link" href="xpath.html#xpath_exception">xpath_exception</a>
|
||||
on parsing errors; also, XPath functions may throw <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bad_alloc</span></code>
|
||||
in low memory conditions. Still, XPath functions provide strong exception
|
||||
guarantee.
|
||||
</p>
|
||||
</div>
|
||||
<div class="section">
|
||||
|
|
@ -514,10 +552,10 @@
|
|||
functions</a>
|
||||
</h4></div></div></div>
|
||||
<a name="allocation_function"></a><a name="deallocation_function"></a><p>
|
||||
All memory for tree structure/data is allocated via globally specified
|
||||
functions, which default to malloc/free. You can set your own allocation
|
||||
functions with set_memory_management functions. The function interfaces
|
||||
are the same as that of malloc/free:
|
||||
All memory for tree structure, tree data and XPath objects is allocated
|
||||
via globally specified functions, which default to malloc/free. You can
|
||||
set your own allocation functions with set_memory_management function.
|
||||
The function interfaces are the same as that of malloc/free:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">typedef</span> <span class="keyword">void</span><span class="special">*</span> <span class="special">(*</span><span class="identifier">allocation_function</span><span class="special">)(</span><span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">);</span>
|
||||
<span class="keyword">typedef</span> <span class="keyword">void</span> <span class="special">(*</span><span class="identifier">deallocation_function</span><span class="special">)(</span><span class="keyword">void</span><span class="special">*</span> <span class="identifier">ptr</span><span class="special">);</span>
|
||||
|
|
@ -532,14 +570,18 @@
|
|||
</pre>
|
||||
<p>
|
||||
Allocation function is called with the size (in bytes) as an argument and
|
||||
should return a pointer to memory block with alignment that is suitable
|
||||
for pointer storage and size that is greater or equal to the requested
|
||||
one. If the allocation fails, the function has to return null pointer (throwing
|
||||
an exception from allocation function results in undefined behavior). Deallocation
|
||||
function is called with the pointer that was returned by the previous call
|
||||
or with a null pointer; null pointer deallocation should be handled as
|
||||
a no-op. If memory management functions are not thread-safe, library thread
|
||||
safety is not guaranteed.
|
||||
should return a pointer to a memory block with alignment that is suitable
|
||||
for storage of primitive types (usually a maximum of <code class="computeroutput"><span class="keyword">void</span><span class="special">*</span></code> and <code class="computeroutput"><span class="keyword">double</span></code>
|
||||
types alignment is sufficient) and size that is greater than or equal to
|
||||
the requested one. If the allocation fails, the function has to return
|
||||
null pointer (throwing an exception from allocation function results in
|
||||
undefined behavior).
|
||||
</p>
|
||||
<p>
|
||||
Deallocation function is called with the pointer that was returned by some
|
||||
call to allocation function; it is never called with a null pointer. If
|
||||
memory management functions are not thread-safe, library thread safety
|
||||
is not guaranteed.
|
||||
</p>
|
||||
<p>
|
||||
This is a simple example of custom memory management (<a href="../samples/custom_memory_management.cpp" target="_top">samples/custom_memory_management.cpp</a>):
|
||||
|
|
@ -572,16 +614,6 @@
|
|||
are destroyed, the new deallocation function will be called with the memory
|
||||
obtained by the old allocation function, resulting in undefined behavior.
|
||||
</p>
|
||||
<div class="note"><table border="0" summary="Note">
|
||||
<tr>
|
||||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
|
||||
<th align="left">Note</th>
|
||||
</tr>
|
||||
<tr><td align="left" valign="top"><p>
|
||||
Currently memory for XPath objects is allocated using default operators
|
||||
new/delete; this will change in the next version.
|
||||
</p></td></tr>
|
||||
</table></div>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h4 class="title">
|
||||
|
|
@ -590,7 +622,7 @@
|
|||
</h4></div></div></div>
|
||||
<p>
|
||||
Constructing a document object using the default constructor does not result
|
||||
in any allocations; document node is stored inside the <code class="computeroutput"><span class="identifier">xml_document</span></code>
|
||||
in any allocations; document node is stored inside the <a class="link" href="dom.html#xml_document">xml_document</a>
|
||||
object.
|
||||
</p>
|
||||
<p>
|
||||
|
|
@ -598,11 +630,11 @@
|
|||
function is used (see <a class="xref" href="loading.html#manual.loading.memory" title="Loading document from memory"> Loading document from memory</a>), a complete copy of character
|
||||
stream is made; all names/values of nodes and attributes are allocated
|
||||
in this buffer. This buffer is allocated via a single large allocation
|
||||
and is only freed when document memory is reclaimed (i.e. if the <code class="computeroutput"><span class="identifier">xml_document</span></code> object is destroyed or if
|
||||
another document is loaded in the same object). Also when loading from
|
||||
file or stream, an additional large allocation may be performed if encoding
|
||||
conversion is required; a temporary buffer is allocated, and it is freed
|
||||
before load function returns.
|
||||
and is only freed when document memory is reclaimed (i.e. if the <a class="link" href="dom.html#xml_document">xml_document</a> object is destroyed or if another
|
||||
document is loaded in the same object). Also when loading from file or
|
||||
stream, an additional large allocation may be performed if encoding conversion
|
||||
is required; a temporary buffer is allocated, and it is freed before load
|
||||
function returns.
|
||||
</p>
|
||||
<p>
|
||||
All additional memory, such as memory for document structure (node/attribute
|
||||
|
|
@ -632,7 +664,8 @@
|
|||
</tr></table>
|
||||
<hr>
|
||||
<table width="100%"><tr>
|
||||
<td>pugixml 0.9 manual |
|
||||
<td>
|
||||
<a href="http://pugixml.org/">pugixml 1.0</a> manual |
|
||||
<a href="../manual.html">Overview</a> |
|
||||
<a href="install.html">Installation</a> |
|
||||
Document:
|
||||
|
|
|
|||
|
|
@ -4,14 +4,15 @@
|
|||
<title>Installation</title>
|
||||
<link rel="stylesheet" href="../pugixml.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
|
||||
<link rel="home" href="../manual.html" title="pugixml 0.9">
|
||||
<link rel="up" href="../manual.html" title="pugixml 0.9">
|
||||
<link rel="prev" href="../manual.html" title="pugixml 0.9">
|
||||
<link rel="home" href="../manual.html" title="pugixml 1.0">
|
||||
<link rel="up" href="../manual.html" title="pugixml 1.0">
|
||||
<link rel="prev" href="../manual.html" title="pugixml 1.0">
|
||||
<link rel="next" href="dom.html" title="Document object model">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table width="100%"><tr>
|
||||
<td>pugixml 0.9 manual |
|
||||
<td>
|
||||
<a href="http://pugixml.org/">pugixml 1.0</a> manual |
|
||||
<a href="../manual.html">Overview</a> |
|
||||
<b>Installation</b> |
|
||||
Document:
|
||||
|
|
@ -64,14 +65,16 @@
|
|||
You can download the latest source distribution via one of the following
|
||||
links:
|
||||
</p>
|
||||
<pre class="programlisting"><a href="http://pugixml.googlecode.com/files/pugixml-0.9.zip" target="_top">http://pugixml.googlecode.com/files/pugixml-0.9.zip</a>
|
||||
<a href="http://pugixml.googlecode.com/files/pugixml-0.9.tar.gz" target="_top">http://pugixml.googlecode.com/files/pugixml-0.9.tar.gz</a>
|
||||
<pre class="programlisting"><a href="http://pugixml.googlecode.com/files/pugixml-1.0.zip" target="_top">http://pugixml.googlecode.com/files/pugixml-1.0.zip</a>
|
||||
<a href="http://pugixml.googlecode.com/files/pugixml-1.0.tar.gz" target="_top">http://pugixml.googlecode.com/files/pugixml-1.0.tar.gz</a>
|
||||
</pre>
|
||||
<p>
|
||||
The distribution contains library source, documentation (the manual you're
|
||||
reading now and the quick start guide) and some code examples. After downloading
|
||||
the distribution, install pugixml by extracting all files from the compressed
|
||||
archive.
|
||||
archive. The files have different line endings depending on the archive
|
||||
format - <code class="filename">.zip</code> archive has Windows line endings, <code class="filename">.tar.gz</code> archive has Unix
|
||||
line endings. Otherwise the files in both archives are identical.
|
||||
</p>
|
||||
<p>
|
||||
If you need an older version, you can download it from the <a href="http://code.google.com/p/pugixml/downloads/list" target="_top">version
|
||||
|
|
@ -91,7 +94,7 @@
|
|||
<p>
|
||||
For example, to checkout the current version, you can use this command:
|
||||
</p>
|
||||
<pre class="programlisting">svn checkout http://pugixml.googlecode.com/svn/tags/release-0.9 pugixml</pre>
|
||||
<pre class="programlisting">svn checkout http://pugixml.googlecode.com/svn/tags/release-1.0 pugixml</pre>
|
||||
<p>
|
||||
To checkout the latest version, you can use this command:
|
||||
</p>
|
||||
|
|
@ -120,9 +123,9 @@
|
|||
have to build them yourself.
|
||||
</p>
|
||||
<p>
|
||||
The complete pugixml source consists of four files - two source files, <code class="filename">pugixml.cpp</code> and
|
||||
<code class="filename">pugixpath.cpp</code>, and two header files, <code class="filename">pugixml.hpp</code> and <code class="filename">pugiconfig.hpp</code>. <code class="filename">pugixml.hpp</code> is
|
||||
the primary header which you need to include in order to use pugixml classes/functions;
|
||||
The complete pugixml source consists of three files - one source file, <code class="filename">pugixml.cpp</code>,
|
||||
and two header files, <code class="filename">pugixml.hpp</code> and <code class="filename">pugiconfig.hpp</code>. <code class="filename">pugixml.hpp</code> is the primary
|
||||
header which you need to include in order to use pugixml classes/functions;
|
||||
<code class="filename">pugiconfig.hpp</code> is a supplementary configuration file (see <a class="xref" href="install.html#manual.install.building.config" title="Additional configuration options"> Additional configuration
|
||||
options</a>).
|
||||
The rest of this guide assumes that <code class="filename">pugixml.hpp</code> is either in the current directory
|
||||
|
|
@ -131,40 +134,31 @@
|
|||
or include directory-relative path (i.e. <code class="computeroutput"><span class="preprocessor">#include</span>
|
||||
<span class="special"><</span><span class="identifier">xml</span><span class="special">/</span><span class="identifier">thirdparty</span><span class="special">/</span><span class="identifier">pugixml</span><span class="special">/</span><span class="identifier">src</span><span class="special">/</span><span class="identifier">pugixml</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>).
|
||||
</p>
|
||||
<div class="note"><table border="0" summary="Note">
|
||||
<tr>
|
||||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
|
||||
<th align="left">Note</th>
|
||||
</tr>
|
||||
<tr><td align="left" valign="top"><p>
|
||||
You don't need to compile <code class="filename">pugixpath.cpp</code> unless you use XPath.
|
||||
</p></td></tr>
|
||||
</table></div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h4 class="title">
|
||||
<a name="manual.install.building.embed"></a><a class="link" href="install.html#manual.install.building.embed" title="Building pugixml as a part of another static library/executable"> Building pugixml as
|
||||
a part of another static library/executable</a>
|
||||
</h4></div></div></div>
|
||||
<p>
|
||||
The easiest way to build pugixml is to compile two source files, <code class="filename">pugixml.cpp</code> and
|
||||
<code class="filename">pugixpath.cpp</code>, along with the existing library/executable. This process
|
||||
depends on the method of building your application; for example, if you're
|
||||
using Microsoft Visual Studio<sup>[<a name="trademarks" href="#ftn.trademarks" class="footnote">1</a>]</sup>, Apple Xcode, Code::Blocks or any other IDE,
|
||||
just add <code class="filename">pugixml.cpp</code> and <code class="filename">pugixpath.cpp</code> to one of your projects.
|
||||
The easiest way to build pugixml is to compile the source file, <code class="filename">pugixml.cpp</code>,
|
||||
along with the existing library/executable. This process depends on the
|
||||
method of building your application; for example, if you're using Microsoft
|
||||
Visual Studio<sup>[<a name="trademarks" href="#ftn.trademarks" class="footnote">1</a>]</sup>, Apple Xcode, Code::Blocks or any other IDE, just add <code class="filename">pugixml.cpp</code> to
|
||||
one of your projects.
|
||||
</p>
|
||||
<p>
|
||||
If you're using Microsoft Visual Studio and the project has precompiled
|
||||
headers turned on, you'll see the following error messages:
|
||||
</p>
|
||||
<pre class="programlisting">pugixpath.cpp(3477) : fatal error C1010: unexpected end of file while looking for precompiled header. Did you forget to add '#include "stdafx.h"' to your source?</pre>
|
||||
<pre class="programlisting">pugixml.cpp(3477) : fatal error C1010: unexpected end of file while looking for precompiled header. Did you forget to add '#include "stdafx.h"' to your source?</pre>
|
||||
<p>
|
||||
The correct way to resolve this is to disable precompiled headers for <code class="filename">pugixml.cpp</code> and
|
||||
<code class="filename">pugixpath.cpp</code>; you have to set "Create/Use Precompiled Header"
|
||||
option (Properties dialog -> C/C++ -> Precompiled Headers -> Create/Use
|
||||
Precompiled Header) to "Not Using Precompiled Headers". You'll
|
||||
have to do it for both <code class="filename">pugixml.cpp</code> and <code class="filename">pugixpath.cpp</code>, for all project configurations/platforms
|
||||
(you can select Configuration "All Configurations" and Platform
|
||||
"All Platforms" before editing the option):
|
||||
The correct way to resolve this is to disable precompiled headers for <code class="filename">pugixml.cpp</code>;
|
||||
you have to set "Create/Use Precompiled Header" option (Properties
|
||||
dialog -> C/C++ -> Precompiled Headers -> Create/Use Precompiled
|
||||
Header) to "Not Using Precompiled Headers". You'll have to do
|
||||
it for all project configurations/platforms (you can select Configuration
|
||||
"All Configurations" and Platform "All Platforms" before
|
||||
editing the option):
|
||||
</p>
|
||||
<div class="informaltable"><table class="table">
|
||||
<colgroup><col></colgroup>
|
||||
|
|
@ -251,7 +245,7 @@
|
|||
process does not differ from building any other library as DLL (adding
|
||||
-shared to compilation flags should suffice); if you're using MSVC-based
|
||||
toolchain, you'll have to explicitly mark exported symbols with a declspec
|
||||
attribute. You can do it by defining <code class="computeroutput"><span class="identifier">PUGIXML_API</span></code>
|
||||
attribute. You can do it by defining <a class="link" href="install.html#PUGIXML_API">PUGIXML_API</a>
|
||||
macro, i.e. via <code class="filename">pugiconfig.hpp</code>:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="preprocessor">#ifdef</span> <span class="identifier">_DLL</span>
|
||||
|
|
@ -260,6 +254,20 @@
|
|||
<span class="preprocessor">#define</span> <span class="identifier">PUGIXML_API</span> <span class="identifier">__declspec</span><span class="special">(</span><span class="identifier">dllimport</span><span class="special">)</span>
|
||||
<span class="preprocessor">#endif</span>
|
||||
</pre>
|
||||
<div class="caution"><table border="0" summary="Caution">
|
||||
<tr>
|
||||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../images/caution.png"></td>
|
||||
<th align="left">Caution</th>
|
||||
</tr>
|
||||
<tr><td align="left" valign="top"><p>
|
||||
If you're using STL-related functions, you should use the shared runtime
|
||||
library to ensure that a single heap is used for STL allocations in your
|
||||
application and in pugixml; in MSVC, this means selecting the 'Multithreaded
|
||||
DLL' or 'Multithreaded Debug DLL' to 'Runtime library' property (/MD
|
||||
or /MDd linker switch). You should also make sure that your runtime library
|
||||
choice is consistent between different projects.
|
||||
</p></td></tr>
|
||||
</table></div>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h4 class="title">
|
||||
|
|
@ -270,13 +278,13 @@
|
|||
pugixml uses several defines to control the compilation process. There
|
||||
are two ways to define them: either put the needed definitions to <code class="filename">pugiconfig.hpp</code> (it
|
||||
has some examples that are commented out) or provide them via compiler
|
||||
command-line. Define consistency is important, i.e. the definitions should
|
||||
match in all source files that include <code class="filename">pugixml.hpp</code> (including pugixml sources)
|
||||
throughout the application. Adding defines to <code class="filename">pugiconfig.hpp</code> lets you guarantee
|
||||
this, unless your macro definition is wrapped in preprocessor <code class="computeroutput"><span class="preprocessor">#if</span></code>/<code class="computeroutput"><span class="preprocessor">#ifdef</span></code>
|
||||
directive and this directive is not consistent. <code class="filename">pugiconfig.hpp</code> will never
|
||||
contain anything but comments, which means that when upgrading to new version,
|
||||
you can safely leave your modified version intact.
|
||||
command-line. Consistency is important: the definitions should match in
|
||||
all source files that include <code class="filename">pugixml.hpp</code> (including pugixml sources) throughout
|
||||
the application. Adding defines to <code class="filename">pugiconfig.hpp</code> lets you guarantee this,
|
||||
unless your macro definition is wrapped in preprocessor <code class="computeroutput"><span class="preprocessor">#if</span></code>/<code class="computeroutput"><span class="preprocessor">#ifdef</span></code> directive and this directive
|
||||
is not consistent. <code class="filename">pugiconfig.hpp</code> will never contain anything but comments,
|
||||
which means that when upgrading to a new version, you can safely leave
|
||||
your modified version intact.
|
||||
</p>
|
||||
<p>
|
||||
<a name="PUGIXML_WCHAR_MODE"></a><code class="literal">PUGIXML_WCHAR_MODE</code> define toggles
|
||||
|
|
@ -289,10 +297,9 @@
|
|||
</p>
|
||||
<p>
|
||||
<a name="PUGIXML_NO_XPATH"></a><code class="literal">PUGIXML_NO_XPATH</code> define disables XPath.
|
||||
Both XPath interfaces and XPath implementation are excluded from compilation;
|
||||
you can still compile the file <code class="filename">pugixpath.cpp</code> (it will result in an empty
|
||||
translation unit). This option is provided in case you do not need XPath
|
||||
functionality and need to save code space.
|
||||
Both XPath interfaces and XPath implementation are excluded from compilation.
|
||||
This option is provided in case you do not need XPath functionality and
|
||||
need to save code space.
|
||||
</p>
|
||||
<p>
|
||||
<a name="PUGIXML_NO_STL"></a><code class="literal">PUGIXML_NO_STL</code> define disables use of
|
||||
|
|
@ -301,33 +308,11 @@
|
|||
provided in case your target platform does not have a standard-compliant
|
||||
STL implementation.
|
||||
</p>
|
||||
<div class="note"><table border="0" summary="Note">
|
||||
<tr>
|
||||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
|
||||
<th align="left">Note</th>
|
||||
</tr>
|
||||
<tr><td align="left" valign="top"><p>
|
||||
As of version 0.9, STL is used in XPath implementation; therefore, XPath
|
||||
is also disabled if this macro is defined. This will change in version
|
||||
1.0.
|
||||
</p></td></tr>
|
||||
</table></div>
|
||||
<p>
|
||||
<a name="PUGIXML_NO_EXCEPTIONS"></a><code class="literal">PUGIXML_NO_EXCEPTIONS</code> define disables
|
||||
use of exceptions in pugixml. This option is provided in case your target
|
||||
platform does not have exception handling capabilities
|
||||
platform does not have exception handling capabilities.
|
||||
</p>
|
||||
<div class="note"><table border="0" summary="Note">
|
||||
<tr>
|
||||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
|
||||
<th align="left">Note</th>
|
||||
</tr>
|
||||
<tr><td align="left" valign="top"><p>
|
||||
As of version 0.9, exceptions are <span class="bold"><strong>only</strong></span>
|
||||
used in XPath implementation; therefore, XPath is also disabled if this
|
||||
macro is defined. This will change in version 1.0.
|
||||
</p></td></tr>
|
||||
</table></div>
|
||||
<p>
|
||||
<a name="PUGIXML_API"></a><code class="literal">PUGIXML_API</code>, <a name="PUGIXML_CLASS"></a><code class="literal">PUGIXML_CLASS</code>
|
||||
and <a name="PUGIXML_FUNCTION"></a><code class="literal">PUGIXML_FUNCTION</code> defines let you
|
||||
|
|
@ -414,8 +399,8 @@
|
|||
</div>
|
||||
<div class="footnotes">
|
||||
<br><hr width="100" align="left">
|
||||
<div class="footnote"><p><sup>[<a name="ftn.trademarks" href="#trademarks" class="para">1</a>] </sup>All trademarks used are properties
|
||||
of their respective owners.</p></div>
|
||||
<div class="footnote"><p><sup>[<a name="ftn.trademarks" href="#trademarks" class="para">1</a>] </sup>All trademarks used are properties of their respective
|
||||
owners.</p></div>
|
||||
</div>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
|
|
@ -427,7 +412,8 @@
|
|||
</tr></table>
|
||||
<hr>
|
||||
<table width="100%"><tr>
|
||||
<td>pugixml 0.9 manual |
|
||||
<td>
|
||||
<a href="http://pugixml.org/">pugixml 1.0</a> manual |
|
||||
<a href="../manual.html">Overview</a> |
|
||||
<b>Installation</b> |
|
||||
Document:
|
||||
|
|
|
|||
|
|
@ -4,14 +4,15 @@
|
|||
<title>Loading document</title>
|
||||
<link rel="stylesheet" href="../pugixml.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
|
||||
<link rel="home" href="../manual.html" title="pugixml 0.9">
|
||||
<link rel="up" href="../manual.html" title="pugixml 0.9">
|
||||
<link rel="home" href="../manual.html" title="pugixml 1.0">
|
||||
<link rel="up" href="../manual.html" title="pugixml 1.0">
|
||||
<link rel="prev" href="dom.html" title="Document object model">
|
||||
<link rel="next" href="access.html" title="Accessing document data">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table width="100%"><tr>
|
||||
<td>pugixml 0.9 manual |
|
||||
<td>
|
||||
<a href="http://pugixml.org/">pugixml 1.0</a> manual |
|
||||
<a href="../manual.html">Overview</a> |
|
||||
<a href="install.html">Installation</a> |
|
||||
Document:
|
||||
|
|
@ -44,11 +45,11 @@
|
|||
non-validating parser. This parser is not fully W3C conformant - it can load
|
||||
any valid XML document, but does not perform some well-formedness checks. While
|
||||
considerable effort is made to reject invalid XML documents, some validation
|
||||
is not performed because of performance reasons. Also some XML transformations
|
||||
(i.e. EOL handling or attribute value normalization) can impact parsing speed
|
||||
and thus can be disabled. However for vast majority of XML documents there
|
||||
is no performance difference between different parsing options. Parsing options
|
||||
also control whether certain XML nodes are parsed; see <a class="xref" href="loading.html#manual.loading.options" title="Parsing options"> Parsing options</a> for
|
||||
is not performed for performance reasons. Also some XML transformations (i.e.
|
||||
EOL handling or attribute value normalization) can impact parsing speed and
|
||||
thus can be disabled. However for vast majority of XML documents there is no
|
||||
performance difference between different parsing options. Parsing options also
|
||||
control whether certain XML nodes are parsed; see <a class="xref" href="loading.html#manual.loading.options" title="Parsing options"> Parsing options</a> for
|
||||
more information.
|
||||
</p>
|
||||
<p>
|
||||
|
|
@ -65,43 +66,36 @@
|
|||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="manual.loading.file"></a><a class="link" href="loading.html#manual.loading.file" title="Loading document from file"> Loading document from file</a>
|
||||
</h3></div></div></div>
|
||||
<a name="xml_document::load_file"></a><p>
|
||||
The most common source of XML data is files; pugixml provides a separate
|
||||
function for loading XML document from file:
|
||||
<a name="xml_document::load_file"></a><a name="xml_document::load_file_wide"></a><p>
|
||||
The most common source of XML data is files; pugixml provides dedicated functions
|
||||
for loading an XML document from file:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="identifier">xml_parse_result</span> <span class="identifier">xml_document</span><span class="special">::</span><span class="identifier">load_file</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">path</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">options</span> <span class="special">=</span> <span class="identifier">parse_default</span><span class="special">,</span> <span class="identifier">xml_encoding</span> <span class="identifier">encoding</span> <span class="special">=</span> <span class="identifier">encoding_auto</span><span class="special">);</span>
|
||||
<span class="identifier">xml_parse_result</span> <span class="identifier">xml_document</span><span class="special">::</span><span class="identifier">load_file</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">wchar_t</span><span class="special">*</span> <span class="identifier">path</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">options</span> <span class="special">=</span> <span class="identifier">parse_default</span><span class="special">,</span> <span class="identifier">xml_encoding</span> <span class="identifier">encoding</span> <span class="special">=</span> <span class="identifier">encoding_auto</span><span class="special">);</span>
|
||||
</pre>
|
||||
<p>
|
||||
This function accepts file path as its first argument, and also two optional
|
||||
arguments, which specify parsing options (see <a class="xref" href="loading.html#manual.loading.options" title="Parsing options"> Parsing options</a>) and
|
||||
input data encoding (see <a class="xref" href="loading.html#manual.loading.encoding" title="Encodings"> Encodings</a>). The path has the target
|
||||
These functions accept the file path as its first argument, and also two
|
||||
optional arguments, which specify parsing options (see <a class="xref" href="loading.html#manual.loading.options" title="Parsing options"> Parsing options</a>)
|
||||
and input data encoding (see <a class="xref" href="loading.html#manual.loading.encoding" title="Encodings"> Encodings</a>). The path has the target
|
||||
operating system format, so it can be a relative or absolute one, it should
|
||||
have the delimiters of target system, it should have the exact case if target
|
||||
file system is case-sensitive, etc. File path is passed to system file opening
|
||||
function as is.
|
||||
have the delimiters of the target system, it should have the exact case if
|
||||
the target file system is case-sensitive, etc.
|
||||
</p>
|
||||
<p>
|
||||
File path is passed to the system file opening function as is in case of
|
||||
the first function (which accepts <code class="computeroutput"><span class="keyword">const</span>
|
||||
<span class="keyword">char</span><span class="special">*</span> <span class="identifier">path</span></code>); the second function either uses
|
||||
a special file opening function if it is provided by the runtime library
|
||||
or converts the path to UTF-8 and uses the system file opening function.
|
||||
</p>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">load_file</span></code> destroys the existing
|
||||
document tree and then tries to load the new tree from the specified file.
|
||||
The result of the operation is returned in an <code class="computeroutput"><span class="identifier">xml_parse_result</span></code>
|
||||
object; this object contains the operation status, and the related information
|
||||
The result of the operation is returned in an <a class="link" href="loading.html#xml_parse_result">xml_parse_result</a>
|
||||
object; this object contains the operation status and the related information
|
||||
(i.e. last successfully parsed position in the input file, if parsing fails).
|
||||
See <a class="xref" href="loading.html#manual.loading.errors" title="Handling parsing errors"> Handling parsing errors</a> for error handling details.
|
||||
</p>
|
||||
<div class="note"><table border="0" summary="Note">
|
||||
<tr>
|
||||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
|
||||
<th align="left">Note</th>
|
||||
</tr>
|
||||
<tr><td align="left" valign="top"><p>
|
||||
As of version 0.9, there is no function for loading XML document from wide
|
||||
character path. Unfortunately, there is no portable way to do this; the
|
||||
version 1.0 will provide such function only for platforms with the corresponding
|
||||
functionality. You can use stream-loading functions as a workaround if
|
||||
your STL implementation can open file streams via <code class="computeroutput"><span class="keyword">wchar_t</span></code>
|
||||
paths.
|
||||
</p></td></tr>
|
||||
</table></div>
|
||||
<p>
|
||||
This is an example of loading XML document from file (<a href="../samples/load_file.cpp" target="_top">samples/load_file.cpp</a>):
|
||||
</p>
|
||||
|
|
@ -122,7 +116,7 @@
|
|||
<a name="manual.loading.memory"></a><a class="link" href="loading.html#manual.loading.memory" title="Loading document from memory"> Loading document from memory</a>
|
||||
</h3></div></div></div>
|
||||
<a name="xml_document::load_buffer"></a><a name="xml_document::load_buffer_inplace"></a><a name="xml_document::load_buffer_inplace_own"></a><p>
|
||||
Sometimes XML data should be loaded from some other source than file, i.e.
|
||||
Sometimes XML data should be loaded from some other source than a file, i.e.
|
||||
HTTP URL; also you may want to load XML data from file using non-standard
|
||||
functions, i.e. to use your virtual file system facilities or to load XML
|
||||
from gzip-compressed files. All these scenarios require loading document
|
||||
|
|
@ -177,12 +171,12 @@
|
|||
</pre>
|
||||
<p>
|
||||
It is equivalent to calling <code class="computeroutput"><span class="identifier">load_buffer</span></code>
|
||||
with <code class="computeroutput"><span class="identifier">size</span> <span class="special">=</span>
|
||||
<span class="identifier">strlen</span><span class="special">(</span><span class="identifier">contents</span><span class="special">)</span></code>.
|
||||
This function assumes native encoding for input data, so it does not do any
|
||||
encoding conversion. In general, this function is fine for loading small
|
||||
documents from string literals, but has more overhead and less functionality
|
||||
than buffer loading functions.
|
||||
with <code class="computeroutput"><span class="identifier">size</span></code> being either <code class="computeroutput"><span class="identifier">strlen</span><span class="special">(</span><span class="identifier">contents</span><span class="special">)</span></code>
|
||||
or <code class="computeroutput"><span class="identifier">wcslen</span><span class="special">(</span><span class="identifier">contents</span><span class="special">)</span> <span class="special">*</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="keyword">wchar_t</span><span class="special">)</span></code>,
|
||||
depending on the character type. This function assumes native encoding for
|
||||
input data, so it does not do any encoding conversion. In general, this function
|
||||
is fine for loading small documents from string literals, but has more overhead
|
||||
and less functionality than the buffer loading functions.
|
||||
</p>
|
||||
<p>
|
||||
This is an example of loading XML document from memory using different functions
|
||||
|
|
@ -246,7 +240,7 @@
|
|||
<a name="manual.loading.stream"></a><a class="link" href="loading.html#manual.loading.stream" title="Loading document from C++ IOstreams"> Loading document from C++ IOstreams</a>
|
||||
</h3></div></div></div>
|
||||
<a name="xml_document::load_stream"></a><p>
|
||||
For additional interoperability pugixml provides functions for loading document
|
||||
To enhance interoperability, pugixml provides functions for loading document
|
||||
from any object which implements C++ <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">istream</span></code>
|
||||
interface. This allows you to load documents from any standard C++ stream
|
||||
(i.e. file stream) or any third-party compliant implementation (i.e. Boost
|
||||
|
|
@ -267,10 +261,10 @@
|
|||
<p>
|
||||
<code class="computeroutput"><span class="identifier">load</span></code> with <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wstream</span></code>
|
||||
argument treats the stream contents as a wide character stream (encoding
|
||||
is always <code class="computeroutput"><span class="identifier">encoding_wchar</span></code>).
|
||||
Because of this, using <code class="computeroutput"><span class="identifier">load</span></code>
|
||||
with wide character streams requires careful (usually platform-specific)
|
||||
stream setup (i.e. using the <code class="computeroutput"><span class="identifier">imbue</span></code>
|
||||
is always <a class="link" href="loading.html#encoding_wchar">encoding_wchar</a>). Because
|
||||
of this, using <code class="computeroutput"><span class="identifier">load</span></code> with
|
||||
wide character streams requires careful (usually platform-specific) stream
|
||||
setup (i.e. using the <code class="computeroutput"><span class="identifier">imbue</span></code>
|
||||
function). Generally use of wide streams is discouraged, however it provides
|
||||
you the ability to load documents from non-Unicode encodings, i.e. you can
|
||||
load Shift-JIS encoded data if you set the correct locale.
|
||||
|
|
@ -330,7 +324,7 @@
|
|||
</li>
|
||||
<li class="listitem">
|
||||
<a name="status_io_error"></a><code class="literal">status_io_error</code> is returned by <code class="computeroutput"><span class="identifier">load_file</span></code> function and by <code class="computeroutput"><span class="identifier">load</span></code> functions with <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">istream</span></code>/<code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wstream</span></code> arguments; it means that some
|
||||
I/O error has occured during reading the file/stream.
|
||||
I/O error has occurred during reading the file/stream.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<a name="status_out_of_memory"></a><code class="literal">status_out_of_memory</code> means that
|
||||
|
|
@ -407,11 +401,11 @@
|
|||
member, which contains the offset of last successfully parsed character if
|
||||
parsing failed because of an error in source data; otherwise <code class="computeroutput"><span class="identifier">offset</span></code> is 0. For parsing efficiency reasons,
|
||||
pugixml does not track the current line during parsing; this offset is in
|
||||
units of <code class="computeroutput"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">char_t</span></code> (bytes for character mode, wide
|
||||
characters for wide character mode). Many text editors support 'Go To Position'
|
||||
feature - you can use it to locate the exact error position. Alternatively,
|
||||
if you're loading the document from memory, you can display the error chunk
|
||||
along with the error description (see the example code below).
|
||||
units of <a class="link" href="dom.html#char_t">pugi::char_t</a> (bytes for character
|
||||
mode, wide characters for wide character mode). Many text editors support
|
||||
'Go To Position' feature - you can use it to locate the exact error position.
|
||||
Alternatively, if you're loading the document from memory, you can display
|
||||
the error chunk along with the error description (see the example code below).
|
||||
</p>
|
||||
<div class="caution"><table border="0" summary="Caution">
|
||||
<tr>
|
||||
|
|
@ -490,9 +484,15 @@
|
|||
<li class="listitem">
|
||||
<a name="parse_declaration"></a><code class="literal">parse_declaration</code> determines if XML
|
||||
document declaration (node with type <a class="link" href="dom.html#node_declaration">node_declaration</a>)
|
||||
are to be put in DOM tree. If this flag is off, it is not put in the
|
||||
tree, but is still parsed and checked for correctness. This flag is
|
||||
<span class="bold"><strong>off</strong></span> by default. <br><br>
|
||||
is to be put in DOM tree. If this flag is off, it is not put in the tree,
|
||||
but is still parsed and checked for correctness. This flag is <span class="bold"><strong>off</strong></span> by default. <br><br>
|
||||
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<a name="parse_doctype"></a><code class="literal">parse_doctype</code> determines if XML document
|
||||
type declaration (node with type <a class="link" href="dom.html#node_doctype">node_doctype</a>)
|
||||
is to be put in DOM tree. If this flag is off, it is not put in the tree,
|
||||
but is still parsed and checked for correctness. This flag is <span class="bold"><strong>off</strong></span> by default. <br><br>
|
||||
|
||||
</li>
|
||||
<li class="listitem">
|
||||
|
|
@ -525,13 +525,13 @@
|
|||
the cost of allocating and storing such nodes (both memory and speed-wise)
|
||||
can be significant. For example, after parsing XML string <code class="computeroutput"><span class="special"><</span><span class="identifier">node</span><span class="special">></span> <span class="special"><</span><span class="identifier">a</span><span class="special">/></span> <span class="special"></</span><span class="identifier">node</span><span class="special">></span></code>, <code class="computeroutput"><span class="special"><</span><span class="identifier">node</span><span class="special">></span></code>
|
||||
element will have three children when <code class="computeroutput"><span class="identifier">parse_ws_pcdata</span></code>
|
||||
is set (child with type <code class="computeroutput"><span class="identifier">node_pcdata</span></code>
|
||||
is set (child with type <a class="link" href="dom.html#node_pcdata">node_pcdata</a>
|
||||
and value <code class="computeroutput"><span class="string">" "</span></code>,
|
||||
child with type <code class="computeroutput"><span class="identifier">node_element</span></code>
|
||||
and name <code class="computeroutput"><span class="string">"a"</span></code>, and
|
||||
another child with type <code class="computeroutput"><span class="identifier">node_pcdata</span></code>
|
||||
and value <code class="computeroutput"><span class="string">" "</span></code>),
|
||||
and only one child when <code class="computeroutput"><span class="identifier">parse_ws_pcdata</span></code>
|
||||
child with type <a class="link" href="dom.html#node_element">node_element</a> and
|
||||
name <code class="computeroutput"><span class="string">"a"</span></code>, and another
|
||||
child with type <a class="link" href="dom.html#node_pcdata">node_pcdata</a> and value
|
||||
<code class="computeroutput"><span class="string">" "</span></code>), and only
|
||||
one child when <code class="computeroutput"><span class="identifier">parse_ws_pcdata</span></code>
|
||||
is not set. This flag is <span class="bold"><strong>off</strong></span> by default.
|
||||
</li>
|
||||
</ul></div>
|
||||
|
|
@ -551,7 +551,7 @@
|
|||
that as pugixml does not handle DTD, the only allowed entities are predefined
|
||||
ones). If character/entity reference can not be expanded, it is left
|
||||
as is, so you can do additional processing later. Reference expansion
|
||||
is performed in attribute values and PCDATA content. This flag is <span class="bold"><strong>on</strong></span> by default. <br><br>
|
||||
is performed on attribute values and PCDATA content. This flag is <span class="bold"><strong>on</strong></span> by default. <br><br>
|
||||
|
||||
</li>
|
||||
<li class="listitem">
|
||||
|
|
@ -569,9 +569,9 @@
|
|||
if attribute value normalization should be performed for all attributes.
|
||||
This means, that whitespace characters (new line, tab and space) are
|
||||
replaced with space (<code class="computeroutput"><span class="char">' '</span></code>).
|
||||
New line characters are always treated as if <code class="computeroutput"><span class="identifier">parse_eol</span></code>
|
||||
New line characters are always treated as if <a class="link" href="loading.html#parse_eol">parse_eol</a>
|
||||
is set, i.e. <code class="computeroutput"><span class="special">\</span><span class="identifier">r</span><span class="special">\</span><span class="identifier">n</span></code>
|
||||
is converted to single space. This flag is <span class="bold"><strong>on</strong></span>
|
||||
is converted to a single space. This flag is <span class="bold"><strong>on</strong></span>
|
||||
by default. <br><br>
|
||||
|
||||
</li>
|
||||
|
|
@ -579,10 +579,10 @@
|
|||
<a name="parse_wnorm_attribute"></a><code class="literal">parse_wnorm_attribute</code> determines
|
||||
if extended attribute value normalization should be performed for all
|
||||
attributes. This means, that after attribute values are normalized as
|
||||
if <code class="computeroutput"><span class="identifier">parse_wconv_attribute</span></code>
|
||||
if <a class="link" href="loading.html#parse_wconv_attribute">parse_wconv_attribute</a>
|
||||
was set, leading and trailing space characters are removed, and all sequences
|
||||
of space characters are replaced by a single space character. The value
|
||||
of <code class="computeroutput"><span class="identifier">parse_wconv_attribute</span></code>
|
||||
of <a class="link" href="loading.html#parse_wconv_attribute">parse_wconv_attribute</a>
|
||||
has no effect if this flag is on. This flag is <span class="bold"><strong>off</strong></span>
|
||||
by default.
|
||||
</li>
|
||||
|
|
@ -595,24 +595,25 @@
|
|||
<tr><td align="left" valign="top"><p>
|
||||
<code class="computeroutput"><span class="identifier">parse_wconv_attribute</span></code> option
|
||||
performs transformations that are required by W3C specification for attributes
|
||||
that are declared as <code class="literal">CDATA</code>; <code class="computeroutput"><span class="identifier">parse_wnorm_attribute</span></code>
|
||||
that are declared as <code class="literal">CDATA</code>; <a class="link" href="loading.html#parse_wnorm_attribute">parse_wnorm_attribute</a>
|
||||
performs transformations required for <code class="literal">NMTOKENS</code> attributes.
|
||||
In the absence of document type declaration all attributes behave as if
|
||||
they are declared as <code class="literal">CDATA</code>, thus <code class="computeroutput"><span class="identifier">parse_wconv_attribute</span></code>
|
||||
In the absence of document type declaration all attributes should behave
|
||||
as if they are declared as <code class="literal">CDATA</code>, thus <a class="link" href="loading.html#parse_wconv_attribute">parse_wconv_attribute</a>
|
||||
is the default option.
|
||||
</p></td></tr>
|
||||
</table></div>
|
||||
<p>
|
||||
Additionally there are two predefined option masks:
|
||||
Additionally there are three predefined option masks:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||||
<li class="listitem">
|
||||
<a name="parse_minimal"></a><code class="literal">parse_minimal</code> has all options turned
|
||||
off. This option mask means that pugixml does not add declaration nodes,
|
||||
PI nodes, CDATA sections and comments to the resulting tree and does
|
||||
not perform any conversion for input data, so theoretically it is the
|
||||
fastest mode. However, as discussed above, in practice <code class="computeroutput"><span class="identifier">parse_default</span></code> is usually equally fast.
|
||||
<br><br>
|
||||
document type declaration nodes, PI nodes, CDATA sections and comments
|
||||
to the resulting tree and does not perform any conversion for input data,
|
||||
so theoretically it is the fastest mode. However, as mentioned above,
|
||||
in practice <a class="link" href="loading.html#parse_default">parse_default</a> is usually
|
||||
equally fast. <br><br>
|
||||
|
||||
</li>
|
||||
<li class="listitem">
|
||||
|
|
@ -622,7 +623,18 @@
|
|||
entity reference expansion, replacing whitespace characters with spaces
|
||||
in attribute values and performing EOL handling. Note, that PCDATA sections
|
||||
consisting only of whitespace characters are not parsed (by default)
|
||||
for performance reasons.
|
||||
for performance reasons. <br><br>
|
||||
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<a name="parse_full"></a><code class="literal">parse_full</code> is the set of flags which adds
|
||||
nodes of all types to the resulting tree and performs default conversions
|
||||
for input data. It includes parsing CDATA sections, comments, PI nodes,
|
||||
document declaration node and document type declaration node, performing
|
||||
character and entity reference expansion, replacing whitespace characters
|
||||
with spaces in attribute values and performing EOL handling. Note, that
|
||||
PCDATA sections consisting only of whitespace characters are not parsed
|
||||
in this mode.
|
||||
</li>
|
||||
</ul></div>
|
||||
<p>
|
||||
|
|
@ -705,36 +717,36 @@
|
|||
</li>
|
||||
<li class="listitem">
|
||||
<a name="encoding_utf8"></a><code class="literal">encoding_utf8</code> corresponds to UTF-8 encoding
|
||||
as defined in Unicode standard; UTF-8 sequences with length equal to
|
||||
5 or 6 are not standard and are rejected.
|
||||
as defined in the Unicode standard; UTF-8 sequences with length equal
|
||||
to 5 or 6 are not standard and are rejected.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<a name="encoding_utf16_le"></a><code class="literal">encoding_utf16_le</code> corresponds to
|
||||
little-endian UTF-16 encoding as defined in Unicode standard; surrogate
|
||||
little-endian UTF-16 encoding as defined in the Unicode standard; surrogate
|
||||
pairs are supported.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<a name="encoding_utf16_be"></a><code class="literal">encoding_utf16_be</code> corresponds to
|
||||
big-endian UTF-16 encoding as defined in Unicode standard; surrogate
|
||||
big-endian UTF-16 encoding as defined in the Unicode standard; surrogate
|
||||
pairs are supported.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<a name="encoding_utf16"></a><code class="literal">encoding_utf16</code> corresponds to UTF-16
|
||||
encoding as defined in Unicode standard; the endianness is assumed to
|
||||
be that of target platform.
|
||||
encoding as defined in the Unicode standard; the endianness is assumed
|
||||
to be that of the target platform.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<a name="encoding_utf32_le"></a><code class="literal">encoding_utf32_le</code> corresponds to
|
||||
little-endian UTF-32 encoding as defined in Unicode standard.
|
||||
little-endian UTF-32 encoding as defined in the Unicode standard.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<a name="encoding_utf32_be"></a><code class="literal">encoding_utf32_be</code> corresponds to
|
||||
big-endian UTF-32 encoding as defined in Unicode standard.
|
||||
big-endian UTF-32 encoding as defined in the Unicode standard.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<a name="encoding_utf32"></a><code class="literal">encoding_utf32</code> corresponds to UTF-32
|
||||
encoding as defined in Unicode standard; the endianness is assumed to
|
||||
be that of target platform.
|
||||
encoding as defined in the Unicode standard; the endianness is assumed
|
||||
to be that of the target platform.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<a name="encoding_wchar"></a><code class="literal">encoding_wchar</code> corresponds to the encoding
|
||||
|
|
@ -823,7 +835,8 @@
|
|||
</tr></table>
|
||||
<hr>
|
||||
<table width="100%"><tr>
|
||||
<td>pugixml 0.9 manual |
|
||||
<td>
|
||||
<a href="http://pugixml.org/">pugixml 1.0</a> manual |
|
||||
<a href="../manual.html">Overview</a> |
|
||||
<a href="install.html">Installation</a> |
|
||||
Document:
|
||||
|
|
|
|||
|
|
@ -4,14 +4,15 @@
|
|||
<title>Modifying document data</title>
|
||||
<link rel="stylesheet" href="../pugixml.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
|
||||
<link rel="home" href="../manual.html" title="pugixml 0.9">
|
||||
<link rel="up" href="../manual.html" title="pugixml 0.9">
|
||||
<link rel="home" href="../manual.html" title="pugixml 1.0">
|
||||
<link rel="up" href="../manual.html" title="pugixml 1.0">
|
||||
<link rel="prev" href="access.html" title="Accessing document data">
|
||||
<link rel="next" href="saving.html" title="Saving document">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table width="100%"><tr>
|
||||
<td>pugixml 0.9 manual |
|
||||
<td>
|
||||
<a href="http://pugixml.org/">pugixml 1.0</a> manual |
|
||||
<a href="../manual.html">Overview</a> |
|
||||
<a href="install.html">Installation</a> |
|
||||
Document:
|
||||
|
|
@ -62,12 +63,13 @@
|
|||
</h3></div></div></div>
|
||||
<a name="xml_node::set_name"></a><a name="xml_node::set_value"></a><p>
|
||||
As discussed before, nodes can have name and value, both of which are strings.
|
||||
Depending on node type, name or value may be absent. <code class="computeroutput"><span class="identifier">node_document</span></code>
|
||||
nodes do not have name or value, <code class="computeroutput"><span class="identifier">node_element</span></code>
|
||||
and <code class="computeroutput"><span class="identifier">node_declaration</span></code> nodes
|
||||
always have a name but never have a value, <code class="computeroutput"><span class="identifier">node_pcdata</span></code>,
|
||||
<code class="computeroutput"><span class="identifier">node_cdata</span></code> and <code class="computeroutput"><span class="identifier">node_comment</span></code> nodes never have a name but
|
||||
always have a value (it may be empty though), <code class="computeroutput"><span class="identifier">node_pi</span></code>
|
||||
Depending on node type, name or value may be absent. <a class="link" href="dom.html#node_document">node_document</a>
|
||||
nodes do not have a name or value, <a class="link" href="dom.html#node_element">node_element</a>
|
||||
and <a class="link" href="dom.html#node_declaration">node_declaration</a> nodes always
|
||||
have a name but never have a value, <a class="link" href="dom.html#node_pcdata">node_pcdata</a>,
|
||||
<a class="link" href="dom.html#node_cdata">node_cdata</a>, <a class="link" href="dom.html#node_comment">node_comment</a>
|
||||
and <a class="link" href="dom.html#node_doctype">node_doctype</a> nodes never have a name
|
||||
but always have a value (it may be empty though), <a class="link" href="dom.html#node_pi">node_pi</a>
|
||||
nodes always have a name and a value (again, value may be empty). In order
|
||||
to set node's name or value, you can use the following functions:
|
||||
</p>
|
||||
|
|
@ -78,16 +80,15 @@
|
|||
Both functions try to set the name/value to the specified string, and return
|
||||
the operation result. The operation fails if the node can not have name or
|
||||
value (for instance, when trying to call <code class="computeroutput"><span class="identifier">set_name</span></code>
|
||||
on a <code class="computeroutput"><span class="identifier">node_pcdata</span></code> node), if
|
||||
the node handle is null, or if there is insufficient memory to handle the
|
||||
request. The provided string is copied into document managed memory and can
|
||||
be destroyed after the function returns (for example, you can safely pass
|
||||
stack-allocated buffers to these functions). The name/value content is not
|
||||
verified, so take care to use only valid XML names, or the document may become
|
||||
malformed.
|
||||
on a <a class="link" href="dom.html#node_pcdata">node_pcdata</a> node), if the node handle
|
||||
is null, or if there is insufficient memory to handle the request. The provided
|
||||
string is copied into document managed memory and can be destroyed after
|
||||
the function returns (for example, you can safely pass stack-allocated buffers
|
||||
to these functions). The name/value content is not verified, so take care
|
||||
to use only valid XML names, or the document may become malformed.
|
||||
</p>
|
||||
<p>
|
||||
There is no equivalent of <code class="computeroutput"><span class="identifier">child_value</span></code>
|
||||
There is no equivalent of <a class="link" href="access.html#xml_node::child_value">child_value</a>
|
||||
function for modifying text children of the node.
|
||||
</p>
|
||||
<p>
|
||||
|
|
@ -185,7 +186,7 @@
|
|||
These operators simply call the right <code class="computeroutput"><span class="identifier">set_value</span></code>
|
||||
function and return the attribute they're called on; the return value of
|
||||
<code class="computeroutput"><span class="identifier">set_value</span></code> is ignored, so
|
||||
errors are not detected.
|
||||
errors are ignored.
|
||||
</p>
|
||||
<p>
|
||||
This is an example of setting attribute name and value (<a href="../samples/modify_base.cpp" target="_top">samples/modify_base.cpp</a>):
|
||||
|
|
@ -214,36 +215,48 @@
|
|||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="manual.modify.add"></a><a class="link" href="modify.html#manual.modify.add" title="Adding nodes/attributes"> Adding nodes/attributes</a>
|
||||
</h3></div></div></div>
|
||||
<a name="xml_node::append_attribute"></a><a name="xml_node::insert_attribute_after"></a><a name="xml_node::insert_attribute_before"></a><a name="xml_node::append_child"></a><a name="xml_node::insert_child_after"></a><a name="xml_node::insert_child_before"></a><p>
|
||||
Nodes and attributes do not exist outside of document tree, so you can't
|
||||
create them without adding them to some document. A node or attribute can
|
||||
be created at the end of node/attribute list or before/after some other node:
|
||||
<a name="xml_node::prepend_attribute"></a><a name="xml_node::append_attribute"></a><a name="xml_node::insert_attribute_after"></a><a name="xml_node::insert_attribute_before"></a><a name="xml_node::prepend_child"></a><a name="xml_node::append_child"></a><a name="xml_node::insert_child_after"></a><a name="xml_node::insert_child_before"></a><p>
|
||||
Nodes and attributes do not exist without a document tree, so you can't create
|
||||
them without adding them to some document. A node or attribute can be created
|
||||
at the end of node/attribute list or before/after some other node:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="identifier">xml_attribute</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">append_attribute</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">name</span><span class="special">);</span>
|
||||
<span class="identifier">xml_attribute</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">prepend_attribute</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">name</span><span class="special">);</span>
|
||||
<span class="identifier">xml_attribute</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">insert_attribute_after</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">attr</span><span class="special">);</span>
|
||||
<span class="identifier">xml_attribute</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">insert_attribute_before</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">attr</span><span class="special">);</span>
|
||||
|
||||
<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">append_child</span><span class="special">(</span><span class="identifier">xml_node_type</span> <span class="identifier">type</span> <span class="special">=</span> <span class="identifier">node_element</span><span class="special">);</span>
|
||||
<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">prepend_child</span><span class="special">(</span><span class="identifier">xml_node_type</span> <span class="identifier">type</span> <span class="special">=</span> <span class="identifier">node_element</span><span class="special">);</span>
|
||||
<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">insert_child_after</span><span class="special">(</span><span class="identifier">xml_node_type</span> <span class="identifier">type</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">node</span><span class="special">);</span>
|
||||
<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">insert_child_before</span><span class="special">(</span><span class="identifier">xml_node_type</span> <span class="identifier">type</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">node</span><span class="special">);</span>
|
||||
|
||||
<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">append_child</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">name</span><span class="special">);</span>
|
||||
<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">prepend_child</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">name</span><span class="special">);</span>
|
||||
<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">insert_child_after</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">node</span><span class="special">);</span>
|
||||
<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">insert_child_before</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">node</span><span class="special">);</span>
|
||||
</pre>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">append_attribute</span></code> and <code class="computeroutput"><span class="identifier">append_child</span></code> create a new node/attribute
|
||||
at the end of the corresponding list of the node the method is called on;
|
||||
<code class="computeroutput"><span class="identifier">insert_attribute_after</span></code>,
|
||||
<code class="computeroutput"><span class="identifier">prepend_attribute</span></code> and <code class="computeroutput"><span class="identifier">prepend_child</span></code> create a new node/attribute
|
||||
at the beginning of the list; <code class="computeroutput"><span class="identifier">insert_attribute_after</span></code>,
|
||||
<code class="computeroutput"><span class="identifier">insert_attribute_before</span></code>,
|
||||
<code class="computeroutput"><span class="identifier">insert_child_after</span></code> and <code class="computeroutput"><span class="identifier">insert_attribute_before</span></code> add the node/attribute
|
||||
before or after specified node/attribute.
|
||||
before or after the specified node/attribute.
|
||||
</p>
|
||||
<p>
|
||||
Attribute functions create an attribute with the specified name; you can
|
||||
specify the empty name and change the name later if you want to. Node functions
|
||||
create the node with the specified type; since node type can't be changed,
|
||||
you have to know the desired type beforehand. Also note that not all types
|
||||
can be added as children; see below for clarification.
|
||||
with the <code class="computeroutput"><span class="identifier">type</span></code> argument create
|
||||
the node with the specified type; since node type can't be changed, you have
|
||||
to know the desired type beforehand. Also note that not all types can be
|
||||
added as children; see below for clarification. Node functions with the
|
||||
<code class="computeroutput"><span class="identifier">name</span></code> argument create the
|
||||
element node (<a class="link" href="dom.html#node_element">node_element</a>) with the
|
||||
specified name.
|
||||
</p>
|
||||
<p>
|
||||
All functions return the handle to newly created object on success, and null
|
||||
All functions return the handle to the created object on success, and null
|
||||
handle on failure. There are several reasons for failure:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||||
|
|
@ -251,32 +264,30 @@
|
|||
Adding fails if the target node is null;
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Only <code class="computeroutput"><span class="identifier">node_element</span></code> nodes
|
||||
can contain attributes, so attribute adding fails if node is not an element;
|
||||
Only <a class="link" href="dom.html#node_element">node_element</a> nodes can contain
|
||||
attributes, so attribute adding fails if node is not an element;
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Only <code class="computeroutput"><span class="identifier">node_document</span></code> and
|
||||
<code class="computeroutput"><span class="identifier">node_element</span></code> nodes can
|
||||
contain children, so child node adding fails if target node is not an
|
||||
element or a document;
|
||||
Only <a class="link" href="dom.html#node_document">node_document</a> and <a class="link" href="dom.html#node_element">node_element</a>
|
||||
nodes can contain children, so child node adding fails if the target
|
||||
node is not an element or a document;
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">node_document</span></code> and <code class="computeroutput"><span class="identifier">node_null</span></code> nodes can not be inserted
|
||||
as children, so passing <code class="computeroutput"><span class="identifier">node_document</span></code>
|
||||
or <code class="computeroutput"><span class="identifier">node_null</span></code> value as
|
||||
type results in operation failure;
|
||||
<a class="link" href="dom.html#node_document">node_document</a> and <a class="link" href="dom.html#node_null">node_null</a>
|
||||
nodes can not be inserted as children, so passing <a class="link" href="dom.html#node_document">node_document</a>
|
||||
or <a class="link" href="dom.html#node_null">node_null</a> value as <code class="computeroutput"><span class="identifier">type</span></code> results in operation failure;
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<code class="computeroutput"><span class="identifier">node_declaration</span></code> nodes
|
||||
can only be added as children of the document node; attempt to insert
|
||||
declaration node as a child of an element node fails;
|
||||
<a class="link" href="dom.html#node_declaration">node_declaration</a> nodes can only
|
||||
be added as children of the document node; attempt to insert declaration
|
||||
node as a child of an element node fails;
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Adding node/attribute results in memory allocation, which may fail;
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Insertion functions fail if the specified node or attribute is not in
|
||||
the target node's children/attribute list.
|
||||
Insertion functions fail if the specified node or attribute is null or
|
||||
is not in the target node's children/attribute list.
|
||||
</li>
|
||||
</ul></div>
|
||||
<p>
|
||||
|
|
@ -302,17 +313,14 @@
|
|||
|
||||
</p>
|
||||
<pre class="programlisting"><span class="comment">// add node with some name
|
||||
</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">node</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">append_child</span><span class="special">();</span>
|
||||
<span class="identifier">node</span><span class="special">.</span><span class="identifier">set_name</span><span class="special">(</span><span class="string">"node"</span><span class="special">);</span>
|
||||
</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">node</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">append_child</span><span class="special">(</span><span class="string">"node"</span><span class="special">);</span>
|
||||
|
||||
<span class="comment">// add description node with text child
|
||||
</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">descr</span> <span class="special">=</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">append_child</span><span class="special">();</span>
|
||||
<span class="identifier">descr</span><span class="special">.</span><span class="identifier">set_name</span><span class="special">(</span><span class="string">"description"</span><span class="special">);</span>
|
||||
</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">descr</span> <span class="special">=</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">append_child</span><span class="special">(</span><span class="string">"description"</span><span class="special">);</span>
|
||||
<span class="identifier">descr</span><span class="special">.</span><span class="identifier">append_child</span><span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">node_pcdata</span><span class="special">).</span><span class="identifier">set_value</span><span class="special">(</span><span class="string">"Simple node"</span><span class="special">);</span>
|
||||
|
||||
<span class="comment">// add param node before the description
|
||||
</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">param</span> <span class="special">=</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">insert_child_before</span><span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">node_element</span><span class="special">,</span> <span class="identifier">descr</span><span class="special">);</span>
|
||||
<span class="identifier">param</span><span class="special">.</span><span class="identifier">set_name</span><span class="special">(</span><span class="string">"param"</span><span class="special">);</span>
|
||||
</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">param</span> <span class="special">=</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">insert_child_before</span><span class="special">(</span><span class="string">"param"</span><span class="special">,</span> <span class="identifier">descr</span><span class="special">);</span>
|
||||
|
||||
<span class="comment">// add attributes to param node
|
||||
</span><span class="identifier">param</span><span class="special">.</span><span class="identifier">append_attribute</span><span class="special">(</span><span class="string">"name"</span><span class="special">)</span> <span class="special">=</span> <span class="string">"version"</span><span class="special">;</span>
|
||||
|
|
@ -400,29 +408,32 @@
|
|||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="manual.modify.clone"></a><a class="link" href="modify.html#manual.modify.clone" title="Cloning nodes/attributes"> Cloning nodes/attributes</a>
|
||||
</h3></div></div></div>
|
||||
<a name="xml_node::append_copy"></a><a name="xml_node::insert_copy_after"></a><a name="xml_node::insert_copy_before"></a><p>
|
||||
<a name="xml_node::prepend_copy"></a><a name="xml_node::append_copy"></a><a name="xml_node::insert_copy_after"></a><a name="xml_node::insert_copy_before"></a><p>
|
||||
With the help of previously described functions, it is possible to create
|
||||
trees with any contents and structure, including cloning the existing data.
|
||||
However since this is an often needed operation, pugixml provides built-in
|
||||
node/attribute cloning facilities. Since nodes and attributes do not exist
|
||||
outside of document tree, you can't create a standalone copy - you have to
|
||||
without a document tree, you can't create a standalone copy - you have to
|
||||
immediately insert it somewhere in the tree. For this, you can use one of
|
||||
the following functions:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="identifier">xml_attribute</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">append_copy</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">proto</span><span class="special">);</span>
|
||||
<span class="identifier">xml_attribute</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">prepend_copy</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">proto</span><span class="special">);</span>
|
||||
<span class="identifier">xml_attribute</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">insert_copy_after</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">proto</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">attr</span><span class="special">);</span>
|
||||
<span class="identifier">xml_attribute</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">insert_copy_before</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">proto</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">attr</span><span class="special">);</span>
|
||||
|
||||
<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">append_copy</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">proto</span><span class="special">);</span>
|
||||
<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">prepend_copy</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">proto</span><span class="special">);</span>
|
||||
<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">insert_copy_after</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">proto</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">node</span><span class="special">);</span>
|
||||
<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">insert_copy_before</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">proto</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">node</span><span class="special">);</span>
|
||||
</pre>
|
||||
<p>
|
||||
These functions mirror the structure of <code class="computeroutput"><span class="identifier">append_child</span></code>,
|
||||
<code class="computeroutput"><span class="identifier">insert_child_before</span></code> and related
|
||||
functions - they take the handle to the prototype object, which is to be
|
||||
cloned, insert a new attribute/node at the appropriate place, and then copy
|
||||
the attribute data or the whole node subtree to the new object. The functions
|
||||
return the handle to the resulting duplicate object, or null handle on failure.
|
||||
<code class="computeroutput"><span class="identifier">prepend_child</span></code>, <code class="computeroutput"><span class="identifier">insert_child_before</span></code> and related functions
|
||||
- they take the handle to the prototype object, which is to be cloned, insert
|
||||
a new attribute/node at the appropriate place, and then copy the attribute
|
||||
data or the whole node subtree to the new object. The functions return the
|
||||
handle to the resulting duplicate object, or null handle on failure.
|
||||
</p>
|
||||
<p>
|
||||
The attribute is copied along with the name and value; the node is copied
|
||||
|
|
@ -445,7 +456,7 @@
|
|||
<li class="listitem">
|
||||
Node cloning starts with insertion of the node of the same type as that
|
||||
of the prototype; for this reason, cloning functions can not be directly
|
||||
used to clone entire documents, since <code class="computeroutput"><span class="identifier">node_document</span></code>
|
||||
used to clone entire documents, since <a class="link" href="dom.html#node_document">node_document</a>
|
||||
is not a valid insertion type. The example below provides a workaround.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
|
|
@ -524,7 +535,8 @@
|
|||
</tr></table>
|
||||
<hr>
|
||||
<table width="100%"><tr>
|
||||
<td>pugixml 0.9 manual |
|
||||
<td>
|
||||
<a href="http://pugixml.org/">pugixml 1.0</a> manual |
|
||||
<a href="../manual.html">Overview</a> |
|
||||
<a href="install.html">Installation</a> |
|
||||
Document:
|
||||
|
|
|
|||
|
|
@ -4,14 +4,15 @@
|
|||
<title>Saving document</title>
|
||||
<link rel="stylesheet" href="../pugixml.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
|
||||
<link rel="home" href="../manual.html" title="pugixml 0.9">
|
||||
<link rel="up" href="../manual.html" title="pugixml 0.9">
|
||||
<link rel="home" href="../manual.html" title="pugixml 1.0">
|
||||
<link rel="up" href="../manual.html" title="pugixml 1.0">
|
||||
<link rel="prev" href="modify.html" title="Modifying document data">
|
||||
<link rel="next" href="xpath.html" title="XPath">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table width="100%"><tr>
|
||||
<td>pugixml 0.9 manual |
|
||||
<td>
|
||||
<a href="http://pugixml.org/">pugixml 1.0</a> manual |
|
||||
<a href="../manual.html">Overview</a> |
|
||||
<a href="install.html">Installation</a> |
|
||||
Document:
|
||||
|
|
@ -49,42 +50,45 @@
|
|||
the relevant functionality.
|
||||
</p>
|
||||
<p>
|
||||
The node/attribute data is written to the destination properly formatted according
|
||||
to the node type; all special XML symbols, such as < and &, are properly
|
||||
escaped. In order to guard against forgotten node/attribute names, empty node/attribute
|
||||
names are printed as <code class="computeroutput"><span class="string">":anonymous"</span></code>.
|
||||
For proper output, make sure all node and attribute names are set to meaningful
|
||||
Before writing to the destination the node/attribute data is properly formatted
|
||||
according to the node type; all special XML symbols, such as < and &,
|
||||
are properly escaped. In order to guard against forgotten node/attribute names,
|
||||
empty node/attribute names are printed as <code class="computeroutput"><span class="string">":anonymous"</span></code>.
|
||||
For well-formed output, make sure all node and attribute names are set to meaningful
|
||||
values.
|
||||
</p>
|
||||
<div class="caution"><table border="0" summary="Caution">
|
||||
<tr>
|
||||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../images/caution.png"></td>
|
||||
<th align="left">Caution</th>
|
||||
</tr>
|
||||
<tr><td align="left" valign="top"><p>
|
||||
Currently the content of CDATA sections is not escaped, so CDATA sections
|
||||
with values that contain <code class="computeroutput"><span class="string">"]]>"</span></code>
|
||||
will result in malformed document. This will be fixed in version 1.0.
|
||||
</p></td></tr>
|
||||
</table></div>
|
||||
<p>
|
||||
CDATA sections with values that contain <code class="computeroutput"><span class="string">"]]>"</span></code>
|
||||
are split into several sections as follows: section with value <code class="computeroutput"><span class="string">"pre]]>post"</span></code> is written as <code class="computeroutput"><span class="special"><![</span><span class="identifier">CDATA</span><span class="special">[</span><span class="identifier">pre</span><span class="special">]]]]><![</span><span class="identifier">CDATA</span><span class="special">[></span><span class="identifier">post</span><span class="special">]]></span></code>.
|
||||
While this alters the structure of the document (if you load the document after
|
||||
saving it, there will be two CDATA sections instead of one), this is the only
|
||||
way to escape CDATA contents.
|
||||
</p>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="manual.saving.file"></a><a class="link" href="saving.html#manual.saving.file" title="Saving document to a file"> Saving document to a file</a>
|
||||
</h3></div></div></div>
|
||||
<a name="xml_document::save_file"></a><p>
|
||||
If you want to save the whole document to a file, you can use the following
|
||||
function:
|
||||
<a name="xml_document::save_file"></a><a name="xml_document::save_file_wide"></a><p>
|
||||
If you want to save the whole document to a file, you can use one of the
|
||||
following functions:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xml_document</span><span class="special">::</span><span class="identifier">save_file</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">path</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">indent</span> <span class="special">=</span> <span class="string">"\t"</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">flags</span> <span class="special">=</span> <span class="identifier">format_default</span><span class="special">,</span> <span class="identifier">xml_encoding</span> <span class="identifier">encoding</span> <span class="special">=</span> <span class="identifier">encoding_auto</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
<span class="keyword">bool</span> <span class="identifier">xml_document</span><span class="special">::</span><span class="identifier">save_file</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">wchar_t</span><span class="special">*</span> <span class="identifier">path</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">indent</span> <span class="special">=</span> <span class="string">"\t"</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">flags</span> <span class="special">=</span> <span class="identifier">format_default</span><span class="special">,</span> <span class="identifier">xml_encoding</span> <span class="identifier">encoding</span> <span class="special">=</span> <span class="identifier">encoding_auto</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
This function accepts file path as its first argument, and also three optional
|
||||
These functions accept file path as its first argument, and also three optional
|
||||
arguments, which specify indentation and other output options (see <a class="xref" href="saving.html#manual.saving.options" title="Output options"> Output options</a>)
|
||||
and output data encoding (see <a class="xref" href="saving.html#manual.saving.encoding" title="Encodings"> Encodings</a>). The path has the target
|
||||
operating system format, so it can be a relative or absolute one, it should
|
||||
have the delimiters of target system, it should have the exact case if target
|
||||
file system is case-sensitive, etc. File path is passed to system file opening
|
||||
function as is.
|
||||
have the delimiters of the target system, it should have the exact case if
|
||||
the target file system is case-sensitive, etc.
|
||||
</p>
|
||||
<p>
|
||||
File path is passed to the system file opening function as is in case of
|
||||
the first function (which accepts <code class="computeroutput"><span class="keyword">const</span>
|
||||
<span class="keyword">char</span><span class="special">*</span> <span class="identifier">path</span></code>); the second function either uses
|
||||
a special file opening function if it is provided by the runtime library
|
||||
or converts the path to UTF-8 and uses the system file opening function.
|
||||
</p>
|
||||
<a name="xml_writer_file"></a><p>
|
||||
<code class="computeroutput"><span class="identifier">save_file</span></code> opens the target
|
||||
|
|
@ -96,19 +100,6 @@
|
|||
handle as the only constructor argument and then calling <code class="computeroutput"><span class="identifier">save</span></code>;
|
||||
see <a class="xref" href="saving.html#manual.saving.writer" title="Saving document via writer interface"> Saving document via writer interface</a> for writer interface details.
|
||||
</p>
|
||||
<div class="note"><table border="0" summary="Note">
|
||||
<tr>
|
||||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
|
||||
<th align="left">Note</th>
|
||||
</tr>
|
||||
<tr><td align="left" valign="top"><p>
|
||||
As of version 0.9, there is no function for saving XML document to wide
|
||||
character paths. Unfortunately, there is no portable way to do this; the
|
||||
version 1.0 will provide such function only for platforms with the corresponding
|
||||
functionality. You can use stream-saving functions as a workaround if your
|
||||
STL implementation can open file streams via wchar_t paths.
|
||||
</p></td></tr>
|
||||
</table></div>
|
||||
<p>
|
||||
This is a simple example of saving XML document to file (<a href="../samples/save_file.cpp" target="_top">samples/save_file.cpp</a>):
|
||||
</p>
|
||||
|
|
@ -126,11 +117,11 @@
|
|||
<a name="manual.saving.stream"></a><a class="link" href="saving.html#manual.saving.stream" title="Saving document to C++ IOstreams"> Saving document to C++ IOstreams</a>
|
||||
</h3></div></div></div>
|
||||
<a name="xml_document::save_stream"></a><p>
|
||||
For additional interoperability pugixml provides functions for saving document
|
||||
to any object which implements C++ std::ostream interface. This allows you
|
||||
to save documents to any standard C++ stream (i.e. file stream) or any third-party
|
||||
compliant implementation (i.e. Boost Iostreams). Most notably, this allows
|
||||
for easy debug output, since you can use <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span></code>
|
||||
To enhance interoperability pugixml provides functions for saving document
|
||||
to any object which implements C++ <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span></code>
|
||||
interface. This allows you to save documents to any standard C++ stream (i.e.
|
||||
file stream) or any third-party compliant implementation (i.e. Boost Iostreams).
|
||||
Most notably, this allows for easy debug output, since you can use <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span></code>
|
||||
stream as saving target. There are two functions, one works with narrow character
|
||||
streams, another handles wide character ones:
|
||||
</p>
|
||||
|
|
@ -142,7 +133,7 @@
|
|||
argument saves the document to the stream in the same way as <code class="computeroutput"><span class="identifier">save_file</span></code> (i.e. with requested header and
|
||||
with encoding conversions). On the other hand, <code class="computeroutput"><span class="identifier">save</span></code>
|
||||
with <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wstream</span></code> argument saves the document to
|
||||
the wide stream with <code class="computeroutput"><span class="identifier">encoding_wchar</span></code>
|
||||
the wide stream with <a class="link" href="loading.html#encoding_wchar">encoding_wchar</a>
|
||||
encoding. Because of this, using <code class="computeroutput"><span class="identifier">save</span></code>
|
||||
with wide character streams requires careful (usually platform-specific)
|
||||
stream setup (i.e. using the <code class="computeroutput"><span class="identifier">imbue</span></code>
|
||||
|
|
@ -201,7 +192,7 @@
|
|||
<p>
|
||||
<code class="computeroutput"><span class="identifier">write</span></code> function is called
|
||||
with relatively large blocks (size is usually several kilobytes, except for
|
||||
the first block with BOM, which is output only if <code class="computeroutput"><span class="identifier">format_write_bom</span></code>
|
||||
the first block with BOM, which is output only if <a class="link" href="saving.html#format_write_bom">format_write_bom</a>
|
||||
is set, and last block, which may be small), so there is often no need for
|
||||
additional buffering in the implementation.
|
||||
</p>
|
||||
|
|
@ -231,9 +222,8 @@
|
|||
<a name="manual.saving.subtree"></a><a class="link" href="saving.html#manual.saving.subtree" title="Saving a single subtree"> Saving a single subtree</a>
|
||||
</h3></div></div></div>
|
||||
<a name="xml_node::print"></a><a name="xml_node::print_stream"></a><p>
|
||||
While the previously described functions saved the whole document to the
|
||||
destination, it is easy to save a single subtree. The following functions
|
||||
are provided:
|
||||
While the previously described functions save the whole document to the destination,
|
||||
it is easy to save a single subtree. The following functions are provided:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">print</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span><span class="special">&</span> <span class="identifier">os</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">indent</span> <span class="special">=</span> <span class="string">"\t"</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">flags</span> <span class="special">=</span> <span class="identifier">format_default</span><span class="special">,</span> <span class="identifier">xml_encoding</span> <span class="identifier">encoding</span> <span class="special">=</span> <span class="identifier">encoding_auto</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">depth</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
<span class="keyword">void</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">print</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">wostream</span><span class="special">&</span> <span class="identifier">os</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">indent</span> <span class="special">=</span> <span class="string">"\t"</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">flags</span> <span class="special">=</span> <span class="identifier">format_default</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">depth</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
|
|
@ -246,10 +236,10 @@
|
|||
</p>
|
||||
<p>
|
||||
Saving a subtree differs from saving the whole document: the process behaves
|
||||
as if <code class="computeroutput"><span class="identifier">format_write_bom</span></code> is
|
||||
off, and <code class="computeroutput"><span class="identifier">format_no_declaration</span></code>
|
||||
is on, even if actual values of the flags are different. This means that
|
||||
BOM is not written to the destination, and document declaration is only written
|
||||
as if <a class="link" href="saving.html#format_write_bom">format_write_bom</a> is off, and
|
||||
<a class="link" href="saving.html#format_no_declaration">format_no_declaration</a> is on,
|
||||
even if actual values of the flags are different. This means that BOM is
|
||||
not written to the destination, and document declaration is only written
|
||||
if it is the node itself or is one of node's children. Note that this also
|
||||
holds if you're saving a document; this example (<a href="../samples/save_subtree.cpp" target="_top">samples/save_subtree.cpp</a>)
|
||||
illustrates the difference:
|
||||
|
|
@ -308,8 +298,8 @@
|
|||
by default). If this flag is on, before every node the indentation string
|
||||
is output several times, where the amount of indentation depends on the
|
||||
node's depth relative to the output subtree. This flag has no effect
|
||||
if <code class="computeroutput"><span class="identifier">format_raw</span></code> is enabled.
|
||||
This flag is <span class="bold"><strong>on</strong></span> by default. <br><br>
|
||||
if <a class="link" href="saving.html#format_raw">format_raw</a> is enabled. This flag
|
||||
is <span class="bold"><strong>on</strong></span> by default. <br><br>
|
||||
|
||||
</li>
|
||||
<li class="listitem">
|
||||
|
|
@ -318,9 +308,9 @@
|
|||
and also no newlines that are not part of document text are printed.
|
||||
Raw mode can be used for serialization where the result is not intended
|
||||
to be read by humans; also it can be useful if the document was parsed
|
||||
with <code class="computeroutput"><span class="identifier">parse_ws_pcdata</span></code>
|
||||
flag, to preserve the original document formatting as much as possible.
|
||||
This flag is <span class="bold"><strong>off</strong></span> by default.
|
||||
with <a class="link" href="loading.html#parse_ws_pcdata">parse_ws_pcdata</a> flag, to
|
||||
preserve the original document formatting as much as possible. This flag
|
||||
is <span class="bold"><strong>off</strong></span> by default.
|
||||
</li>
|
||||
</ul></div>
|
||||
<p>
|
||||
|
|
@ -429,7 +419,7 @@
|
|||
</p>
|
||||
<p>
|
||||
Also note that wide stream saving functions do not have <code class="computeroutput"><span class="identifier">encoding</span></code>
|
||||
argument and always assume <code class="computeroutput"><span class="identifier">encoding_wchar</span></code>
|
||||
argument and always assume <a class="link" href="loading.html#encoding_wchar">encoding_wchar</a>
|
||||
encoding.
|
||||
</p>
|
||||
<div class="note"><table border="0" summary="Note">
|
||||
|
|
@ -456,7 +446,8 @@
|
|||
</tr></table>
|
||||
<hr>
|
||||
<table width="100%"><tr>
|
||||
<td>pugixml 0.9 manual |
|
||||
<td>
|
||||
<a href="http://pugixml.org/">pugixml 1.0</a> manual |
|
||||
<a href="../manual.html">Overview</a> |
|
||||
<a href="install.html">Installation</a> |
|
||||
Document:
|
||||
|
|
|
|||
|
|
@ -4,13 +4,14 @@
|
|||
<title>Table of Contents</title>
|
||||
<link rel="stylesheet" href="../pugixml.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
|
||||
<link rel="home" href="../manual.html" title="pugixml 0.9">
|
||||
<link rel="up" href="../manual.html" title="pugixml 0.9">
|
||||
<link rel="home" href="../manual.html" title="pugixml 1.0">
|
||||
<link rel="up" href="../manual.html" title="pugixml 1.0">
|
||||
<link rel="prev" href="apiref.html" title="API Reference">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table width="100%"><tr>
|
||||
<td>pugixml 0.9 manual |
|
||||
<td>
|
||||
<a href="http://pugixml.org/">pugixml 1.0</a> manual |
|
||||
<a href="../manual.html">Overview</a> |
|
||||
<a href="install.html">Installation</a> |
|
||||
Document:
|
||||
|
|
@ -134,7 +135,8 @@
|
|||
</tr></table>
|
||||
<hr>
|
||||
<table width="100%"><tr>
|
||||
<td>pugixml 0.9 manual |
|
||||
<td>
|
||||
<a href="http://pugixml.org/">pugixml 1.0</a> manual |
|
||||
<a href="../manual.html">Overview</a> |
|
||||
<a href="install.html">Installation</a> |
|
||||
Document:
|
||||
|
|
|
|||
|
|
@ -4,14 +4,15 @@
|
|||
<title>XPath</title>
|
||||
<link rel="stylesheet" href="../pugixml.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
|
||||
<link rel="home" href="../manual.html" title="pugixml 0.9">
|
||||
<link rel="up" href="../manual.html" title="pugixml 0.9">
|
||||
<link rel="home" href="../manual.html" title="pugixml 1.0">
|
||||
<link rel="up" href="../manual.html" title="pugixml 1.0">
|
||||
<link rel="prev" href="saving.html" title="Saving document">
|
||||
<link rel="next" href="changes.html" title="Changelog">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table width="100%"><tr>
|
||||
<td>pugixml 0.9 manual |
|
||||
<td>
|
||||
<a href="http://pugixml.org/">pugixml 1.0</a> manual |
|
||||
<a href="../manual.html">Overview</a> |
|
||||
<a href="install.html">Installation</a> |
|
||||
Document:
|
||||
|
|
@ -33,6 +34,7 @@
|
|||
<dt><span class="section"><a href="xpath.html#manual.xpath.types"> XPath types</a></span></dt>
|
||||
<dt><span class="section"><a href="xpath.html#manual.xpath.select"> Selecting nodes via XPath expression</a></span></dt>
|
||||
<dt><span class="section"><a href="xpath.html#manual.xpath.query"> Using query objects</a></span></dt>
|
||||
<dt><span class="section"><a href="xpath.html#manual.xpath.variables"> Using variables</a></span></dt>
|
||||
<dt><span class="section"><a href="xpath.html#manual.xpath.errors"> Error handling</a></span></dt>
|
||||
<dt><span class="section"><a href="xpath.html#manual.xpath.w3c"> Conformance to W3C specification</a></span></dt>
|
||||
</dl></div>
|
||||
|
|
@ -54,18 +56,6 @@
|
|||
at tizag.com</a>, and <a href="http://www.w3.org/TR/xpath/" target="_top">the XPath
|
||||
1.0 specification</a>.
|
||||
</p>
|
||||
<div class="note"><table border="0" summary="Note">
|
||||
<tr>
|
||||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
|
||||
<th align="left">Note</th>
|
||||
</tr>
|
||||
<tr><td align="left" valign="top"><p>
|
||||
As of version 0.9, you need both STL and exception support to use XPath;
|
||||
XPath is disabled if either <code class="computeroutput"><span class="identifier">PUGIXML_NO_STL</span></code>
|
||||
or <code class="computeroutput"><span class="identifier">PUGIXML_NO_EXCEPTIONS</span></code>
|
||||
is defined.
|
||||
</p></td></tr>
|
||||
</table></div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="manual.xpath.types"></a><a class="link" href="xpath.html#manual.xpath.types" title="XPath types"> XPath types</a>
|
||||
|
|
@ -76,7 +66,7 @@
|
|||
type, number type corresponds to <code class="computeroutput"><span class="keyword">double</span></code>
|
||||
type, string type corresponds to either <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code>
|
||||
or <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wstring</span></code>, depending on whether <a class="link" href="dom.html#manual.dom.unicode" title="Unicode interface">wide
|
||||
character interface is enabled</a>, and node set corresponds to <code class="computeroutput"><span class="identifier">xpath_node_set</span></code> type. There is an enumeration,
|
||||
character interface is enabled</a>, and node set corresponds to <a class="link" href="xpath.html#xpath_node_set">xpath_node_set</a> type. There is an enumeration,
|
||||
<code class="computeroutput"><span class="identifier">xpath_value_type</span></code>, which can
|
||||
take the values <code class="computeroutput"><span class="identifier">xpath_type_boolean</span></code>,
|
||||
<code class="computeroutput"><span class="identifier">xpath_type_number</span></code>, <code class="computeroutput"><span class="identifier">xpath_type_string</span></code> or <code class="computeroutput"><span class="identifier">xpath_type_node_set</span></code>,
|
||||
|
|
@ -117,12 +107,14 @@
|
|||
for equality with each other.
|
||||
</p>
|
||||
<a name="xpath_node::ctor"></a><p>
|
||||
You can also create XPath nodes with one of tree constructors: the default
|
||||
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). However, usually you don't need
|
||||
to create your own XPath node objects, since they are returned to you via
|
||||
selection functions.
|
||||
belong to the attribute list of the node). The constructor from <code class="computeroutput"><span class="identifier">xml_node</span></code> is implicit, so you can usually
|
||||
pass <code class="computeroutput"><span class="identifier">xml_node</span></code> to functions
|
||||
that expect <code class="computeroutput"><span class="identifier">xpath_node</span></code>. Apart
|
||||
from that you usually don't need to create your own XPath node objects, since
|
||||
they are returned to you via selection functions.
|
||||
</p>
|
||||
<a name="xpath_node_set"></a><p>
|
||||
XPath expressions operate not on single nodes, but instead on node sets.
|
||||
|
|
@ -153,7 +145,7 @@
|
|||
the iterators are random-access, all of the above operations are constant
|
||||
time, and accessing the element at index that is greater or equal than the
|
||||
set size results in undefined behavior. You can use both iterator-based and
|
||||
index-based access for iteration, however the iterator-based can be faster.
|
||||
index-based access for iteration, however the iterator-based one can be faster.
|
||||
</p>
|
||||
<a name="xpath_node_set::type"></a><a name="xpath_node_set::type_unsorted"></a><a name="xpath_node_set::type_sorted"></a><a name="xpath_node_set::type_sorted_reverse"></a><a name="xpath_node_set::sort"></a><p>
|
||||
The order of iteration depends on the order of nodes inside the set; the
|
||||
|
|
@ -195,6 +187,21 @@
|
|||
the complexity does - if the set is sorted, the complexity is constant, otherwise
|
||||
it is linear in the number of elements or worse.
|
||||
</p>
|
||||
<a name="xpath_node_set::ctor"></a><p>
|
||||
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 (<code class="computeroutput"><span class="identifier">const_iterator</span></code>
|
||||
is a typedef for <code class="computeroutput"><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">*</span></code>), and an optional type:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="identifier">xpath_node_set</span><span class="special">::</span><span class="identifier">xpath_node_set</span><span class="special">(</span><span class="identifier">const_iterator</span> <span class="identifier">begin</span><span class="special">,</span> <span class="identifier">const_iterator</span> <span class="identifier">end</span><span class="special">,</span> <span class="identifier">type_t</span> <span class="identifier">type</span> <span class="special">=</span> <span class="identifier">type_unsorted</span><span class="special">);</span>
|
||||
</pre>
|
||||
<p>
|
||||
The constructor copies the specified range and sets the specified type. The
|
||||
objects in the range are not checked in any way; you'll have to ensure that
|
||||
the range contains no duplicates, and that the objects are sorted according
|
||||
to the <code class="computeroutput"><span class="identifier">type</span></code> parameter. Otherwise
|
||||
XPath operations with this set may produce unexpected results.
|
||||
</p>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
|
|
@ -204,8 +211,8 @@
|
|||
If you want to select nodes that match some XPath expression, you can do
|
||||
it with the following functions:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="identifier">xpath_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">select_single_node</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">query</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
<span class="identifier">xpath_node_set</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">select_nodes</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">query</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
<pre class="programlisting"><span class="identifier">xpath_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">select_single_node</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">query</span><span class="special">,</span> <span class="identifier">xpath_variable_set</span><span class="special">*</span> <span class="identifier">variables</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
<span class="identifier">xpath_node_set</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">select_nodes</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">query</span><span class="special">,</span> <span class="identifier">xpath_variable_set</span><span class="special">*</span> <span class="identifier">variables</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">select_nodes</span></code> function compiles
|
||||
|
|
@ -219,7 +226,7 @@
|
|||
returns null XPath node.
|
||||
</p>
|
||||
<p>
|
||||
Both functions throw <code class="computeroutput"><span class="identifier">xpath_exception</span></code>
|
||||
If exception handling is not disabled, both functions throw <a class="link" href="xpath.html#xpath_exception">xpath_exception</a>
|
||||
if the query can not be compiled or if it returns a value with type other
|
||||
than node set; see <a class="xref" href="xpath.html#manual.xpath.errors" title="Error handling"> Error handling</a> for details.
|
||||
</p>
|
||||
|
|
@ -235,7 +242,7 @@
|
|||
<span class="identifier">xpath_node_set</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">select_nodes</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_query</span><span class="special">&</span> <span class="identifier">query</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
Both functions throw <code class="computeroutput"><span class="identifier">xpath_exception</span></code>
|
||||
If exception handling is not disabled, both functions throw <a class="link" href="xpath.html#xpath_exception">xpath_exception</a>
|
||||
if the query returns a value with type other than node set.
|
||||
</p>
|
||||
<p>
|
||||
|
|
@ -268,8 +275,8 @@
|
|||
<a name="xpath_query"></a><p>
|
||||
When you call <code class="computeroutput"><span class="identifier">select_nodes</span></code>
|
||||
with an expression string as an argument, a query object is created behind
|
||||
the scene. A query object represents a compiled XPath expression. Query objects
|
||||
can be needed in the following circumstances:
|
||||
the scenes. A query object represents a compiled XPath expression. Query
|
||||
objects can be needed in the following circumstances:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||||
<li class="listitem">
|
||||
|
|
@ -296,33 +303,34 @@
|
|||
You can create a query object with the constructor that takes XPath expression
|
||||
as an argument:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">explicit</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">xpath_query</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">query</span><span class="special">);</span>
|
||||
<pre class="programlisting"><span class="keyword">explicit</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">xpath_query</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">query</span><span class="special">,</span> <span class="identifier">xpath_variable_set</span><span class="special">*</span> <span class="identifier">variables</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span>
|
||||
</pre>
|
||||
<a name="xpath_query::return_type"></a><p>
|
||||
The expression is compiled and the compiled representation is stored in the
|
||||
new query object. If compilation fails, <code class="computeroutput"><span class="identifier">xpath_exception</span></code>
|
||||
is thrown (see <a class="xref" href="xpath.html#manual.xpath.errors" title="Error handling"> Error handling</a> for details). After the query is created,
|
||||
you can query the type of the evaluation result using the following function:
|
||||
new query object. If compilation fails, <a class="link" href="xpath.html#xpath_exception">xpath_exception</a>
|
||||
is thrown if exception handling is not disabled (see <a class="xref" href="xpath.html#manual.xpath.errors" title="Error handling"> Error handling</a> for
|
||||
details). After the query is created, you can query the type of the evaluation
|
||||
result using the following function:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="identifier">xpath_value_type</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">return_type</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
</pre>
|
||||
<a name="xpath_query::evaluate_boolean"></a><a name="xpath_query::evaluate_number"></a><a name="xpath_query::evaluate_string"></a><a name="xpath_query::evaluate_node_set"></a><p>
|
||||
You can evaluate the query using one of the following functions:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">evaluate_boolean</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
<span class="keyword">double</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">evaluate_number</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
<span class="identifier">string_t</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">evaluate_string</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
<span class="identifier">xpath_node_set</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">evaluate_node_set</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">evaluate_boolean</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
<span class="keyword">double</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">evaluate_number</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
<span class="identifier">string_t</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">evaluate_string</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
<span class="identifier">xpath_node_set</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">evaluate_node_set</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
All functions take the context node as an argument, compute the expression
|
||||
and return the result, converted to the requested type. By XPath specification,
|
||||
value of any type can be converted to boolean, number or string value, but
|
||||
no type other than node set can be converted to node set. Because of this,
|
||||
<code class="computeroutput"><span class="identifier">evaluate_boolean</span></code>, <code class="computeroutput"><span class="identifier">evaluate_number</span></code> and <code class="computeroutput"><span class="identifier">evaluate_string</span></code>
|
||||
always return a result, but <code class="computeroutput"><span class="identifier">evaluate_node_set</span></code>
|
||||
throws an <code class="computeroutput"><span class="identifier">xpath_exception</span></code>
|
||||
if the return type is not node set.
|
||||
and return the result, converted to the requested type. According to XPath
|
||||
specification, value of any type can be converted to boolean, number or string
|
||||
value, but no type other than node set can be converted to node set. Because
|
||||
of this, <code class="computeroutput"><span class="identifier">evaluate_boolean</span></code>,
|
||||
<code class="computeroutput"><span class="identifier">evaluate_number</span></code> and <code class="computeroutput"><span class="identifier">evaluate_string</span></code> always return a result,
|
||||
but <code class="computeroutput"><span class="identifier">evaluate_node_set</span></code> results
|
||||
in an error if the return type is not node set (see <a class="xref" href="xpath.html#manual.xpath.errors" title="Error handling"> Error handling</a>).
|
||||
</p>
|
||||
<div class="note"><table border="0" summary="Note">
|
||||
<tr>
|
||||
|
|
@ -334,6 +342,36 @@
|
|||
is equivalent to calling <code class="computeroutput"><span class="identifier">xpath_query</span><span class="special">(</span><span class="string">"query"</span><span class="special">).</span><span class="identifier">evaluate_node_set</span><span class="special">(</span><span class="identifier">node</span><span class="special">)</span></code>.
|
||||
</p></td></tr>
|
||||
</table></div>
|
||||
<a name="xpath_query::evaluate_string_buffer"></a><p>
|
||||
Note that <code class="computeroutput"><span class="identifier">evaluate_string</span></code>
|
||||
function returns the STL string; as such, it's not available in <a class="link" href="install.html#PUGIXML_NO_STL">PUGIXML_NO_STL</a>
|
||||
mode and also usually allocates memory. There is another string evaluation
|
||||
function:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="identifier">size_t</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">evaluate_string</span><span class="special">(</span><span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">size_t</span> <span class="identifier">capacity</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
This function evaluates the string, and then writes the result to <code class="computeroutput"><span class="identifier">buffer</span></code> (but at most <code class="computeroutput"><span class="identifier">capacity</span></code>
|
||||
characters); then it returns the full size of the result in characters, including
|
||||
the terminating zero. If <code class="computeroutput"><span class="identifier">capacity</span></code>
|
||||
is not 0, the resulting buffer is always zero-terminated. You can use this
|
||||
function as follows:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||||
<li class="listitem">
|
||||
First call the function with <code class="computeroutput"><span class="identifier">buffer</span>
|
||||
<span class="special">=</span> <span class="number">0</span></code>
|
||||
and <code class="computeroutput"><span class="identifier">capacity</span> <span class="special">=</span>
|
||||
<span class="number">0</span></code>; then allocate the returned amount
|
||||
of characters, and call the function again, passing the allocated storage
|
||||
and the amount of characters;
|
||||
</li>
|
||||
<li class="listitem">
|
||||
First call the function with small buffer and buffer capacity; then,
|
||||
if the result is larger than the capacity, the output has been trimmed,
|
||||
so allocate a larger buffer and call the function again.
|
||||
</li>
|
||||
</ul></div>
|
||||
<p>
|
||||
This is an example of using query objects (<a href="../samples/xpath_query.cpp" target="_top">samples/xpath_query.cpp</a>):
|
||||
</p>
|
||||
|
|
@ -367,22 +405,237 @@
|
|||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="manual.xpath.errors"></a><a class="link" href="xpath.html#manual.xpath.errors" title="Error handling"> Error handling</a>
|
||||
<a name="manual.xpath.variables"></a><a class="link" href="xpath.html#manual.xpath.variables" title="Using variables"> Using variables</a>
|
||||
</h3></div></div></div>
|
||||
<a name="xpath_exception"></a><a name="xpath_exception::what"></a><p>
|
||||
As of version 0.9, all XPath errors result in thrown exceptions. The errors
|
||||
can arise during expression compilation or node set evaluation. In both cases,
|
||||
an <code class="computeroutput"><span class="identifier">xpath_exception</span></code> object
|
||||
is thrown. This is an exception object that implements <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span></code>
|
||||
interface, and thus has a single function <code class="computeroutput"><span class="identifier">what</span><span class="special">()</span></code>:
|
||||
<p>
|
||||
XPath queries may contain references to variables; this is useful if you
|
||||
want to use queries that depend on some dynamic parameter without manually
|
||||
preparing the complete query string, or if you want to reuse the same query
|
||||
object for similar queries.
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">virtual</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">xpath_exception</span><span class="special">::</span><span class="identifier">what</span><span class="special">()</span> <span class="keyword">const</span> <span class="keyword">throw</span><span class="special">();</span>
|
||||
<p>
|
||||
Variable references have the form <code class="computeroutput"><span class="identifier">$name</span></code>; in order to use them, you have to provide
|
||||
a variable set, which includes all variables present in the query with correct
|
||||
types. This set is passed to <code class="computeroutput"><span class="identifier">xpath_query</span></code>
|
||||
constructor or to <code class="computeroutput"><span class="identifier">select_nodes</span></code>/<code class="computeroutput"><span class="identifier">select_single_node</span></code> functions:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">explicit</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">xpath_query</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">query</span><span class="special">,</span> <span class="identifier">xpath_variable_set</span><span class="special">*</span> <span class="identifier">variables</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span>
|
||||
<span class="identifier">xpath_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">select_single_node</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">query</span><span class="special">,</span> <span class="identifier">xpath_variable_set</span><span class="special">*</span> <span class="identifier">variables</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
<span class="identifier">xpath_node_set</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">select_nodes</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">query</span><span class="special">,</span> <span class="identifier">xpath_variable_set</span><span class="special">*</span> <span class="identifier">variables</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
This function returns the error message. Currently it is impossible to get
|
||||
the exact place where query compilation failed. This functionality, along
|
||||
with optional error handling without exceptions, will be available in version
|
||||
1.0.
|
||||
If you're using query objects, you can change the variable values before
|
||||
<code class="computeroutput"><span class="identifier">evaluate</span></code>/<code class="computeroutput"><span class="identifier">select</span></code>
|
||||
calls to change the query behavior.
|
||||
</p>
|
||||
<div class="note"><table border="0" summary="Note">
|
||||
<tr>
|
||||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
|
||||
<th align="left">Note</th>
|
||||
</tr>
|
||||
<tr><td align="left" valign="top"><p>
|
||||
The variable set pointer is stored in the query object; you have to ensure
|
||||
that the lifetime of the set exceeds that of query object.
|
||||
</p></td></tr>
|
||||
</table></div>
|
||||
<a name="xpath_variable_set"></a><p>
|
||||
Variable sets correspond to <code class="computeroutput"><span class="identifier">xpath_variable_set</span></code>
|
||||
type, which is essentially a variable container.
|
||||
</p>
|
||||
<a name="xpath_variable_set::add"></a><p>
|
||||
You can add new variables with the following function:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="identifier">xpath_variable</span><span class="special">*</span> <span class="identifier">xpath_variable_set</span><span class="special">::</span><span class="identifier">add</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">xpath_value_type</span> <span class="identifier">type</span><span class="special">);</span>
|
||||
</pre>
|
||||
<p>
|
||||
The function tries to add a new variable with the specified name and type;
|
||||
if the variable with such name does not exist in the set, the function adds
|
||||
a new variable and returns the variable handle; if there is already a variable
|
||||
with the specified name, the function returns the variable handle if variable
|
||||
has the specified type. Otherwise the function returns null pointer; it also
|
||||
returns null pointer on allocation failure.
|
||||
</p>
|
||||
<p>
|
||||
New variables are assigned the default value which depends on the type:
|
||||
<code class="computeroutput"><span class="number">0</span></code> for numbers, <code class="computeroutput"><span class="keyword">false</span></code> for booleans, empty string for strings
|
||||
and empty set for node sets.
|
||||
</p>
|
||||
<a name="xpath_variable_set::get"></a><p>
|
||||
You can get the existing variables with the following functions:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="identifier">xpath_variable</span><span class="special">*</span> <span class="identifier">xpath_variable_set</span><span class="special">::</span><span class="identifier">get</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">name</span><span class="special">);</span>
|
||||
<span class="keyword">const</span> <span class="identifier">xpath_variable</span><span class="special">*</span> <span class="identifier">xpath_variable_set</span><span class="special">::</span><span class="identifier">get</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">name</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
The functions return the variable handle, or null pointer if the variable
|
||||
with the specified name is not found.
|
||||
</p>
|
||||
<a name="xpath_variable_set::set"></a><p>
|
||||
Additionally, there are the helper functions for setting the variable value
|
||||
by name; they try to add the variable with the corresponding type, if it
|
||||
does not exist, and to set the value. If the variable with the same name
|
||||
but with different type is already present, they return <code class="computeroutput"><span class="keyword">false</span></code>;
|
||||
they also return <code class="computeroutput"><span class="keyword">false</span></code> on allocation
|
||||
failure. Note that these functions do not perform any type conversions.
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xpath_variable_set</span><span class="special">::</span><span class="identifier">set</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="keyword">bool</span> <span class="identifier">value</span><span class="special">);</span>
|
||||
<span class="keyword">bool</span> <span class="identifier">xpath_variable_set</span><span class="special">::</span><span class="identifier">set</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">value</span><span class="special">);</span>
|
||||
<span class="keyword">bool</span> <span class="identifier">xpath_variable_set</span><span class="special">::</span><span class="identifier">set</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">value</span><span class="special">);</span>
|
||||
<span class="keyword">bool</span> <span class="identifier">xpath_variable_set</span><span class="special">::</span><span class="identifier">set</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">xpath_node_set</span><span class="special">&</span> <span class="identifier">value</span><span class="special">);</span>
|
||||
</pre>
|
||||
<p>
|
||||
The variable values are copied to the internal variable storage, so you can
|
||||
modify or destroy them after the functions return.
|
||||
</p>
|
||||
<a name="xpath_variable"></a><p>
|
||||
If setting variables by name is not efficient enough, or if you have to inspect
|
||||
variable information or get variable values, you can use variable handles.
|
||||
A variable corresponds to the <code class="computeroutput"><span class="identifier">xpath_variable</span></code>
|
||||
type, and a variable handle is simply a pointer to <code class="computeroutput"><span class="identifier">xpath_variable</span></code>.
|
||||
</p>
|
||||
<a name="xpath_variable::type"></a><a name="xpath_variable::name"></a><p>
|
||||
In order to get variable information, you can use one of the following functions:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">xpath_variable</span><span class="special">::</span><span class="identifier">name</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
<span class="identifier">xpath_value_type</span> <span class="identifier">xpath_variable</span><span class="special">::</span><span class="identifier">type</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
Note that each variable has a distinct type which is specified upon variable
|
||||
creation and can not be changed later.
|
||||
</p>
|
||||
<a name="xpath_variable::get_boolean"></a><a name="xpath_variable::get_number"></a><a name="xpath_variable::get_string"></a><a name="xpath_variable::get_node_set"></a><p>
|
||||
In order to get variable value, you should use one of the following functions,
|
||||
depending on the variable type:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xpath_variable</span><span class="special">::</span><span class="identifier">get_boolean</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
<span class="keyword">double</span> <span class="identifier">xpath_variable</span><span class="special">::</span><span class="identifier">get_number</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
<span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">xpath_variable</span><span class="special">::</span><span class="identifier">get_string</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
<span class="keyword">const</span> <span class="identifier">xpath_node_set</span><span class="special">&</span> <span class="identifier">xpath_variable</span><span class="special">::</span><span class="identifier">get_node_set</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
These functions return the value of the variable. Note that no type conversions
|
||||
are performed; if the type mismatch occurs, a dummy value is returned (<code class="computeroutput"><span class="keyword">false</span></code> for booleans, <code class="computeroutput"><span class="identifier">NaN</span></code>
|
||||
for numbers, empty string for strings and empty set for node sets).
|
||||
</p>
|
||||
<a name="xpath_variable::set"></a><p>
|
||||
In order to set variable value, you should use one of the following functions,
|
||||
depending on the variable type:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xpath_variable</span><span class="special">::</span><span class="identifier">set</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">value</span><span class="special">);</span>
|
||||
<span class="keyword">bool</span> <span class="identifier">xpath_variable</span><span class="special">::</span><span class="identifier">set</span><span class="special">(</span><span class="keyword">double</span> <span class="identifier">value</span><span class="special">);</span>
|
||||
<span class="keyword">bool</span> <span class="identifier">xpath_variable</span><span class="special">::</span><span class="identifier">set</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">value</span><span class="special">);</span>
|
||||
<span class="keyword">bool</span> <span class="identifier">xpath_variable</span><span class="special">::</span><span class="identifier">set</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node_set</span><span class="special">&</span> <span class="identifier">value</span><span class="special">);</span>
|
||||
</pre>
|
||||
<p>
|
||||
These function modify the variable value. Note that no type conversions are
|
||||
performed; if the type mismatch occurs, the functions return <code class="computeroutput"><span class="keyword">false</span></code>; they also return <code class="computeroutput"><span class="keyword">false</span></code>
|
||||
on allocation failure. The variable values are copied to the internal variable
|
||||
storage, so you can modify or destroy them after the functions return.
|
||||
</p>
|
||||
<p>
|
||||
This is an example of using variables in XPath queries (<a href="../samples/xpath_variables.cpp" target="_top">samples/xpath_variables.cpp</a>):
|
||||
</p>
|
||||
<p>
|
||||
|
||||
</p>
|
||||
<pre class="programlisting"><span class="comment">// Select nodes via compiled query
|
||||
</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_variable_set</span> <span class="identifier">vars</span><span class="special">;</span>
|
||||
<span class="identifier">vars</span><span class="special">.</span><span class="identifier">add</span><span class="special">(</span><span class="string">"remote"</span><span class="special">,</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_type_boolean</span><span class="special">);</span>
|
||||
|
||||
<span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_query</span> <span class="identifier">query_remote_tools</span><span class="special">(</span><span class="string">"/Profile/Tools/Tool[@AllowRemote = string($remote)]"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">vars</span><span class="special">);</span>
|
||||
|
||||
<span class="identifier">vars</span><span class="special">.</span><span class="identifier">set</span><span class="special">(</span><span class="string">"remote"</span><span class="special">,</span> <span class="keyword">true</span><span class="special">);</span>
|
||||
<span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_node_set</span> <span class="identifier">tools_remote</span> <span class="special">=</span> <span class="identifier">query_remote_tools</span><span class="special">.</span><span class="identifier">evaluate_node_set</span><span class="special">(</span><span class="identifier">doc</span><span class="special">);</span>
|
||||
|
||||
<span class="identifier">vars</span><span class="special">.</span><span class="identifier">set</span><span class="special">(</span><span class="string">"remote"</span><span class="special">,</span> <span class="keyword">false</span><span class="special">);</span>
|
||||
<span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_node_set</span> <span class="identifier">tools_local</span> <span class="special">=</span> <span class="identifier">query_remote_tools</span><span class="special">.</span><span class="identifier">evaluate_node_set</span><span class="special">(</span><span class="identifier">doc</span><span class="special">);</span>
|
||||
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Remote tool: "</span><span class="special">;</span>
|
||||
<span class="identifier">tools_remote</span><span class="special">[</span><span class="number">2</span><span class="special">].</span><span class="identifier">node</span><span class="special">().</span><span class="identifier">print</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">);</span>
|
||||
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Local tool: "</span><span class="special">;</span>
|
||||
<span class="identifier">tools_local</span><span class="special">[</span><span class="number">0</span><span class="special">].</span><span class="identifier">node</span><span class="special">().</span><span class="identifier">print</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">);</span>
|
||||
|
||||
<span class="comment">// You can pass the context directly to select_nodes/select_single_node
|
||||
</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_node_set</span> <span class="identifier">tools_local_imm</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">select_nodes</span><span class="special">(</span><span class="string">"/Profile/Tools/Tool[@AllowRemote = string($remote)]"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">vars</span><span class="special">);</span>
|
||||
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Local tool imm: "</span><span class="special">;</span>
|
||||
<span class="identifier">tools_local_imm</span><span class="special">[</span><span class="number">0</span><span class="special">].</span><span class="identifier">node</span><span class="special">().</span><span class="identifier">print</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">);</span>
|
||||
</pre>
|
||||
<p>
|
||||
</p>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="manual.xpath.errors"></a><a class="link" href="xpath.html#manual.xpath.errors" title="Error handling"> Error handling</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
There are two different mechanisms for error handling in XPath implementation;
|
||||
the mechanism used depends on whether exception support is disabled (this
|
||||
is controlled with <a class="link" href="install.html#PUGIXML_NO_EXCEPTIONS">PUGIXML_NO_EXCEPTIONS</a>
|
||||
define).
|
||||
</p>
|
||||
<a name="xpath_exception"></a><a name="xpath_exception::result"></a><a name="xpath_exception::what"></a><p>
|
||||
By default, XPath functions throw <code class="computeroutput"><span class="identifier">xpath_exception</span></code>
|
||||
object in case of errors; additionally, in the event any memory allocation
|
||||
fails, an <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bad_alloc</span></code> exception is thrown. Also <code class="computeroutput"><span class="identifier">xpath_exception</span></code> is thrown if the query
|
||||
is evaluated to a node set, but the return type is not node set. If the query
|
||||
constructor succeeds (i.e. no exception is thrown), the query object is valid.
|
||||
Otherwise you can get the error details via one of the following functions:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">virtual</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">xpath_exception</span><span class="special">::</span><span class="identifier">what</span><span class="special">()</span> <span class="keyword">const</span> <span class="keyword">throw</span><span class="special">();</span>
|
||||
<span class="keyword">const</span> <span class="identifier">xpath_parse_result</span><span class="special">&</span> <span class="identifier">xpath_exception</span><span class="special">::</span><span class="identifier">result</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
</pre>
|
||||
<a name="xpath_query::unspecified_bool_type"></a><a name="xpath_query::result"></a><p>
|
||||
If exceptions are disabled, then in the event of parsing failure the query
|
||||
is initialized to invalid state; you can test if the query object is valid
|
||||
by using it in a boolean expression: <code class="computeroutput"><span class="keyword">if</span>
|
||||
<span class="special">(</span><span class="identifier">query</span><span class="special">)</span> <span class="special">{</span> <span class="special">...</span>
|
||||
<span class="special">}</span></code>. Additionally, you can get parsing
|
||||
result via the result() accessor:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">const</span> <span class="identifier">xpath_parse_result</span><span class="special">&</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">result</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
Without exceptions, evaluating invalid query results in <code class="computeroutput"><span class="keyword">false</span></code>,
|
||||
empty string, NaN or an empty node set, depending on the type; evaluating
|
||||
a query as a node set results in an empty node set if the return type is
|
||||
not node set.
|
||||
</p>
|
||||
<a name="xpath_parse_result"></a><p>
|
||||
The information about parsing result is returned via <code class="computeroutput"><span class="identifier">xpath_parse_result</span></code>
|
||||
object. It contains parsing status and the offset of last successfully parsed
|
||||
character from the beginning of the source stream:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">xpath_parse_result</span>
|
||||
<span class="special">{</span>
|
||||
<span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">error</span><span class="special">;</span>
|
||||
<span class="identifier">ptrdiff_t</span> <span class="identifier">offset</span><span class="special">;</span>
|
||||
|
||||
<span class="keyword">operator</span> <span class="keyword">bool</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
<span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">description</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
|
||||
<span class="special">};</span>
|
||||
</pre>
|
||||
<a name="xpath_parse_result::error"></a><p>
|
||||
Parsing result is represented as the error message; it is either a null pointer,
|
||||
in case there is no error, or the error message in the form of ASCII zero-terminated
|
||||
string.
|
||||
</p>
|
||||
<a name="xpath_parse_result::description"></a><p>
|
||||
<code class="computeroutput"><span class="identifier">description</span><span class="special">()</span></code>
|
||||
member function can be used to get the error message; it never returns the
|
||||
null pointer, so you can safely use description() even if query parsing succeeded.
|
||||
</p>
|
||||
<a name="xpath_parse_result::offset"></a><p>
|
||||
In addition to the error message, parsing result has an <code class="computeroutput"><span class="identifier">offset</span></code>
|
||||
member, which contains the offset of last successfully parsed character.
|
||||
This offset is in units of <a class="link" href="dom.html#char_t">pugi::char_t</a> (bytes
|
||||
for character mode, wide characters for wide character mode).
|
||||
</p>
|
||||
<a name="xpath_parse_result::bool"></a><p>
|
||||
Parsing result object can be implicitly converted to <code class="computeroutput"><span class="keyword">bool</span></code>
|
||||
like this: <code class="computeroutput"><span class="keyword">if</span> <span class="special">(</span><span class="identifier">result</span><span class="special">)</span> <span class="special">{</span> <span class="special">...</span> <span class="special">}</span>
|
||||
<span class="keyword">else</span> <span class="special">{</span> <span class="special">...</span> <span class="special">}</span></code>.
|
||||
</p>
|
||||
<p>
|
||||
This is an example of XPath error handling (<a href="../samples/xpath_error.cpp" target="_top">samples/xpath_error.cpp</a>):
|
||||
|
|
@ -440,7 +693,7 @@
|
|||
but instead has three.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Since document can't have a document type declaration, <code class="computeroutput"><span class="identifier">id</span><span class="special">()</span></code>
|
||||
Since the document type declaration is not used for parsing, <code class="computeroutput"><span class="identifier">id</span><span class="special">()</span></code>
|
||||
function always returns an empty node set.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
|
|
@ -459,13 +712,7 @@
|
|||
value, depending on the library configuration; this means that some string
|
||||
functions are not fully Unicode-aware. This affects <code class="computeroutput"><span class="identifier">substring</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">string</span><span class="special">-</span><span class="identifier">length</span><span class="special">()</span></code> and <code class="computeroutput"><span class="identifier">translate</span><span class="special">()</span></code> functions.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Variable references are not supported.
|
||||
</li>
|
||||
</ul></div>
|
||||
<p>
|
||||
Some of these incompatibilities will be fixed in version 1.0.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
|
|
@ -477,7 +724,8 @@
|
|||
</tr></table>
|
||||
<hr>
|
||||
<table width="100%"><tr>
|
||||
<td>pugixml 0.9 manual |
|
||||
<td>
|
||||
<a href="http://pugixml.org/">pugixml 1.0</a> manual |
|
||||
<a href="../manual.html">Overview</a> |
|
||||
<a href="install.html">Installation</a> |
|
||||
Document:
|
||||
|
|
|
|||
|
|
@ -1,16 +1,16 @@
|
|||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>pugixml 0.9</title>
|
||||
<title>pugixml 1.0</title>
|
||||
<link rel="stylesheet" href="pugixml.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
|
||||
<link rel="home" href="quickstart.html" title="pugixml 0.9">
|
||||
<link rel="home" href="quickstart.html" title="pugixml 1.0">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<div class="article">
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="quickstart.main"></a><a class="link" href="quickstart.html#quickstart.main" title="pugixml 0.9 quick start guide"> pugixml 0.9 quick start guide</a>
|
||||
<a name="quickstart.main"></a><a class="link" href="quickstart.html#quickstart.main" title="pugixml 1.0 quick start guide"> pugixml 1.0 quick start guide</a>
|
||||
</h2></div></div></div>
|
||||
<div class="toc"><dl>
|
||||
<dt><span class="section"><a href="quickstart.html#quickstart.main.introduction"> Introduction</a></span></dt>
|
||||
|
|
@ -28,16 +28,17 @@
|
|||
<a name="quickstart.main.introduction"></a><a class="link" href="quickstart.html#quickstart.main.introduction" title="Introduction"> Introduction</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
pugixml is a light-weight C++ XML processing library. It consists of a DOM-like
|
||||
interface with rich traversal/modification capabilities, an extremely fast
|
||||
XML parser which constructs the DOM tree from an XML file/buffer, and an
|
||||
XPath 1.0 implementation for complex data-driven tree queries. Full Unicode
|
||||
support is also available, with Unicode interface variants and conversions
|
||||
between different Unicode encodings (which happen automatically during parsing/saving).
|
||||
The library is extremely portable and easy to integrate and use. pugixml
|
||||
is developed and maintained since 2006 and has many users. All code is distributed
|
||||
under the MIT license, making it completely free to use in both open-source
|
||||
and proprietary applications.
|
||||
<a href="http://pugixml.org/" target="_top">pugixml</a> is a light-weight C++ XML
|
||||
processing library. It consists of a DOM-like interface with rich traversal/modification
|
||||
capabilities, an extremely fast XML parser which constructs the DOM tree
|
||||
from an XML file/buffer, and an XPath 1.0 implementation for complex data-driven
|
||||
tree queries. Full Unicode support is also available, with Unicode interface
|
||||
variants and conversions between different Unicode encodings (which happen
|
||||
automatically during parsing/saving). The library is extremely portable and
|
||||
easy to integrate and use. pugixml is developed and maintained since 2006
|
||||
and has many users. All code is distributed under the <a class="link" href="quickstart.html#quickstart.main.license" title="License">MIT
|
||||
license</a>, making it completely free to use in both open-source and
|
||||
proprietary applications.
|
||||
</p>
|
||||
<p>
|
||||
pugixml enables very fast, convenient and memory-efficient XML document processing.
|
||||
|
|
@ -74,19 +75,21 @@
|
|||
pugixml is distributed in source form. You can download a source distribution
|
||||
via one of the following links:
|
||||
</p>
|
||||
<pre class="programlisting"><a href="http://pugixml.googlecode.com/files/pugixml-0.9.zip" target="_top">http://pugixml.googlecode.com/files/pugixml-0.9.zip</a>
|
||||
<a href="http://pugixml.googlecode.com/files/pugixml-0.9.tar.gz" target="_top">http://pugixml.googlecode.com/files/pugixml-0.9.tar.gz</a>
|
||||
<pre class="programlisting"><a href="http://pugixml.googlecode.com/files/pugixml-1.0.zip" target="_top">http://pugixml.googlecode.com/files/pugixml-1.0.zip</a>
|
||||
<a href="http://pugixml.googlecode.com/files/pugixml-1.0.tar.gz" target="_top">http://pugixml.googlecode.com/files/pugixml-1.0.tar.gz</a>
|
||||
</pre>
|
||||
<p>
|
||||
The distribution contains library source, documentation (the guide you're
|
||||
reading now and the manual) and some code examples. After downloading the
|
||||
distribution, install pugixml by extracting all files from the compressed
|
||||
archive.
|
||||
archive. The files have different line endings depending on the archive format
|
||||
- <code class="filename">.zip</code> archive has Windows line endings, <code class="filename">.tar.gz</code> archive has Unix line endings.
|
||||
Otherwise the files in both archives are identical.
|
||||
</p>
|
||||
<p>
|
||||
The complete pugixml source consists of four files - two source files, <code class="filename">pugixml.cpp</code> and
|
||||
<code class="filename">pugixpath.cpp</code>, and two header files, <code class="filename">pugixml.hpp</code> and <code class="filename">pugiconfig.hpp</code>. <code class="filename">pugixml.hpp</code> is
|
||||
the primary header which you need to include in order to use pugixml classes/functions.
|
||||
The complete pugixml source consists of three files - one source file, <code class="filename">pugixml.cpp</code>,
|
||||
and two header files, <code class="filename">pugixml.hpp</code> and <code class="filename">pugiconfig.hpp</code>. <code class="filename">pugixml.hpp</code> is the primary
|
||||
header which you need to include in order to use pugixml classes/functions.
|
||||
The rest of this guide assumes that <code class="filename">pugixml.hpp</code> is either in the current directory
|
||||
or in one of include directories of your projects, so that <code class="computeroutput"><span class="preprocessor">#include</span> <span class="string">"pugixml.hpp"</span></code>
|
||||
can find the header; however you can also use relative path (i.e. <code class="computeroutput"><span class="preprocessor">#include</span> <span class="string">"../libs/pugixml/src/pugixml.hpp"</span></code>)
|
||||
|
|
@ -94,13 +97,14 @@
|
|||
<span class="special"><</span><span class="identifier">xml</span><span class="special">/</span><span class="identifier">thirdparty</span><span class="special">/</span><span class="identifier">pugixml</span><span class="special">/</span><span class="identifier">src</span><span class="special">/</span><span class="identifier">pugixml</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>).
|
||||
</p>
|
||||
<p>
|
||||
The easiest way to build pugixml is to compile two source files, <code class="filename">pugixml.cpp</code> and
|
||||
<code class="filename">pugixpath.cpp</code>, along with the existing library/executable. This process depends
|
||||
on the method of building your application; for example, if you're using
|
||||
Microsoft Visual Studio<sup>[<a name="trademarks" href="#ftn.trademarks" class="footnote">1</a>]</sup>, Apple Xcode, Code::Blocks or any other IDE, just add
|
||||
<code class="filename">pugixml.cpp</code> and <code class="filename">pugixpath.cpp</code> to one of your projects. There are other building
|
||||
methods available, including building pugixml as a standalone static/shared
|
||||
library; read the manual for further information.
|
||||
The easiest way to build pugixml is to compile the source file, <code class="filename">pugixml.cpp</code>,
|
||||
along with the existing library/executable. This process depends on the method
|
||||
of building your application; for example, if you're using Microsoft Visual
|
||||
Studio<sup>[<a name="trademarks" href="#ftn.trademarks" class="footnote">1</a>]</sup>,
|
||||
Apple Xcode, Code::Blocks or any other IDE, just add <code class="filename">pugixml.cpp</code> to one of
|
||||
your projects. There are other building methods available, including building
|
||||
pugixml as a standalone static/shared library; <a href="manual/install.html#manual.install.building" target="_top">read
|
||||
the manual</a> for further information.
|
||||
</p>
|
||||
</div>
|
||||
<div class="section">
|
||||
|
|
@ -176,11 +180,10 @@
|
|||
<code class="computeroutput"><span class="identifier">xml_document</span></code> is the owner
|
||||
of the entire document structure; destroying the document destroys the whole
|
||||
tree. The interface of <code class="computeroutput"><span class="identifier">xml_document</span></code>
|
||||
consists of loading functions, saving functions and the interface of <code class="computeroutput"><span class="identifier">xml_node</span></code>, which allows for document inspection
|
||||
and/or modification. Note that while <code class="computeroutput"><span class="identifier">xml_document</span></code>
|
||||
is a sub-class of <code class="computeroutput"><span class="identifier">xml_node</span></code>,
|
||||
<code class="computeroutput"><span class="identifier">xml_node</span></code> is not a polymorphic
|
||||
type; the inheritance is only used to simplify usage.
|
||||
consists of loading functions, saving functions and the entire interface
|
||||
of <code class="computeroutput"><span class="identifier">xml_node</span></code>, which allows
|
||||
for document inspection and/or modification. Note that while <code class="computeroutput"><span class="identifier">xml_document</span></code> is a sub-class of <code class="computeroutput"><span class="identifier">xml_node</span></code>, <code class="computeroutput"><span class="identifier">xml_node</span></code>
|
||||
is not a polymorphic type; the inheritance is present only to simplify usage.
|
||||
</p>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">xml_node</span></code> is the handle to
|
||||
|
|
@ -208,8 +211,8 @@
|
|||
<code class="computeroutput"><span class="identifier">xml_attribute</span></code> is the handle
|
||||
to an XML attribute; it has the same semantics as <code class="computeroutput"><span class="identifier">xml_node</span></code>,
|
||||
i.e. there can be several <code class="computeroutput"><span class="identifier">xml_attribute</span></code>
|
||||
handles pointing to the same underlying object, there is a special null attribute
|
||||
value, which propagates to function results.
|
||||
handles pointing to the same underlying object and there is a special null
|
||||
attribute value, which propagates to function results.
|
||||
</p>
|
||||
<p>
|
||||
There are two choices of interface and internal representation when configuring
|
||||
|
|
@ -217,8 +220,8 @@
|
|||
UTF-16/32 (also called wchar_t) one. The choice is controlled via <code class="computeroutput"><span class="identifier">PUGIXML_WCHAR_MODE</span></code> define; you can set
|
||||
it via <code class="filename">pugiconfig.hpp</code> or via preprocessor options. All tree functions that
|
||||
work with strings work with either C-style null terminated strings or STL
|
||||
strings of the selected character type. Read the manual for additional information
|
||||
on Unicode interface.
|
||||
strings of the selected character type. <a href="manual/dom.html#manual.dom.unicode" target="_top">Read
|
||||
the manual</a> for additional information on Unicode interface.
|
||||
</p>
|
||||
</div>
|
||||
<div class="section">
|
||||
|
|
@ -601,13 +604,13 @@
|
|||
<p>
|
||||
</p>
|
||||
<p>
|
||||
Nodes and attributes do not exist outside of document tree, so you can't
|
||||
create them without adding them to some document. A node or attribute can
|
||||
be created at the end of node/attribute list or before/after some other node.
|
||||
All insertion functions return the handle to newly created object on success,
|
||||
and null handle on failure. Even if the operation fails (for example, if
|
||||
you're trying to add a child node to PCDATA node), the document remains in
|
||||
consistent state, but the requested node/attribute is not added.
|
||||
Nodes and attributes do not exist without a document tree, so you can't create
|
||||
them without adding them to some document. A node or attribute can be created
|
||||
at the end of node/attribute list or before/after some other node. All insertion
|
||||
functions return the handle to newly created object on success, and null
|
||||
handle on failure. Even if the operation fails (for example, if you're trying
|
||||
to add a child node to PCDATA node), the document remains in consistent state,
|
||||
but the requested node/attribute is not added.
|
||||
</p>
|
||||
<div class="caution"><table border="0" summary="Caution">
|
||||
<tr>
|
||||
|
|
@ -628,17 +631,14 @@
|
|||
|
||||
</p>
|
||||
<pre class="programlisting"><span class="comment">// add node with some name
|
||||
</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">node</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">append_child</span><span class="special">();</span>
|
||||
<span class="identifier">node</span><span class="special">.</span><span class="identifier">set_name</span><span class="special">(</span><span class="string">"node"</span><span class="special">);</span>
|
||||
</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">node</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">append_child</span><span class="special">(</span><span class="string">"node"</span><span class="special">);</span>
|
||||
|
||||
<span class="comment">// add description node with text child
|
||||
</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">descr</span> <span class="special">=</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">append_child</span><span class="special">();</span>
|
||||
<span class="identifier">descr</span><span class="special">.</span><span class="identifier">set_name</span><span class="special">(</span><span class="string">"description"</span><span class="special">);</span>
|
||||
</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">descr</span> <span class="special">=</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">append_child</span><span class="special">(</span><span class="string">"description"</span><span class="special">);</span>
|
||||
<span class="identifier">descr</span><span class="special">.</span><span class="identifier">append_child</span><span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">node_pcdata</span><span class="special">).</span><span class="identifier">set_value</span><span class="special">(</span><span class="string">"Simple node"</span><span class="special">);</span>
|
||||
|
||||
<span class="comment">// add param node before the description
|
||||
</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">param</span> <span class="special">=</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">insert_child_before</span><span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">node_element</span><span class="special">,</span> <span class="identifier">descr</span><span class="special">);</span>
|
||||
<span class="identifier">param</span><span class="special">.</span><span class="identifier">set_name</span><span class="special">(</span><span class="string">"param"</span><span class="special">);</span>
|
||||
</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">param</span> <span class="special">=</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">insert_child_before</span><span class="special">(</span><span class="string">"param"</span><span class="special">,</span> <span class="identifier">descr</span><span class="special">);</span>
|
||||
|
||||
<span class="comment">// add attributes to param node
|
||||
</span><span class="identifier">param</span><span class="special">.</span><span class="identifier">append_attribute</span><span class="special">(</span><span class="string">"name"</span><span class="special">)</span> <span class="special">=</span> <span class="string">"version"</span><span class="special">;</span>
|
||||
|
|
@ -647,7 +647,7 @@
|
|||
</pre>
|
||||
<p>
|
||||
</p>
|
||||
<a name="xml_node::remove_attribute"></a><a name="xml_node::remove_child"></a><p>
|
||||
<p>
|
||||
If you do not want your document to contain some node or attribute, you can
|
||||
remove it with <code class="computeroutput"><span class="identifier">remove_attribute</span></code>
|
||||
and <code class="computeroutput"><span class="identifier">remove_child</span></code> functions.
|
||||
|
|
@ -693,12 +693,12 @@
|
|||
encoding conversions.
|
||||
</p>
|
||||
<p>
|
||||
The node/attribute data is written to the destination properly formatted
|
||||
Before writing to the destination the node/attribute data is properly formatted
|
||||
according to the node type; all special XML symbols, such as < and &,
|
||||
are properly escaped. In order to guard against forgotten node/attribute
|
||||
names, empty node/attribute names are printed as <code class="computeroutput"><span class="string">":anonymous"</span></code>.
|
||||
For proper output, make sure all node and attribute names are set to meaningful
|
||||
values.
|
||||
For well-formed output, make sure all node and attribute names are set to
|
||||
meaningful values.
|
||||
</p>
|
||||
<p>
|
||||
If you want to save the whole document to a file, you can use the <code class="computeroutput"><span class="identifier">save_file</span></code> function, which returns <code class="computeroutput"><span class="keyword">true</span></code> on success. This is a simple example
|
||||
|
|
@ -713,11 +713,11 @@
|
|||
<p>
|
||||
</p>
|
||||
<p>
|
||||
For additional interoperability pugixml provides functions for saving document
|
||||
to any object which implements C++ std::ostream interface. This allows you
|
||||
to save documents to any standard C++ stream (i.e. file stream) or any third-party
|
||||
compliant implementation (i.e. Boost Iostreams). Most notably, this allows
|
||||
for easy debug output, since you can use <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span></code>
|
||||
To enhance interoperability pugixml provides functions for saving document
|
||||
to any object which implements C++ <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span></code>
|
||||
interface. This allows you to save documents to any standard C++ stream (i.e.
|
||||
file stream) or any third-party compliant implementation (i.e. Boost Iostreams).
|
||||
Most notably, this allows for easy debug output, since you can use <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span></code>
|
||||
stream as saving target. There are two functions, one works with narrow character
|
||||
streams, another handles wide character ones.
|
||||
</p>
|
||||
|
|
@ -763,11 +763,12 @@
|
|||
<p>
|
||||
</p>
|
||||
<p>
|
||||
While the previously described functions saved the whole document to the
|
||||
destination, it is easy to save a single subtree. Instead of calling <code class="computeroutput"><span class="identifier">xml_document</span><span class="special">::</span><span class="identifier">save</span></code>, just call <code class="computeroutput"><span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">print</span></code>
|
||||
function on the target node. You can save node contents to C++ IOstream object
|
||||
or custom writer in this way. Saving a subtree slightly differs from saving
|
||||
the whole document; read the manual for more information.
|
||||
While the previously described functions save the whole document to the destination,
|
||||
it is easy to save a single subtree. Instead of calling <code class="computeroutput"><span class="identifier">xml_document</span><span class="special">::</span><span class="identifier">save</span></code>,
|
||||
just call <code class="computeroutput"><span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">print</span></code> function on the target node. You
|
||||
can save node contents to C++ IOstream object or custom writer in this way.
|
||||
Saving a subtree slightly differs from saving the whole document; <a href="manual/saving.html#manual.saving.subtree" target="_top">read the manual</a> for
|
||||
more information.
|
||||
</p>
|
||||
</div>
|
||||
<div class="section">
|
||||
|
|
@ -819,16 +820,25 @@
|
|||
IN THE SOFTWARE.
|
||||
</p>
|
||||
</blockquote></div>
|
||||
<p>
|
||||
This means that you can freely use pugixml in your applications, both open-source
|
||||
and proprietary. If you use pugixml in a product, it is sufficient to add
|
||||
an acknowledgment like this to the product distribution:
|
||||
</p>
|
||||
<div class="blockquote"><blockquote class="blockquote"><p>
|
||||
This software is based on pugixml library (http://pugixml.org).<br>
|
||||
pugixml
|
||||
is Copyright (C) 2006-2010 Arseny Kapoulkine.
|
||||
</p></blockquote></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="footnotes">
|
||||
<br><hr width="100" align="left">
|
||||
<div class="footnote"><p><sup>[<a name="ftn.trademarks" href="#trademarks" class="para">1</a>] </sup>All trademarks used are properties of their
|
||||
respective owners.</p></div>
|
||||
<div class="footnote"><p><sup>[<a name="ftn.trademarks" href="#trademarks" class="para">1</a>] </sup>All trademarks used are properties of their respective owners.</p></div>
|
||||
</div>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"><p><small>Last revised: July 15, 2010 at 17:02:03 GMT</small></p></td>
|
||||
<td align="left"><p><small>Last revised: October 31, 2010 at 07:44:52 GMT</small></p></td>
|
||||
<td align="right"><div class="copyright-footer"></div></td>
|
||||
</tr></table>
|
||||
</body>
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue