diff options
| -rw-r--r-- | docs/manual.html | 191 | ||||
| -rw-r--r-- | docs/manual/access.html | 721 | ||||
| -rw-r--r-- | docs/manual/apiref.html | 1151 | ||||
| -rw-r--r-- | docs/manual/changes.html | 574 | ||||
| -rw-r--r-- | docs/manual/dom.html | 649 | ||||
| -rw-r--r-- | docs/manual/install.html | 445 | ||||
| -rw-r--r-- | docs/manual/loading.html | 840 | ||||
| -rw-r--r-- | docs/manual/modify.html | 541 | ||||
| -rw-r--r-- | docs/manual/saving.html | 473 | ||||
| -rw-r--r-- | docs/manual/toc.html | 130 | ||||
| -rw-r--r-- | docs/manual/xpath.html | 494 | ||||
| -rw-r--r-- | docs/quickstart.html | 828 |
12 files changed, 7037 insertions, 0 deletions
diff --git a/docs/manual.html b/docs/manual.html new file mode 100644 index 0000000..940b1cc --- /dev/null +++ b/docs/manual.html @@ -0,0 +1,191 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>pugixml 0.9</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="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 | + <b>Overview</b> | + <a href="manual/install.html">Installation</a> | + Document: + <a href="manual/dom.html">Object model</a> · <a href="manual/loading.html">Loading</a> · <a href="manual/access.html">Accessing</a> · <a href="manual/modify.html">Modifying</a> · <a href="manual/saving.html">Saving</a> | + <a href="manual/xpath.html">XPath</a> | + <a href="manual/apiref.html">API Reference</a> | + <a href="manual/toc.html">Table of Contents</a> +</td> +<td width="*" align="right"><div class="spirit-nav"><a accesskey="n" href="manual/install.html"><img src="images/next.png" alt="Next"></a></div></td> +</tr></table> +<hr> +<div class="book"><div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="manual.overview"></a><a class="link" href="manual.html#manual.overview" title="Overview"> Overview</a> +</h2></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="manual.html#manual.overview.introduction"> Introduction</a></span></dt> +<dt><span class="section"><a href="manual.html#manual.overview.feedback"> Feedback</a></span></dt> +<dt><span class="section"><a href="manual.html#manual.overview.thanks"> Acknowledgments</a></span></dt> +<dt><span class="section"><a href="manual.html#manual.overview.license"> License</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<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. + </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. + </p> +<p> + This is the complete manual for pugixml, which describes all features of + the library in detail. If you want to start writing code as quickly as possible, + you are advised to <a href="quickstart.html" target="_top">read the quick start guide + first</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> + No documentation is perfect, neither is this one. If you encounter a description + that is unclear, please file an issue as described in <a class="xref" href="manual.html#manual.overview.feedback" title="Feedback"> Feedback</a>. + Also if you can spare the time for a full proof-reading, including spelling + and grammar, that would be great! Please <a class="link" href="manual.html#email">send me + an e-mail</a>; as a token of appreciation, your name will be included + into the <a class="link" href="manual.html#manual.overview.thanks" title="Acknowledgments">corresponding section</a> + of this documentation. + </p></td></tr> +</table></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.overview.feedback"></a><a class="link" href="manual.html#manual.overview.feedback" title="Feedback"> Feedback</a> +</h3></div></div></div> +<p> + If you believe you've found a bug in pugixml (bugs include compilation problems + (errors/warnings), crashes, performance degradation and incorrect behavior), + please file an issue via <a href="http://code.google.com/p/pugixml/issues/entry" target="_top">issue + submission form</a>. Be sure to include the relevant information so that + the bug can be reproduced: the version of pugixml, compiler version and target + architecture, the code that uses pugixml and exhibits the bug, etc. + </p> +<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. + </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. + </p> +<a name="email"></a><p> + If filing an issue is not possible due to privacy or other concerns, you + can contact pugixml author by e-mail directly: <a href="mailto:arseny.kapoulkine@gmail.com" target="_top">arseny.kapoulkine@gmail.com</a>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.overview.thanks"></a><a class="link" href="manual.html#manual.overview.thanks" title="Acknowledgments"> Acknowledgments</a> +</h3></div></div></div> +<p> + pugixml could not be developed without the help from many people; some of + them are listed in this section. If you've played a part in pugixml development + and you can not find yourself on this list, I'm truly sorry; please <a class="link" href="manual.html#email">send me an e-mail</a> so I can fix this. + </p> +<p> + Thanks to <span class="bold"><strong>Kristen Wegner</strong></span> for pugxml parser, + which was used as a basis for pugixml. + </p> +<p> + Thanks to <span class="bold"><strong>Neville Franks</strong></span> for contributions + to pugxml parser. + </p> +<p> + Thanks to <span class="bold"><strong>Artyom Palvelev</strong></span> for suggesting + a lazy gap contraction approach. + </p> +<p> + Thanks to <span class="bold"><strong>Vyacheslav Egorov</strong></span> for documentation + proofreading. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.overview.license"></a><a class="link" href="manual.html#manual.overview.license" title="License"> License</a> +</h3></div></div></div> +<p> + The pugixml library is distributed under the MIT license: + </p> +<div class="blockquote"><blockquote class="blockquote"> +<p> + Copyright (c) 2006-2010 Arseny Kapoulkine + </p> +<p> + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the Software + is furnished to do so, subject to the following conditions: + </p> +<p> + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + </p> +<p> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS + IN THE SOFTWARE. + </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 11, 2010 at 16:10:06 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 | + <b>Overview</b> | + <a href="manual/install.html">Installation</a> | + Document: + <a href="manual/dom.html">Object model</a> · <a href="manual/loading.html">Loading</a> · <a href="manual/access.html">Accessing</a> · <a href="manual/modify.html">Modifying</a> · <a href="manual/saving.html">Saving</a> | + <a href="manual/xpath.html">XPath</a> | + <a href="manual/apiref.html">API Reference</a> | + <a href="manual/toc.html">Table of Contents</a> +</td> +<td width="*" align="right"><div class="spirit-nav"><a accesskey="n" href="manual/install.html"><img src="images/next.png" alt="Next"></a></div></td> +</tr></table> +</body> +</html> diff --git a/docs/manual/access.html b/docs/manual/access.html new file mode 100644 index 0000000..4581583 --- /dev/null +++ b/docs/manual/access.html @@ -0,0 +1,721 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<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="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 | + <a href="../manual.html">Overview</a> | + <a href="install.html">Installation</a> | + Document: + <a href="dom.html">Object model</a> · <a href="loading.html">Loading</a> · <b>Accessing</b> · <a href="modify.html">Modifying</a> · <a href="saving.html">Saving</a> | + <a href="xpath.html">XPath</a> | + <a href="apiref.html">API Reference</a> | + <a href="toc.html">Table of Contents</a> +</td> +<td width="*" align="right"><div class="spirit-nav"> +<a accesskey="p" href="loading.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../manual.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../manual.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="modify.html"><img src="../images/next.png" alt="Next"></a> +</div></td> +</tr></table> +<hr> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="manual.access"></a><a class="link" href="access.html" title="Accessing document data"> Accessing document data</a> +</h2></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="access.html#manual.access.basic"> Basic traversal functions</a></span></dt> +<dt><span class="section"><a href="access.html#manual.access.nodedata"> Getting node data</a></span></dt> +<dt><span class="section"><a href="access.html#manual.access.attrdata"> Getting attribute data</a></span></dt> +<dt><span class="section"><a href="access.html#manual.access.contents"> Contents-based traversal functions</a></span></dt> +<dt><span class="section"><a href="access.html#manual.access.iterators"> Traversing node/attribute lists + via iterators</a></span></dt> +<dt><span class="section"><a href="access.html#manual.access.walker"> Recursive traversal with xml_tree_walker</a></span></dt> +<dt><span class="section"><a href="access.html#manual.access.predicate"> Searching for nodes/attributes + with predicates</a></span></dt> +<dt><span class="section"><a href="access.html#manual.access.misc"> Miscellaneous functions</a></span></dt> +</dl></div> +<p> + pugixml features an extensive interface for getting various types of data from + the document and for traversing the document. This section provides documentation + for all such functions that do not modify the tree except for XPath-related + functions; see <a class="xref" href="xpath.html" title="XPath"> XPath</a> for XPath reference. As discussed in <a class="xref" href="dom.html#manual.dom.cpp" title="C++ interface"> C++ interface</a>, + there are two types of handles to tree data - <a class="link" href="dom.html#xml_node">xml_node</a> + and <a class="link" href="dom.html#xml_attribute">xml_attribute</a>. The handles have special + null (empty) values which propagate through various functions and thus are + useful for writing more concise code; see <a class="link" href="dom.html#node_null">this description</a> + for details. The documentation in this section will explicitly state the results + of all function in case of null inputs. + </p> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.access.basic"></a><a class="link" href="access.html#manual.access.basic" title="Basic traversal functions"> Basic traversal functions</a> +</h3></div></div></div> +<a name="xml_node::parent"></a><a name="xml_node::first_child"></a><a name="xml_node::last_child"></a><a name="xml_node::next_sibling"></a><a name="xml_node::previous_sibling"></a><a name="xml_node::first_attribute"></a><a name="xml_node::last_attribute"></a><a name="xml_attribute::next_attribute"></a><a name="xml_attribute::previous_attribute"></a><p> + The internal representation of the document is a tree, where each node has + a list of child nodes (the order of children corresponds to their order in + the XML representation), and additionally element nodes have a list of attributes, + which is also ordered. Several functions are provided in order to let you + get from one node in the tree to the other. These functions roughly correspond + to the internal representation, and thus are usually building blocks for + other methods of traversing (i.e. XPath traversals are based on these functions). + </p> +<pre class="programlisting"><span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">parent</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">first_child</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">last_child</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">next_sibling</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">previous_sibling</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + +<span class="identifier">xml_attribute</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">first_attribute</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="identifier">xml_attribute</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">last_attribute</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="identifier">xml_attribute</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">next_attribute</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="identifier">xml_attribute</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">previous_attribute</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +</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> + 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>, + calling <code class="computeroutput"><span class="identifier">next_sibling</span></code> for + a handle that points to <code class="computeroutput"><span class="special"><</span><span class="identifier">b</span><span class="special">/></span></code> + results in a handle pointing to <code class="computeroutput"><span class="special"><</span><span class="identifier">c</span><span class="special">/></span></code>, + and calling <code class="computeroutput"><span class="identifier">previous_sibling</span></code> + 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. + </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> + Because of memory consumption reasons, attributes do not have a link to + their parent nodes. Thus there is no <code class="computeroutput"><span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">parent</span><span class="special">()</span></code> function. + </p></td></tr> +</table></div> +<p> + 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. + </p> +<p> + With these functions, you can iterate through all child nodes and display + all attributes like this (<a href="../samples/traverse_base.cpp" target="_top">samples/traverse_base.cpp</a>): + </p> +<p> + +</p> +<pre class="programlisting"><span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">tool</span> <span class="special">=</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">first_child</span><span class="special">();</span> <span class="identifier">tool</span><span class="special">;</span> <span class="identifier">tool</span> <span class="special">=</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">next_sibling</span><span class="special">())</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">"Tool:"</span><span class="special">;</span> + + <span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_attribute</span> <span class="identifier">attr</span> <span class="special">=</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">first_attribute</span><span class="special">();</span> <span class="identifier">attr</span><span class="special">;</span> <span class="identifier">attr</span> <span class="special">=</span> <span class="identifier">attr</span><span class="special">.</span><span class="identifier">next_attribute</span><span class="special">())</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">" "</span> <span class="special"><<</span> <span class="identifier">attr</span><span class="special">.</span><span class="identifier">name</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"="</span> <span class="special"><<</span> <span class="identifier">attr</span><span class="special">.</span><span class="identifier">value</span><span class="special">();</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">endl</span><span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.access.nodedata"></a><a class="link" href="access.html#manual.access.nodedata" title="Getting node data"> Getting node data</a> +</h3></div></div></div> +<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> + 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> +<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">name</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">value</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<p> + In case node does not have a name or value or if the node handle is null, + both functions return empty strings - they never return null pointers. + </p> +<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: + </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>. + 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. + </p> +<p> + There is an example of using some of these functions <a class="link" href="access.html#code_traverse_base_data">at + the end of the next section</a>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.access.attrdata"></a><a class="link" href="access.html#manual.access.attrdata" title="Getting attribute data"> Getting attribute data</a> +</h3></div></div></div> +<a name="xml_attribute::name"></a><a name="xml_attribute::value"></a><p> + All attributes have name and value, both of which are strings (value may + be empty). There are two corresponding accessors, like for <code class="computeroutput"><span class="identifier">xml_node</span></code>: + </p> +<pre class="programlisting"><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">name</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_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. + </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: + </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> +<span class="keyword">double</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">as_double</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="keyword">float</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">as_float</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="keyword">bool</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">as_bool</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<p> + <code class="computeroutput"><span class="identifier">as_int</span></code>, <code class="computeroutput"><span class="identifier">as_uint</span></code>, + <code class="computeroutput"><span class="identifier">as_double</span></code> and <code class="computeroutput"><span class="identifier">as_float</span></code> convert attribute values to numbers. + If attribute handle is null or attribute value is empty, <code class="computeroutput"><span class="number">0</span></code> + is returned. Otherwise, all leading whitespace characters are truncated, + and the remaining string is parsed as a decimal number (<code class="computeroutput"><span class="identifier">as_int</span></code> + or <code class="computeroutput"><span class="identifier">as_uint</span></code>) or as a floating + point number in either decimal or scientific form (<code class="computeroutput"><span class="identifier">as_double</span></code> + or <code class="computeroutput"><span class="identifier">as_float</span></code>). Any extra characters + are silently discarded, i.e. <code class="computeroutput"><span class="identifier">as_int</span></code> + will return <code class="computeroutput"><span class="number">1</span></code> for string <code class="computeroutput"><span class="string">"1abc"</span></code>. + </p> +<p> + In case the input string contains a number that is out of the target numeric + range, the result is undefined. + </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> + Number conversion functions depend on current C locale as set with <code class="computeroutput"><span class="identifier">setlocale</span></code>, so may return unexpected results + if the locale is different from <code class="computeroutput"><span class="string">"C"</span></code>. + </p></td></tr> +</table></div> +<p> + <code class="computeroutput"><span class="identifier">as_bool</span></code> converts attribute + 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> + <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 + as <code class="computeroutput"><span class="keyword">true</span></code>, while strings like + <code class="computeroutput"><span class="string">"false"</span></code> and <code class="computeroutput"><span class="string">"no"</span></code> are recognized as <code class="computeroutput"><span class="keyword">false</span></code>. For more complex matching you'll have + to write your own function. + </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> + There are no portable 64-bit types in C++, so there is no corresponding + conversion function. If your platform has a 64-bit integer, you can easily + write a conversion function yourself. + </p></td></tr> +</table></div> +<a name="code_traverse_base_data"></a><p> + This is an example of using these functions, along with node data retrieval + ones (<a href="../samples/traverse_base.cpp" target="_top">samples/traverse_base.cpp</a>): + </p> +<p> + +</p> +<pre class="programlisting"><span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">tool</span> <span class="special">=</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">child</span><span class="special">(</span><span class="string">"Tool"</span><span class="special">);</span> <span class="identifier">tool</span><span class="special">;</span> <span class="identifier">tool</span> <span class="special">=</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">next_sibling</span><span class="special">(</span><span class="string">"Tool"</span><span class="special">))</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">"Tool "</span> <span class="special"><<</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"Filename"</span><span class="special">).</span><span class="identifier">value</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">": AllowRemote "</span> <span class="special"><<</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"AllowRemote"</span><span class="special">).</span><span class="identifier">as_bool</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">", Timeout "</span> <span class="special"><<</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"Timeout"</span><span class="special">).</span><span class="identifier">as_int</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">", Description '"</span> <span class="special"><<</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">child_value</span><span class="special">(</span><span class="string">"Description"</span><span class="special">)</span> <span class="special"><<</span> <span class="string">"'\n"</span><span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.access.contents"></a><a class="link" href="access.html#manual.access.contents" title="Contents-based traversal functions"> Contents-based traversal functions</a> +</h3></div></div></div> +<a name="xml_node::child"></a><a name="xml_node::attribute"></a><a name="xml_node::next_sibling_name"></a><a name="xml_node::previous_sibling_name"></a><p> + Since a lot of document traversal consists of finding the node/attribute + with the correct name, there are special functions for that purpose: + </p> +<pre class="programlisting"><span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">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="keyword">const</span><span class="special">;</span> +<span class="identifier">xml_attribute</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">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="keyword">const</span><span class="special">;</span> +<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">next_sibling</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> +<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">previous_sibling</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</span></code> and <code class="computeroutput"><span class="identifier">attribute</span></code> + return the first child/attribute with the specified name; <code class="computeroutput"><span class="identifier">next_sibling</span></code> + and <code class="computeroutput"><span class="identifier">previous_sibling</span></code> return + the first sibling in the corresponding direction with the specified name. + All string comparisons are case-sensitive. In case the node handle is null + or there is no node/attribute with the specified name, null handle is returned. + </p> +<p> + <code class="computeroutput"><span class="identifier">child</span></code> and <code class="computeroutput"><span class="identifier">next_sibling</span></code> + functions can be used together to loop through all child nodes with the desired + name like this: + </p> +<pre class="programlisting"><span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">tool</span> <span class="special">=</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">child</span><span class="special">(</span><span class="string">"Tool"</span><span class="special">);</span> <span class="identifier">tool</span><span class="special">;</span> <span class="identifier">tool</span> <span class="special">=</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">next_sibling</span><span class="special">(</span><span class="string">"Tool"</span><span class="special">))</span> +</pre> +<a name="xml_node::find_child_by_attribute"></a><p> + Occasionally the needed node is specified not by the unique name but instead + by the value of some attribute; for example, it is common to have node collections + with each node having a unique id: <code class="computeroutput"><span class="special"><</span><span class="identifier">group</span><span class="special">><</span><span class="identifier">item</span> <span class="identifier">id</span><span class="special">=</span><span class="string">"1"</span><span class="special">/></span> <span class="special"><</span><span class="identifier">item</span> <span class="identifier">id</span><span class="special">=</span><span class="string">"2"</span><span class="special">/></</span><span class="identifier">group</span><span class="special">></span></code>. There are two functions for finding + child nodes based on the attribute values: + </p> +<pre class="programlisting"><span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">find_child_by_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="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">attr_name</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">attr_value</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">find_child_by_attribute</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">attr_name</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">attr_value</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<p> + The three-argument function returns the first child node with the specified + name which has an attribute with the specified name/value; the two-argument + function skips the name test for the node, which can be useful for searching + in heterogeneous collections. If the node handle is null or if no node is + found, null handle is returned. All string comparisons are case-sensitive. + </p> +<p> + In all of the above functions, all arguments have to be valid strings; passing + null pointers results in undefined behavior. + </p> +<p> + This is an example of using these functions (<a href="../samples/traverse_base.cpp" target="_top">samples/traverse_base.cpp</a>): + </p> +<p> + +</p> +<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Tool for *.dae generation: "</span> <span class="special"><<</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">find_child_by_attribute</span><span class="special">(</span><span class="string">"Tool"</span><span class="special">,</span> <span class="string">"OutputFileMasks"</span><span class="special">,</span> <span class="string">"*.dae"</span><span class="special">).</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"Filename"</span><span class="special">).</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"\n"</span><span class="special">;</span> + +<span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">tool</span> <span class="special">=</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">child</span><span class="special">(</span><span class="string">"Tool"</span><span class="special">);</span> <span class="identifier">tool</span><span class="special">;</span> <span class="identifier">tool</span> <span class="special">=</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">next_sibling</span><span class="special">(</span><span class="string">"Tool"</span><span class="special">))</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">"Tool "</span> <span class="special"><<</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"Filename"</span><span class="special">).</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"\n"</span><span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.access.iterators"></a><a class="link" href="access.html#manual.access.iterators" title="Traversing node/attribute lists via iterators"> Traversing node/attribute lists + via iterators</a> +</h3></div></div></div> +<a name="xml_node_iterator"></a><a name="xml_attribute_iterator"></a><a name="xml_node::begin"></a><a name="xml_node::end"></a><a name="xml_node::attributes_begin"></a><a name="xml_node::attributes_end"></a><p> + Child node lists and attribute lists are simply double-linked lists; while + you can use <code class="computeroutput"><span class="identifier">previous_sibling</span></code>/<code class="computeroutput"><span class="identifier">next_sibling</span></code> and other such functions for + iteration, pugixml additionally provides node and attribute iterators, so + that you can treat nodes as containers of other nodes or attributes: + </p> +<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">xml_node_iterator</span><span class="special">;</span> +<span class="keyword">class</span> <span class="identifier">xml_attribute_iterator</span><span class="special">;</span> + +<span class="keyword">typedef</span> <span class="identifier">xml_node_iterator</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">iterator</span><span class="special">;</span> +<span class="identifier">iterator</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">begin</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="identifier">iterator</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">end</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + +<span class="keyword">typedef</span> <span class="identifier">xml_attribute_iterator</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">attribute_iterator</span><span class="special">;</span> +<span class="identifier">attribute_iterator</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">attributes_begin</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="identifier">attribute_iterator</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">attributes_end</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<p> + <code class="computeroutput"><span class="identifier">begin</span></code> and <code class="computeroutput"><span class="identifier">attributes_begin</span></code> + return iterators that point to the first node/attribute, respectively; <code class="computeroutput"><span class="identifier">end</span></code> and <code class="computeroutput"><span class="identifier">attributes_end</span></code> + 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>. + 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> +<p> + <code class="computeroutput"><span class="identifier">begin</span></code> and <code class="computeroutput"><span class="identifier">end</span></code> + return equal iterators if called on null node; such iterators can't be dereferenced. + <code class="computeroutput"><span class="identifier">attributes_begin</span></code> and <code class="computeroutput"><span class="identifier">attributes_end</span></code> behave the same way. For + correct iterator usage this means that child node/attribute collections of + null nodes appear to be empty. + </p> +<p> + Both types of iterators have bidirectional iterator semantics (i.e. they + can be incremented and decremented, but efficient random access is not supported) + and support all usual iterator operations - comparison, dereference, etc. + The iterators are invalidated if the node/attribute objects they're pointing + to are removed from the tree; adding nodes/attributes does not invalidate + any iterators. + </p> +<p> + Here is an example of using iterators for document traversal (<a href="../samples/traverse_iter.cpp" target="_top">samples/traverse_iter.cpp</a>): + </p> +<p> + +</p> +<pre class="programlisting"><span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node_iterator</span> <span class="identifier">it</span> <span class="special">=</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">begin</span><span class="special">();</span> <span class="identifier">it</span> <span class="special">!=</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">end</span><span class="special">();</span> <span class="special">++</span><span class="identifier">it</span><span class="special">)</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">"Tool:"</span><span class="special">;</span> + + <span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_attribute_iterator</span> <span class="identifier">ait</span> <span class="special">=</span> <span class="identifier">it</span><span class="special">-></span><span class="identifier">attributes_begin</span><span class="special">();</span> <span class="identifier">ait</span> <span class="special">!=</span> <span class="identifier">it</span><span class="special">-></span><span class="identifier">attributes_end</span><span class="special">();</span> <span class="special">++</span><span class="identifier">ait</span><span class="special">)</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">" "</span> <span class="special"><<</span> <span class="identifier">ait</span><span class="special">-></span><span class="identifier">name</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"="</span> <span class="special"><<</span> <span class="identifier">ait</span><span class="special">-></span><span class="identifier">value</span><span class="special">();</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">endl</span><span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + </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> + Node and attribute iterators are somewhere in the middle between const + and non-const iterators. While dereference operation yields a non-constant + reference to the object, so that you can use it for tree modification operations, + modifying this reference by assignment - i.e. passing iterators to a function + like <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">sort</span></code> - will not give expected results, + as assignment modifies local handle that's stored in the iterator. + </p></td></tr> +</table></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.access.walker"></a><a class="link" href="access.html#manual.access.walker" title="Recursive traversal with xml_tree_walker"> Recursive traversal with xml_tree_walker</a> +</h3></div></div></div> +<a name="xml_tree_walker"></a><p> + The methods described above allow traversal of immediate children of some + node; if you want to do a deep tree traversal, you'll have to do it via a + recursive function or some equivalent method. However, pugixml provides a + helper for depth-first traversal of a subtree. In order to use it, you have + to implement <code class="computeroutput"><span class="identifier">xml_tree_walker</span></code> + interface and to call <code class="computeroutput"><span class="identifier">traverse</span></code> + function: + </p> +<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">xml_tree_walker</span> +<span class="special">{</span> +<span class="keyword">public</span><span class="special">:</span> + <span class="keyword">virtual</span> <span class="keyword">bool</span> <span class="identifier">begin</span><span class="special">(</span><span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">node</span><span class="special">);</span> + <span class="keyword">virtual</span> <span class="keyword">bool</span> <span class="identifier">for_each</span><span class="special">(</span><span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">node</span><span class="special">)</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> + <span class="keyword">virtual</span> <span class="keyword">bool</span> <span class="identifier">end</span><span class="special">(</span><span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">node</span><span class="special">);</span> + + <span class="keyword">int</span> <span class="identifier">depth</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="special">};</span> + +<span class="keyword">bool</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">traverse</span><span class="special">(</span><span class="identifier">xml_tree_walker</span><span class="special">&</span> <span class="identifier">walker</span><span class="special">);</span> +</pre> +<a name="xml_tree_walker::begin"></a><a name="xml_tree_walker::for_each"></a><a name="xml_tree_walker::end"></a><a name="xml_node::traverse"></a><p> + The traversal is launched by calling <code class="computeroutput"><span class="identifier">traverse</span></code> + function on traversal root and proceeds as follows: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + First, <code class="computeroutput"><span class="identifier">begin</span></code> function + is called with traversal root as its argument. + </li> +<li class="listitem"> + Then, <code class="computeroutput"><span class="identifier">for_each</span></code> function + is called for all nodes in the traversal subtree in depth first order, + excluding the traversal root. Node is passed as an argument. + </li> +<li class="listitem"> + Finally, <code class="computeroutput"><span class="identifier">end</span></code> function + is called with traversal root as its argument. + </li> +</ul></div> +<p> + If <code class="computeroutput"><span class="identifier">begin</span></code>, <code class="computeroutput"><span class="identifier">end</span></code> + or any of the <code class="computeroutput"><span class="identifier">for_each</span></code> calls + return <code class="computeroutput"><span class="keyword">false</span></code>, the traversal + is terminated and <code class="computeroutput"><span class="keyword">false</span></code> is returned + as the traversal result; otherwise, the traversal results in <code class="computeroutput"><span class="keyword">true</span></code>. Note that you don't have to override + <code class="computeroutput"><span class="identifier">begin</span></code> or <code class="computeroutput"><span class="identifier">end</span></code> + functions; their default implementations return <code class="computeroutput"><span class="keyword">true</span></code>. + </p> +<a name="xml_tree_walker::depth"></a><p> + You can get the node's depth relative to the traversal root at any point + by calling <code class="computeroutput"><span class="identifier">depth</span></code> function. + It returns <code class="computeroutput"><span class="special">-</span><span class="number">1</span></code> + if called from <code class="computeroutput"><span class="identifier">begin</span></code>/<code class="computeroutput"><span class="identifier">end</span></code>, and returns 0-based depth if called + from <code class="computeroutput"><span class="identifier">for_each</span></code> - depth is + 0 for all children of the traversal root, 1 for all grandchildren and so + on. + </p> +<p> + This is an example of traversing tree hierarchy with xml_tree_walker (<a href="../samples/traverse_walker.cpp" target="_top">samples/traverse_walker.cpp</a>): + </p> +<p> + +</p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">simple_walker</span><span class="special">:</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_tree_walker</span> +<span class="special">{</span> + <span class="keyword">virtual</span> <span class="keyword">bool</span> <span class="identifier">for_each</span><span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">node</span><span class="special">)</span> + <span class="special">{</span> + <span class="keyword">for</span> <span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special"><</span> <span class="identifier">depth</span><span class="special">();</span> <span class="special">++</span><span class="identifier">i</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">" "</span><span class="special">;</span> <span class="comment">// indentation +</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">node_types</span><span class="special">[</span><span class="identifier">node</span><span class="special">.</span><span class="identifier">type</span><span class="special">()]</span> <span class="special"><<</span> <span class="string">": name='"</span> <span class="special"><<</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">name</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"', value='"</span> <span class="special"><<</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"'\n"</span><span class="special">;</span> + + <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> <span class="comment">// continue traversal +</span> <span class="special">}</span> +<span class="special">};</span> +</pre> +<p> + </p> +<p> + +</p> +<pre class="programlisting"><span class="identifier">simple_walker</span> <span class="identifier">walker</span><span class="special">;</span> +<span class="identifier">doc</span><span class="special">.</span><span class="identifier">traverse</span><span class="special">(</span><span class="identifier">walker</span><span class="special">);</span> +</pre> +<p> + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.access.predicate"></a><a class="link" href="access.html#manual.access.predicate" title="Searching for nodes/attributes with predicates"> Searching for nodes/attributes + with predicates</a> +</h3></div></div></div> +<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, + you can make a predicate and call one of <code class="computeroutput"><span class="identifier">find_</span></code> + functions: + </p> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Predicate</span><span class="special">></span> <span class="identifier">xml_attribute</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">find_attribute</span><span class="special">(</span><span class="identifier">Predicate</span> <span class="identifier">pred</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Predicate</span><span class="special">></span> <span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">find_child</span><span class="special">(</span><span class="identifier">Predicate</span> <span class="identifier">pred</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Predicate</span><span class="special">></span> <span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">find_node</span><span class="special">(</span><span class="identifier">Predicate</span> <span class="identifier">pred</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<p> + The predicate should be either a plain function or a function object which + accepts one argument of type <code class="computeroutput"><span class="identifier">xml_attribute</span></code> + (for <code class="computeroutput"><span class="identifier">find_attribute</span></code>) or + <code class="computeroutput"><span class="identifier">xml_node</span></code> (for <code class="computeroutput"><span class="identifier">find_child</span></code> and <code class="computeroutput"><span class="identifier">find_node</span></code>), + and returns <code class="computeroutput"><span class="keyword">bool</span></code>. The predicate + is never called with null handle as an argument. + </p> +<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 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 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 + <code class="computeroutput"><span class="keyword">false</span></code> for all nodes or if subtree + was empty, null node is returned. + </p> +<p> + This is an example of using predicate-based functions (<a href="../samples/traverse_predicate.cpp" target="_top">samples/traverse_predicate.cpp</a>): + </p> +<p> + +</p> +<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">small_timeout</span><span class="special">(</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="special">{</span> + <span class="keyword">return</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"Timeout"</span><span class="special">).</span><span class="identifier">as_int</span><span class="special">()</span> <span class="special"><</span> <span class="number">20</span><span class="special">;</span> +<span class="special">}</span> + +<span class="keyword">struct</span> <span class="identifier">allow_remote_predicate</span> +<span class="special">{</span> + <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_attribute</span> <span class="identifier">attr</span><span class="special">)</span> <span class="keyword">const</span> + <span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">strcmp</span><span class="special">(</span><span class="identifier">attr</span><span class="special">.</span><span class="identifier">name</span><span class="special">(),</span> <span class="string">"AllowRemote"</span><span class="special">)</span> <span class="special">==</span> <span class="number">0</span><span class="special">;</span> + <span class="special">}</span> + + <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">()(</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="keyword">const</span> + <span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"AllowRemote"</span><span class="special">).</span><span class="identifier">as_bool</span><span class="special">();</span> + <span class="special">}</span> +<span class="special">};</span> +</pre> +<p> + </p> +<p> + +</p> +<pre class="programlisting"><span class="comment">// Find child via predicate (looks for direct children only) +</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">find_child</span><span class="special">(</span><span class="identifier">allow_remote_predicate</span><span class="special">()).</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"Filename"</span><span class="special">).</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> + +<span class="comment">// Find node via predicate (looks for all descendants in depth-first order) +</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">find_node</span><span class="special">(</span><span class="identifier">allow_remote_predicate</span><span class="special">()).</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"Filename"</span><span class="special">).</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> + +<span class="comment">// Find attribute via predicate +</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">last_child</span><span class="special">().</span><span class="identifier">find_attribute</span><span class="special">(</span><span class="identifier">allow_remote_predicate</span><span class="special">()).</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> + +<span class="comment">// We can use simple functions instead of function objects +</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">find_child</span><span class="special">(</span><span class="identifier">small_timeout</span><span class="special">).</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"Filename"</span><span class="special">).</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> +</pre> +<p> + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.access.misc"></a><a class="link" href="access.html#manual.access.misc" title="Miscellaneous functions"> Miscellaneous functions</a> +</h3></div></div></div> +<a name="xml_node::root"></a><p> + If you need to get the document root of some node, you can use the following + function: + </p> +<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>, + 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. + </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 + handling facility is needed. There are two functions, for getting node path + and for converting path to a node: + </p> +<pre class="programlisting"><span class="identifier">string_t</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">path</span><span class="special">(</span><span class="identifier">char_t</span> <span class="identifier">delimiter</span> <span class="special">=</span> <span class="char">'/'</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">first_element_by_path</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">path</span><span class="special">,</span> <span class="identifier">char_t</span> <span class="identifier">delimiter</span> <span class="special">=</span> <span class="char">'/'</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<p> + Node paths consist of node names, separated with a delimiter (which is <code class="computeroutput"><span class="special">/</span></code> by default); also paths can contain self + (<code class="computeroutput"><span class="special">.</span></code>) and parent (<code class="computeroutput"><span class="special">..</span></code>) pseudo-names, so that this is a valid + path: <code class="computeroutput"><span class="string">"../../foo/./bar"</span></code>. + <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>, + 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> + results in node <code class="computeroutput"><span class="special"><</span><span class="identifier">b</span><span class="special">/></span></code>; calling <code class="computeroutput"><span class="identifier">first_element_by_path</span></code> + for node <code class="computeroutput"><span class="special"><</span><span class="identifier">a</span><span class="special">/></span></code> with path <code class="computeroutput"><span class="string">"../a/./b/../."</span></code> + results in node <code class="computeroutput"><span class="special"><</span><span class="identifier">a</span><span class="special">/></span></code>; calling <code class="computeroutput"><span class="identifier">first_element_by_path</span></code> + with path <code class="computeroutput"><span class="string">"/a"</span></code> results + in node <code class="computeroutput"><span class="special"><</span><span class="identifier">a</span><span class="special">/></span></code> for any node. + </p> +<p> + In case path component is ambiguous (if there are two nodes with given name), + the first one is selected; paths are not guaranteed to uniquely identify + nodes in a document. If any component of a path is not found, the result + of <code class="computeroutput"><span class="identifier">first_element_by_path</span></code> + is null node; also <code class="computeroutput"><span class="identifier">first_element_by_path</span></code> + returns null node for null nodes, in which case the path does not matter. + <code class="computeroutput"><span class="identifier">path</span></code> returns an empty string + for null nodes. + </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> + <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> + is defined. + </p></td></tr> +</table></div> +<a name="xml_node::offset_debug"></a><p> + pugixml does not record row/column information for nodes upon parsing for + efficiency reasons. However, if the node has not changed in a significant + way since parsing (the name/value are not changed, and the node itself is + the original one, i.e. it was not deleted from the tree and re-added later), + it is possible to get the offset from the beginning of XML buffer: + </p> +<pre class="programlisting"><span class="identifier">ptrdiff_t</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">offset_debug</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<p> + 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> + units. For more information on parsing offsets, see <a class="link" href="loading.html#xml_parse_result::offset">parsing + error handling documentation</a>. + </p> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2010 Arseny Kapoulkine<p> + Distributed under the MIT License + </p> +</div></td> +</tr></table> +<hr> +<table width="100%"><tr> +<td>pugixml 0.9 manual | + <a href="../manual.html">Overview</a> | + <a href="install.html">Installation</a> | + Document: + <a href="dom.html">Object model</a> · <a href="loading.html">Loading</a> · <b>Accessing</b> · <a href="modify.html">Modifying</a> · <a href="saving.html">Saving</a> | + <a href="xpath.html">XPath</a> | + <a href="apiref.html">API Reference</a> | + <a href="toc.html">Table of Contents</a> +</td> +<td width="*" align="right"><div class="spirit-nav"> +<a accesskey="p" href="loading.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../manual.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../manual.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="modify.html"><img src="../images/next.png" alt="Next"></a> +</div></td> +</tr></table> +</body> +</html> diff --git a/docs/manual/apiref.html b/docs/manual/apiref.html new file mode 100644 index 0000000..4648697 --- /dev/null +++ b/docs/manual/apiref.html @@ -0,0 +1,1151 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<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="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 | + <a href="../manual.html">Overview</a> | + <a href="install.html">Installation</a> | + Document: + <a href="dom.html">Object model</a> · <a href="loading.html">Loading</a> · <a href="access.html">Accessing</a> · <a href="modify.html">Modifying</a> · <a href="saving.html">Saving</a> | + <a href="xpath.html">XPath</a> | + <b>API Reference</b> | + <a href="toc.html">Table of Contents</a> +</td> +<td width="*" align="right"><div class="spirit-nav"> +<a accesskey="p" href="changes.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../manual.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../manual.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="toc.html"><img src="../images/next.png" alt="Next"></a> +</div></td> +</tr></table> +<hr> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="manual.apiref"></a><a class="link" href="apiref.html" title="API Reference"> API Reference</a> +</h2></div></div></div> +<p> + This is the reference for all macros, types, enumerations, classes and functions + in pugixml. Each symbol is a link that leads to the relevant section of the + manual. + </p> +<p> + Macros: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + <code class="computeroutput"><span class="preprocessor">#define</span> </code><a class="link" href="install.html#PUGIXML_WCHAR_MODE">PUGIXML_WCHAR_MODE</a> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="preprocessor">#define</span> </code><a class="link" href="install.html#PUGIXML_NO_XPATH">PUGIXML_NO_XPATH</a> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="preprocessor">#define</span> </code><a class="link" href="install.html#PUGIXML_NO_STL">PUGIXML_NO_STL</a> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="preprocessor">#define</span> </code><a class="link" href="install.html#PUGIXML_NO_EXCEPTIONS">PUGIXML_NO_EXCEPTIONS</a> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="preprocessor">#define</span> </code><a class="link" href="install.html#PUGIXML_API">PUGIXML_API</a> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="preprocessor">#define</span> </code><a class="link" href="install.html#PUGIXML_CLASS">PUGIXML_CLASS</a> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="preprocessor">#define</span> </code><a class="link" href="install.html#PUGIXML_FUNCTION">PUGIXML_FUNCTION</a> + </li> +</ul></div> +<p> + Types: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">typedef</span> </code><span class="emphasis"><em>configuration-defined + type</em></span><code class="computeroutput"> </code><a class="link" href="dom.html#char_t">char_t</a><code class="computeroutput"><span class="special">;</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">typedef</span> </code><span class="emphasis"><em>configuration-defined + type</em></span><code class="computeroutput"> </code><a class="link" href="dom.html#string_t">string_t</a><code class="computeroutput"><span class="special">;</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">typedef</span> <span class="keyword">void</span><span class="special">*</span> <span class="special">(*</span></code><a class="link" href="dom.html#allocation_function">allocation_function</a><code class="computeroutput"><span class="special">)(</span><span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">);</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">typedef</span> <span class="keyword">void</span> + <span class="special">(*</span></code><a class="link" href="dom.html#deallocation_function">deallocation_function</a><code class="computeroutput"><span class="special">)(</span><span class="keyword">void</span><span class="special">*</span> + <span class="identifier">ptr</span><span class="special">);</span></code> + </li> +</ul></div> +<p> + Enumerations: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">enum</span> </code><a class="link" href="dom.html#xml_node_type">xml_node_type</a> + <div class="itemizedlist"><ul class="itemizedlist" type="circle"> +<li class="listitem"> + <a class="link" href="dom.html#node_null">node_null</a> + </li> +<li class="listitem"> + <a class="link" href="dom.html#node_document">node_document</a> + </li> +<li class="listitem"> + <a class="link" href="dom.html#node_element">node_element</a> + </li> +<li class="listitem"> + <a class="link" href="dom.html#node_pcdata">node_pcdata</a> + </li> +<li class="listitem"> + <a class="link" href="dom.html#node_cdata">node_cdata</a> + </li> +<li class="listitem"> + <a class="link" href="dom.html#node_comment">node_comment</a> + </li> +<li class="listitem"> + <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> + + </li> +</ul></div> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">enum</span> </code><a class="link" href="loading.html#xml_parse_status">xml_parse_status</a> + <div class="itemizedlist"><ul class="itemizedlist" type="circle"> +<li class="listitem"> + <a class="link" href="loading.html#status_ok">status_ok</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#status_file_not_found">status_file_not_found</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#status_io_error">status_io_error</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#status_out_of_memory">status_out_of_memory</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#status_internal_error">status_internal_error</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#status_unrecognized_tag">status_unrecognized_tag</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#status_bad_pi">status_bad_pi</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#status_bad_comment">status_bad_comment</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#status_bad_cdata">status_bad_cdata</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#status_bad_doctype">status_bad_doctype</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#status_bad_pcdata">status_bad_pcdata</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#status_bad_start_element">status_bad_start_element</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#status_bad_attribute">status_bad_attribute</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#status_bad_end_element">status_bad_end_element</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#status_end_element_mismatch">status_end_element_mismatch</a> + <br><br> + + </li> +</ul></div> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">enum</span> </code><a class="link" href="loading.html#xml_encoding">xml_encoding</a> + <div class="itemizedlist"><ul class="itemizedlist" type="circle"> +<li class="listitem"> + <a class="link" href="loading.html#encoding_auto">encoding_auto</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#encoding_utf8">encoding_utf8</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#encoding_utf16_le">encoding_utf16_le</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#encoding_utf16_be">encoding_utf16_be</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#encoding_utf16">encoding_utf16</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#encoding_utf32_le">encoding_utf32_le</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#encoding_utf32_be">encoding_utf32_be</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#encoding_utf32">encoding_utf32</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#encoding_wchar">encoding_wchar</a> <br><br> + + </li> +</ul></div> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">enum</span> </code><a class="link" href="xpath.html#xpath_value_type">xpath_value_type</a> + <div class="itemizedlist"><ul class="itemizedlist" type="circle"> +<li class="listitem"> + <a class="link" href="xpath.html#xpath_type_none">xpath_type_none</a> + </li> +<li class="listitem"> + <a class="link" href="xpath.html#xpath_type_node_set">xpath_type_node_set</a> + </li> +<li class="listitem"> + <a class="link" href="xpath.html#xpath_type_number">xpath_type_number</a> + </li> +<li class="listitem"> + <a class="link" href="xpath.html#xpath_type_string">xpath_type_string</a> + </li> +<li class="listitem"> + <a class="link" href="xpath.html#xpath_type_boolean">xpath_type_boolean</a> + </li> +</ul></div> + </li> +</ul></div> +<p> + Constants: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Formatting options bit flags: + <div class="itemizedlist"><ul class="itemizedlist" type="circle"> +<li class="listitem"> + <a class="link" href="saving.html#format_default">format_default</a> + </li> +<li class="listitem"> + <a class="link" href="saving.html#format_indent">format_indent</a> + </li> +<li class="listitem"> + <a class="link" href="saving.html#format_no_declaration">format_no_declaration</a> + </li> +<li class="listitem"> + <a class="link" href="saving.html#format_raw">format_raw</a> + </li> +<li class="listitem"> + <a class="link" href="saving.html#format_write_bom">format_write_bom</a> <br><br> + + </li> +</ul></div> + </li> +<li class="listitem"> + Parsing options bit flags: + <div class="itemizedlist"><ul class="itemizedlist" type="circle"> +<li class="listitem"> + <a class="link" href="loading.html#parse_cdata">parse_cdata</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#parse_comments">parse_comments</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#parse_declaration">parse_declaration</a> + </li> +<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_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_minimal">parse_minimal</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#parse_pi">parse_pi</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#parse_ws_pcdata">parse_ws_pcdata</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#parse_wconv_attribute">parse_wconv_attribute</a> + </li> +<li class="listitem"> + <a class="link" href="loading.html#parse_wnorm_attribute">parse_wnorm_attribute</a> + </li> +</ul></div> + </li> +</ul></div> +<p> + Classes: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">class</span> </code><a class="link" href="dom.html#xml_attribute">xml_attribute</a> + <div class="itemizedlist"><ul class="itemizedlist" type="circle"> +<li class="listitem"> + <a class="link" href="dom.html#xml_attribute::ctor">xml_attribute</a><code class="computeroutput"><span class="special">();</span></code> <br><br> + + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="dom.html#xml_attribute::empty">empty</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="dom.html#xml_attribute::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> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="dom.html#xml_attribute::comparison">operator==</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">r</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="dom.html#xml_attribute::comparison">operator!=</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">r</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="dom.html#xml_attribute::comparison">operator<</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">r</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="dom.html#xml_attribute::comparison">operator></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">r</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="dom.html#xml_attribute::comparison">operator<=</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">r</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="dom.html#xml_attribute::comparison">operator>=</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">r</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_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> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">xml_attribute</span> </code><a class="link" href="access.html#xml_attribute::previous_attribute">previous_attribute</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">char_t</span><span class="special">*</span> </code><a class="link" href="access.html#xml_attribute::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="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> </code><a class="link" href="access.html#xml_attribute::value">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="keyword">int</span> </code><a class="link" href="access.html#xml_attribute::as_int">as_int</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">unsigned</span> <span class="keyword">int</span> + </code><a class="link" href="access.html#xml_attribute::as_uint">as_uint</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="access.html#xml_attribute::as_double">as_double</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">float</span> </code><a class="link" href="access.html#xml_attribute::as_float">as_float</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">bool</span> </code><a class="link" href="access.html#xml_attribute::as_bool">as_bool</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="modify.html#xml_attribute::set_name">set_name</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">rhs</span><span class="special">);</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="modify.html#xml_attribute::set_value">set_value</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">rhs</span><span class="special">);</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="modify.html#xml_attribute::set_value">set_value</a><code class="computeroutput"><span class="special">(</span><span class="keyword">int</span> <span class="identifier">rhs</span><span class="special">);</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="modify.html#xml_attribute::set_value">set_value</a><code class="computeroutput"><span class="special">(</span><span class="keyword">unsigned</span> + <span class="keyword">int</span> <span class="identifier">rhs</span><span class="special">);</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="modify.html#xml_attribute::set_value">set_value</a><code class="computeroutput"><span class="special">(</span><span class="keyword">double</span> + <span class="identifier">rhs</span><span class="special">);</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="modify.html#xml_attribute::set_value">set_value</a><code class="computeroutput"><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">rhs</span><span class="special">);</span></code> + <br><br> + + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">xml_attribute</span><span class="special">&</span> + </code><a class="link" href="modify.html#xml_attribute::assign">operator=</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">rhs</span><span class="special">);</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">xml_attribute</span><span class="special">&</span> + </code><a class="link" href="modify.html#xml_attribute::assign">operator=</a><code class="computeroutput"><span class="special">(</span><span class="keyword">int</span> <span class="identifier">rhs</span><span class="special">);</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">xml_attribute</span><span class="special">&</span> + </code><a class="link" href="modify.html#xml_attribute::assign">operator=</a><code class="computeroutput"><span class="special">(</span><span class="keyword">unsigned</span> + <span class="keyword">int</span> <span class="identifier">rhs</span><span class="special">);</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">xml_attribute</span><span class="special">&</span> + </code><a class="link" href="modify.html#xml_attribute::assign">operator=</a><code class="computeroutput"><span class="special">(</span><span class="keyword">double</span> + <span class="identifier">rhs</span><span class="special">);</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">xml_attribute</span><span class="special">&</span> + </code><a class="link" href="modify.html#xml_attribute::assign">operator=</a><code class="computeroutput"><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">rhs</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="dom.html#xml_node">xml_node</a> + <div class="itemizedlist"><ul class="itemizedlist" type="circle"> +<li class="listitem"> + <a class="link" href="dom.html#xml_node::ctor">xml_node</a><code class="computeroutput"><span class="special">();</span></code> + <br><br> + + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="dom.html#xml_node::empty">empty</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="dom.html#xml_node::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> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="dom.html#xml_node::comparison">operator==</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">r</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="dom.html#xml_node::comparison">operator!=</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">r</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="dom.html#xml_node::comparison">operator<</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">r</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="dom.html#xml_node::comparison">operator></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">r</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="dom.html#xml_node::comparison">operator<=</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">r</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="dom.html#xml_node::comparison">operator>=</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">r</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_type</span> </code><a class="link" href="dom.html#xml_node::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">const</span> <span class="identifier">char_t</span><span class="special">*</span> </code><a class="link" href="access.html#xml_node::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="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> </code><a class="link" href="access.html#xml_node::value">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</span> </code><a class="link" href="access.html#xml_node::parent">parent</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">xml_node</span> </code><a class="link" href="access.html#xml_node::first_child">first_child</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">xml_node</span> </code><a class="link" href="access.html#xml_node::last_child">last_child</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">xml_node</span> </code><a class="link" href="access.html#xml_node::next_sibling">next_sibling</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">xml_node</span> </code><a class="link" href="access.html#xml_node::previous_sibling">previous_sibling</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_node::first_attribute">first_attribute</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">xml_attribute</span> </code><a class="link" href="access.html#xml_node::last_attribute">last_attribute</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</span> </code><a class="link" href="access.html#xml_node::child">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> + <span class="keyword">const</span><span class="special">;</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">xml_attribute</span> </code><a class="link" href="access.html#xml_node::attribute">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> <span class="keyword">const</span><span class="special">;</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">xml_node</span> </code><a class="link" href="access.html#xml_node::next_sibling_name">next_sibling</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> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">xml_node</span> </code><a class="link" href="access.html#xml_node::previous_sibling_name">previous_sibling</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> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">xml_node</span> </code><a class="link" href="access.html#xml_node::find_child_by_attribute">find_child_by_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> + <span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">attr_name</span><span class="special">,</span> <span class="keyword">const</span> + <span class="identifier">char_t</span><span class="special">*</span> + <span class="identifier">attr_value</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">xml_node</span> </code><a class="link" href="access.html#xml_node::find_child_by_attribute">find_child_by_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">attr_name</span><span class="special">,</span> + <span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">attr_value</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="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> </code><a class="link" href="access.html#xml_node::child_value">child_value</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="access.html#xml_node::child_value">child_value</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> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">typedef</span> <span class="identifier">xml_node_iterator</span> + </code><a class="link" href="access.html#xml_node_iterator">iterator</a><code class="computeroutput"><span class="special">;</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">iterator</span> </code><a class="link" href="access.html#xml_node::begin">begin</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">iterator</span> </code><a class="link" href="access.html#xml_node::end">end</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">typedef</span> <span class="identifier">xml_attribute_iterator</span> + </code><a class="link" href="access.html#xml_attribute_iterator">attribute_iterator</a><code class="computeroutput"><span class="special">;</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">attribute_iterator</span> </code><a class="link" href="access.html#xml_node::attributes_begin">attributes_begin</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">attribute_iterator</span> </code><a class="link" href="access.html#xml_node::attributes_end">attributes_end</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="access.html#xml_node::traverse">traverse</a><code class="computeroutput"><span class="special">(</span><span class="identifier">xml_tree_walker</span><span class="special">&</span> <span class="identifier">walker</span><span class="special">);</span></code> <br><br> + + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Predicate</span><span class="special">></span> <span class="identifier">xml_attribute</span> + </code><a class="link" href="access.html#xml_node::find_attribute">find_attribute</a><code class="computeroutput"><span class="special">(</span><span class="identifier">Predicate</span> + <span class="identifier">pred</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">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Predicate</span><span class="special">></span> <span class="identifier">xml_node</span> + </code><a class="link" href="access.html#xml_node::find_child">find_child</a><code class="computeroutput"><span class="special">(</span><span class="identifier">Predicate</span> + <span class="identifier">pred</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">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Predicate</span><span class="special">></span> <span class="identifier">xml_node</span> + </code><a class="link" href="access.html#xml_node::find_node">find_node</a><code class="computeroutput"><span class="special">(</span><span class="identifier">Predicate</span> + <span class="identifier">pred</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">string_t</span> </code><a class="link" href="access.html#xml_node::path">path</a><code class="computeroutput"><span class="special">(</span><span class="identifier">char_t</span> + <span class="identifier">delimiter</span> <span class="special">=</span> + <span class="char">'/'</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">xml_node</span> </code><a class="link" href="access.html#xml_node::first_element_by_path">xml_node::first_element_by_path</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">path</span><span class="special">,</span> + <span class="identifier">char_t</span> <span class="identifier">delimiter</span> + <span class="special">=</span> <span class="char">'/'</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">xml_node</span> </code><a class="link" href="access.html#xml_node::root">root</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">ptrdiff_t</span> </code><a class="link" href="access.html#xml_node::offset_debug">offset_debug</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="modify.html#xml_node::set_name">set_name</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">rhs</span><span class="special">);</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="modify.html#xml_node::set_value">set_value</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">rhs</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_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::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> + <span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">attr</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_before">insert_attribute_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_attribute</span><span class="special">&</span> <span class="identifier">attr</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="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> + <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="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></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::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> + <span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">attr</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_before">insert_copy_before</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> + <span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">attr</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_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::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> + <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_copy_before">insert_copy_before</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> + <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="keyword">bool</span> </code><a class="link" href="modify.html#xml_node::remove_attribute">remove_attribute</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">a</span><span class="special">);</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="modify.html#xml_node::remove_attribute">remove_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="keyword">bool</span> </code><a class="link" href="modify.html#xml_node::remove_child">remove_child</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">n</span><span class="special">);</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="modify.html#xml_node::remove_child">remove_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> + <br><br> + + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">void</span> </code><a class="link" href="saving.html#xml_node::print">print</a><code class="computeroutput"><span class="special">(</span><span class="identifier">xml_writer</span><span class="special">&</span> <span class="identifier">writer</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></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">void</span> </code><a class="link" href="saving.html#xml_node::print_stream">print</a><code class="computeroutput"><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></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">void</span> </code><a class="link" href="saving.html#xml_node::print_stream">print</a><code class="computeroutput"><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></code> + <br><br> + + </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="keyword">const</span><span class="special">;</span></code> + </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_precomp">select_single_node</a><code class="computeroutput"><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></code> + </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="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#xml_node::select_nodes_precomp">select_nodes</a><code class="computeroutput"><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></code> + <br><br> + + </li> +</ul></div> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">class</span> </code><a class="link" href="dom.html#xml_document">xml_document</a> + <div class="itemizedlist"><ul class="itemizedlist" type="circle"> +<li class="listitem"> + <a class="link" href="dom.html#xml_document::ctor">xml_document</a><code class="computeroutput"><span class="special">();</span></code> + </li> +<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="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> + <span class="identifier">stream</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> + </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">wistream</span><span class="special">&</span> + <span class="identifier">stream</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></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_string">load</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">contents</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></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">load_file</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">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"> + <code class="computeroutput"><span class="identifier">xml_parse_result</span> </code><a class="link" href="loading.html#xml_document::load_buffer">load_buffer</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="keyword">void</span><span class="special">*</span> <span class="identifier">contents</span><span class="special">,</span> + <span class="identifier">size_t</span> <span class="identifier">size</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> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">xml_parse_result</span> </code><a class="link" href="loading.html#xml_document::load_buffer_inplace">load_buffer_inplace</a><code class="computeroutput"><span class="special">(</span><span class="keyword">void</span><span class="special">*</span> <span class="identifier">contents</span><span class="special">,</span> <span class="identifier">size_t</span> + <span class="identifier">size</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> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">xml_parse_result</span> </code><a class="link" href="loading.html#xml_document::load_buffer_inplace_own">load_buffer_inplace_own</a><code class="computeroutput"><span class="special">(</span><span class="keyword">void</span><span class="special">*</span> <span class="identifier">contents</span><span class="special">,</span> <span class="identifier">size_t</span> + <span class="identifier">size</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"> + <code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="saving.html#xml_document::save_file">save_file</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">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> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">void</span> </code><a class="link" href="saving.html#xml_document::save_stream">save</a><code class="computeroutput"><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">stream</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> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">void</span> </code><a class="link" href="saving.html#xml_document::save_stream">save</a><code class="computeroutput"><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">stream</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">const</span><span class="special">;</span></code> + <br><br> + + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">void</span> </code><a class="link" href="saving.html#xml_document::save">save</a><code class="computeroutput"><span class="special">(</span><span class="identifier">xml_writer</span><span class="special">&</span> <span class="identifier">writer</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> +</ul></div> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">struct</span> </code><a class="link" href="loading.html#xml_parse_result">xml_parse_result</a> + <div class="itemizedlist"><ul class="itemizedlist" type="circle"> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">xml_parse_status</span> </code><a class="link" href="loading.html#xml_parse_result::status">status</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="loading.html#xml_parse_result::offset">offset</a><code class="computeroutput"><span class="special">;</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">xml_encoding</span> </code><a class="link" href="loading.html#xml_parse_result::encoding">encoding</a><code class="computeroutput"><span class="special">;</span></code> <br><br> + + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">operator</span> </code><a class="link" href="loading.html#xml_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="loading.html#xml_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="access.html#xml_node_iterator">xml_node_iterator</a> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">class</span> </code><a class="link" href="access.html#xml_attribute_iterator">xml_attribute_iterator</a> + <br><br> + + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">class</span> </code><a class="link" href="access.html#xml_tree_walker">xml_tree_walker</a> + <div class="itemizedlist"><ul class="itemizedlist" type="circle"> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">virtual</span> <span class="keyword">bool</span> + </code><a class="link" href="access.html#xml_tree_walker::begin">begin</a><code class="computeroutput"><span class="special">(</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="keyword">virtual</span> <span class="keyword">bool</span> + </code><a class="link" href="access.html#xml_tree_walker::for_each">for_each</a><code class="computeroutput"><span class="special">(</span><span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">node</span><span class="special">)</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">virtual</span> <span class="keyword">bool</span> + </code><a class="link" href="access.html#xml_tree_walker::end">end</a><code class="computeroutput"><span class="special">(</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="keyword">int</span> </code><a class="link" href="access.html#xml_tree_walker::depth">depth</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="saving.html#xml_writer">xml_writer</a> + <div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"> + <code class="computeroutput"><span class="keyword">virtual</span> <span class="keyword">void</span> + </code><a class="link" href="saving.html#xml_writer::write">write</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="keyword">void</span><span class="special">*</span> <span class="identifier">data</span><span class="special">,</span> + <span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">)</span> <span class="special">=</span> <span class="number">0</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="saving.html#xml_writer_file">xml_writer_file</a><code class="computeroutput"><span class="special">:</span> <span class="keyword">public</span> <span class="identifier">xml_writer</span></code> + <div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"> + <a class="link" href="saving.html#xml_writer_file">xml_writer_file</a><code class="computeroutput"><span class="special">(</span><span class="keyword">void</span><span class="special">*</span> <span class="identifier">file</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="saving.html#xml_writer_stream">xml_writer_stream</a><code class="computeroutput"><span class="special">:</span> <span class="keyword">public</span> <span class="identifier">xml_writer</span></code> + <div class="itemizedlist"><ul class="itemizedlist" type="circle"> +<li class="listitem"> + <a class="link" href="saving.html#xml_writer_stream">xml_writer_stream</a><code class="computeroutput"><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">stream</span><span class="special">);</span></code> + </li> +<li class="listitem"> + <a class="link" href="saving.html#xml_writer_stream">xml_writer_stream</a><code class="computeroutput"><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">stream</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::ctor</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> + <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> + <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> + <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> + <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> + <span class="identifier">n</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">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> +</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"> + <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">class</span> </code><a class="link" href="xpath.html#xpath_node">xpath_node</a> + <div class="itemizedlist"><ul class="itemizedlist" type="circle"> +<li class="listitem"> + <a class="link" href="xpath.html#xpath_node::ctor">xpath_node</a><code class="computeroutput"><span class="special">();</span></code> + </li> +<li class="listitem"> + <a class="link" href="xpath.html#xpath_node::ctor">xpath_node</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">node</span><span class="special">);</span></code> + </li> +<li class="listitem"> + <a class="link" href="xpath.html#xpath_node::ctor">xpath_node</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">attribute</span><span class="special">,</span> <span class="keyword">const</span> + <span class="identifier">xml_node</span><span class="special">&</span> + <span class="identifier">parent</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="xpath.html#xpath_node::node">node</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">xml_attribute</span> </code><a class="link" href="xpath.html#xpath_node::attribute">attribute</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">xml_node</span> </code><a class="link" href="xpath.html#xpath_node::parent">parent</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">operator</span> </code><a class="link" href="xpath.html#xpath_node::unspecified_bool_type">unspecified_bool_type</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">bool</span> </code><a class="link" href="xpath.html#xpath_node::comparison">operator==</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">bool</span> </code><a class="link" href="xpath.html#xpath_node::comparison">operator!=</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> + + </li> +</ul></div> + </li> +<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"> + <code class="computeroutput"><span class="keyword">typedef</span> <span class="keyword">const</span> + <span class="identifier">xpath_node</span><span class="special">*</span> + </code><a class="link" href="xpath.html#xpath_node_set::const_iterator">const_iterator</a><code class="computeroutput"><span class="special">;</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">const_iterator</span> </code><a class="link" href="xpath.html#xpath_node_set::begin">begin</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">const_iterator</span> </code><a class="link" href="xpath.html#xpath_node_set::end">end</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_node</span><span class="special">&</span> </code><a class="link" href="xpath.html#xpath_node_set::index">operator[]</a><code class="computeroutput"><span class="special">(</span><span class="identifier">size_t</span> + <span class="identifier">index</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">size_t</span> </code><a class="link" href="xpath.html#xpath_node_set::size">size</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">bool</span> </code><a class="link" href="xpath.html#xpath_node_set::empty">empty</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">xpath_node</span> </code><a class="link" href="xpath.html#xpath_node_set::first">first</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">enum</span> <span class="identifier">type_t</span> + <span class="special">{</span></code><a class="link" href="xpath.html#xpath_node_set::type_unsorted">type_unsorted</a>, + <a class="link" href="xpath.html#xpath_node_set::type_sorted">type_sorted</a>, + <a class="link" href="xpath.html#xpath_node_set::type_sorted_reverse">type_sorted_reverse</a><code class="computeroutput"><span class="special">};</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">type_t</span> </code><a class="link" href="xpath.html#xpath_node_set::type">type</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">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> + </li> +</ul></div> + </li> +</ul></div> +<p> + Functions: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + <a class="link" href="dom.html#as_utf8">as_utf8</a> + </li> +<li class="listitem"> + <a class="link" href="dom.html#as_wide">as_wide</a> + </li> +<li class="listitem"> + <a class="link" href="dom.html#get_memory_allocation_function">get_memory_allocation_function</a> + </li> +<li class="listitem"> + <a class="link" href="dom.html#get_memory_deallocation_function">get_memory_deallocation_function</a> + </li> +<li class="listitem"> + <a class="link" href="dom.html#set_memory_management_functions">set_memory_management_functions</a> + </li> +</ul></div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2010 Arseny Kapoulkine<p> + Distributed under the MIT License + </p> +</div></td> +</tr></table> +<hr> +<table width="100%"><tr> +<td>pugixml 0.9 manual | + <a href="../manual.html">Overview</a> | + <a href="install.html">Installation</a> | + Document: + <a href="dom.html">Object model</a> · <a href="loading.html">Loading</a> · <a href="access.html">Accessing</a> · <a href="modify.html">Modifying</a> · <a href="saving.html">Saving</a> | + <a href="xpath.html">XPath</a> | + <b>API Reference</b> | + <a href="toc.html">Table of Contents</a> +</td> +<td width="*" align="right"><div class="spirit-nav"> +<a accesskey="p" href="changes.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../manual.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../manual.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="toc.html"><img src="../images/next.png" alt="Next"></a> +</div></td> +</tr></table> +</body> +</html> diff --git a/docs/manual/changes.html b/docs/manual/changes.html new file mode 100644 index 0000000..48e8325 --- /dev/null +++ b/docs/manual/changes.html @@ -0,0 +1,574 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<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="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 | + <a href="../manual.html">Overview</a> | + <a href="install.html">Installation</a> | + Document: + <a href="dom.html">Object model</a> · <a href="loading.html">Loading</a> · <a href="access.html">Accessing</a> · <a href="modify.html">Modifying</a> · <a href="saving.html">Saving</a> | + <a href="xpath.html">XPath</a> | + <a href="apiref.html">API Reference</a> | + <a href="toc.html">Table of Contents</a> +</td> +<td width="*" align="right"><div class="spirit-nav"> +<a accesskey="p" href="xpath.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../manual.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../manual.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="apiref.html"><img src="../images/next.png" alt="Next"></a> +</div></td> +</tr></table> +<hr> +<div class="section"> +<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_07_2010___version_0_9"></a><h6> +<a name="id1359890"></a> + <a class="link" href="changes.html#manual.changes.1_07_2010___version_0_9">1.07.2010 - version + 0.9</a> + </h6> +<p> + Major release, featuring extended and improved Unicode support, miscellaneous + performance improvements, bug fixes and more. + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Major Unicode improvements: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + Introduced encoding support (automatic/manual encoding detection + on load, manual encoding selection on save, conversion from/to UTF8, + UTF16 LE/BE, UTF32 LE/BE) + </li> +<li class="listitem"> + Introduced wchar_t mode (you can set PUGIXML_WCHAR_MODE define to + switch pugixml internal encoding from UTF8 to wchar_t; all functions + are switched to their Unicode variants) + </li> +<li class="listitem"> + Load/save functions now support wide streams + </li> +</ol></div> + </li> +<li class="listitem"> + Bug fixes: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + Fixed document corruption on failed parsing bug + </li> +<li class="listitem"> + XPath string <-> number conversion improvements (increased + precision, fixed crash for huge numbers) + </li> +<li class="listitem"> + Improved DOCTYPE parsing: now parser recognizes all well-formed DOCTYPE + declarations + </li> +<li class="listitem"> + Fixed xml_attribute::as_uint() for large numbers (i.e. 2^32-1) + </li> +<li class="listitem"> + Fixed xml_node::first_element_by_path for path components that are + prefixes of node names, but are not exactly equal to them. + </li> +</ol></div> + </li> +<li class="listitem"> + Specification changes: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + parse() API changed to load_buffer/load_buffer_inplace/load_buffer_inplace_own; + load_buffer APIs do not require zero-terminated strings. + </li> +<li class="listitem"> + Renamed as_utf16 to as_wide + </li> +<li class="listitem"> + Changed xml_node::offset_debug return type and xml_parse_result::offset + type to ptrdiff_t + </li> +<li class="listitem"> + Nodes/attributes with empty names are now printed as :anonymous + </li> +</ol></div> + </li> +<li class="listitem"> + Performance improvements: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + Optimized document parsing and saving + </li> +<li class="listitem"> + Changed internal memory management: internal allocator is used for + both metadata and name/value data; allocated pages are deleted if + all allocations from them are deleted + </li> +<li class="listitem"> + Optimized memory consumption: sizeof(xml_node_struct) reduced from + 40 bytes to 32 bytes on x86 + </li> +<li class="listitem"> + Optimized debug mode parsing/saving by order of magnitude + </li> +</ol></div> + </li> +<li class="listitem"> + Miscellaneous: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + All STL includes except <exception> in pugixml.hpp are replaced + with forward declarations + </li> +<li class="listitem"> + xml_node::remove_child and xml_node::remove_attribute now return + the operation result + </li> +</ol></div> + </li> +<li class="listitem"> + Compatibility: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + parse() and as_utf16 are left for compatibility (these functions + are deprecated and will be removed in version 1.0) + </li> +<li class="listitem"> + Wildcard functions, document_order/precompute_document_order functions, + all_elements_by_name function and format_write_bom_utf8 flag are + deprecated and will be removed in version 1.0 + </li> +<li class="listitem"> + xpath_type_t enumeration was renamed to xpath_value_type; xpath_type_t + is deprecated and will be removed in version 1.0 + </li> +</ol></div> + </li> +</ul></div> +<a name="manual.changes.8_11_2009___version_0_5"></a><h6> +<a name="id1361399"></a> + <a class="link" href="changes.html#manual.changes.8_11_2009___version_0_5">8.11.2009 - version + 0.5</a> + </h6> +<p> + Major bugfix release. Changes: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + XPath bugfixes: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + Fixed translate(), lang() and concat() functions (infinite loops/crashes) + </li> +<li class="listitem"> + Fixed compilation of queries with empty literal strings ("") + </li> +<li class="listitem"> + Fixed axis tests: they never add empty nodes/attributes to the resulting + node set now + </li> +<li class="listitem"> + Fixed string-value evaluation for node-set (the result excluded some + text descendants) + </li> +<li class="listitem"> + Fixed self:: axis (it behaved like ancestor-or-self::) + </li> +<li class="listitem"> + Fixed following:: and preceding:: axes (they included descendent + and ancestor nodes, respectively) + </li> +<li class="listitem"> + Minor fix for namespace-uri() function (namespace declaration scope + includes the parent element of namespace declaration attribute) + </li> +<li class="listitem"> + Some incorrect queries are no longer parsed now (i.e. foo: *) + </li> +<li class="listitem"> + Fixed text()/etc. node test parsing bug (i.e. foo[text()] failed + to compile) + </li> +<li class="listitem"> + Fixed root step (/) - it now selects empty node set if query is evaluated + on empty node + </li> +<li class="listitem"> + Fixed string to number conversion ("123 " converted to + NaN, "123 .456" converted to 123.456 - now the results + are 123 and NaN, respectively) + </li> +<li class="listitem"> + Node set copying now preserves sorted type; leads to better performance + on some queries + </li> +</ol></div> + </li> +<li class="listitem"> + Miscellaneous bugfixes: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + Fixed xml_node::offset_debug for PI nodes + </li> +<li class="listitem"> + Added empty attribute checks to xml_node::remove_attribute + </li> +<li class="listitem"> + Fixed node_pi and node_declaration copying + </li> +<li class="listitem"> + Const-correctness fixes + </li> +</ol></div> + </li> +<li class="listitem"> + Specification changes: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + xpath_node::select_nodes() and related functions now throw exception + if expression return type is not node set (instead of assertion) + </li> +<li class="listitem"> + xml_node::traverse() now sets depth to -1 for both begin() and end() + callbacks (was 0 at begin() and -1 at end()) + </li> +<li class="listitem"> + In case of non-raw node printing a newline is output after PCDATA + inside nodes if the PCDATA has siblings + </li> +<li class="listitem"> + UTF8 -> wchar_t conversion now considers 5-byte UTF8-like sequences + as invalid + </li> +</ol></div> + </li> +<li class="listitem"> + New features: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + Added xpath_node_set::operator[] for index-based iteration + </li> +<li class="listitem"> + Added xpath_query::return_type() + </li> +<li class="listitem"> + Added getter accessors for memory-management functions + </li> +</ol></div> + </li> +</ul></div> +<a name="manual.changes.17_09_2009___version_0_42"></a><h6> +<a name="id1361638"></a> + <a class="link" href="changes.html#manual.changes.17_09_2009___version_0_42">17.09.2009 - version + 0.42</a> + </h6> +<p> + Maintenance release. Changes: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Bug fixes: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + Fixed deallocation in case of custom allocation functions or if delete[] + / free are incompatible + </li> +<li class="listitem"> + XPath parser fixed for incorrect queries (i.e. incorrect XPath queries + should now always fail to compile) + </li> +<li class="listitem"> + Const-correctness fixes for find_child_by_attribute + </li> +<li class="listitem"> + Improved compatibility (miscellaneous warning fixes, fixed cstring + include dependency for GCC) + </li> +<li class="listitem"> + Fixed iterator begin/end and print function to work correctly for + empty nodes + </li> +</ol></div> + </li> +<li class="listitem"> + New features: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + Added PUGIXML_API/PUGIXML_CLASS/PUGIXML_FUNCTION configuration macros + to control class/function attributes + </li> +<li class="listitem"> + Added xml_attribute::set_value overloads for different types + </li> +</ol></div> + </li> +</ul></div> +<a name="manual.changes.8_02_2009___version_0_41"></a><h6> +<a name="id1361735"></a> + <a class="link" href="changes.html#manual.changes.8_02_2009___version_0_41">8.02.2009 - version + 0.41</a> + </h6> +<p> + Maintenance release. Changes: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + Bug fixes: + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + Fixed bug with node printing (occasionally some content was not written + to output stream) + </li></ol></div> + </li></ul></div> +<a name="manual.changes.18_01_2009___version_0_4"></a><h6> +<a name="id1361776"></a> + <a class="link" href="changes.html#manual.changes.18_01_2009___version_0_4">18.01.2009 - version + 0.4</a> + </h6> +<p> + Changes: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Bug fixes: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + Documentation fix in samples for parse() with manual lifetime control + </li> +<li class="listitem"> + Fixed document order sorting in XPath (it caused wrong order of nodes + after xpath_node_set::sort and wrong results of some XPath queries) + </li> +</ol></div> + </li> +<li class="listitem"> + Node printing changes: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + Single quotes are no longer escaped when printing nodes + </li> +<li class="listitem"> + Symbols in second half of ASCII table are no longer escaped when + printing nodes; because of this, format_utf8 flag is deleted as it's + no longer needed and format_write_bom is renamed to format_write_bom_utf8. + </li> +<li class="listitem"> + Reworked node printing - now it works via xml_writer interface; implementations + for FILE* and std::ostream are available. As a side-effect, xml_document::save_file + now works without STL. + </li> +</ol></div> + </li> +<li class="listitem"> + New features: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + Added unsigned integer support for attributes (xml_attribute::as_uint, + xml_attribute::operator=) + </li> +<li class="listitem"> + Now document declaration (<?xml ...?>) is parsed as node with + type node_declaration when parse_declaration flag is specified (access + to encoding/version is performed as if they were attributes, i.e. + doc.child("xml").attribute("version").as_float()); + corresponding flags for node printing were also added + </li> +<li class="listitem"> + Added support for custom memory management (see set_memory_management_functions + for details) + </li> +<li class="listitem"> + Implemented node/attribute copying (see xml_node::insert_copy_* and + xml_node::append_copy for details) + </li> +<li class="listitem"> + Added find_child_by_attribute and find_child_by_attribute_w to simplify + parsing code in some cases (i.e. COLLADA files) + </li> +<li class="listitem"> + Added file offset information querying for debugging purposes (now + you're able to determine exact location of any xml_node in parsed + file, see xml_node::offset_debug for details) + </li> +<li class="listitem"> + Improved error handling for parsing - now load(), load_file() and + parse() return xml_parse_result, which contains error code and last + parsed offset; this does not break old interface as xml_parse_result + can be implicitly casted to bool. + </li> +</ol></div> + </li> +</ul></div> +<a name="manual.changes.31_10_2007___version_0_34"></a><h6> +<a name="id1361922"></a> + <a class="link" href="changes.html#manual.changes.31_10_2007___version_0_34">31.10.2007 - version + 0.34</a> + </h6> +<p> + Maintenance release. Changes: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Bug fixes: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + Fixed bug with loading from text-mode iostreams + </li> +<li class="listitem"> + Fixed leak when transfer_ownership is true and parsing is failing + </li> +<li class="listitem"> + Fixed bug in saving (\r and \n are now escaped in attribute values) + </li> +<li class="listitem"> + Renamed free() to destroy() - some macro conflicts were reported + </li> +</ol></div> + </li> +<li class="listitem"> + New features: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + Improved compatibility (supported Digital Mars C++, MSVC 6, CodeWarrior + 8, PGI C++, Comeau, supported PS3 and XBox360) + </li> +<li class="listitem"> + PUGIXML_NO_EXCEPTION flag for platforms without exception handling + </li> +</ol></div> + </li> +</ul></div> +<a name="manual.changes.21_02_2007___version_0_3"></a><h6> +<a name="id1362012"></a> + <a class="link" href="changes.html#manual.changes.21_02_2007___version_0_3">21.02.2007 - version + 0.3</a> + </h6> +<p> + Refactored, reworked and improved version. Changes: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Interface: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + Added XPath + </li> +<li class="listitem"> + Added tree modification functions + </li> +<li class="listitem"> + Added no STL compilation mode + </li> +<li class="listitem"> + Added saving document to file + </li> +<li class="listitem"> + Refactored parsing flags + </li> +<li class="listitem"> + Removed xml_parser class in favor of xml_document + </li> +<li class="listitem"> + Added transfer ownership parsing mode + </li> +<li class="listitem"> + Modified the way xml_tree_walker works + </li> +<li class="listitem"> + Iterators are now non-constant + </li> +</ol></div> + </li> +<li class="listitem"> + Implementation: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + Support of several compilers and platforms + </li> +<li class="listitem"> + Refactored and sped up parsing core + </li> +<li class="listitem"> + Improved standard compliancy + </li> +<li class="listitem"> + Added XPath implementation + </li> +<li class="listitem"> + Fixed several bugs + </li> +</ol></div> + </li> +</ul></div> +<a name="manual.changes.6_11_2006___version_0_2"></a><h6> +<a name="id1362168"></a> + <a class="link" href="changes.html#manual.changes.6_11_2006___version_0_2">6.11.2006 - version + 0.2</a> + </h6> +<p> + First public release. Changes: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Bug fixes: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + Fixed child_value() (for empty nodes) + </li> +<li class="listitem"> + Fixed xml_parser_impl warning at W4 + </li> +</ol></div> + </li> +<li class="listitem"> + New features: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + Introduced child_value(name) and child_value_w(name) + </li> +<li class="listitem"> + parse_eol_pcdata and parse_eol_attribute flags + parse_minimal optimizations + </li> +<li class="listitem"> + Optimizations of strconv_t + </li> +</ol></div> + </li> +</ul></div> +<a name="manual.changes.15_07_2006___version_0_1"></a><h6> +<a name="id1362252"></a> + <a class="link" href="changes.html#manual.changes.15_07_2006___version_0_1">15.07.2006 - version + 0.1</a> + </h6> +<p> + First private release for testing purposes + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2010 Arseny Kapoulkine<p> + Distributed under the MIT License + </p> +</div></td> +</tr></table> +<hr> +<table width="100%"><tr> +<td>pugixml 0.9 manual | + <a href="../manual.html">Overview</a> | + <a href="install.html">Installation</a> | + Document: + <a href="dom.html">Object model</a> · <a href="loading.html">Loading</a> · <a href="access.html">Accessing</a> · <a href="modify.html">Modifying</a> · <a href="saving.html">Saving</a> | + <a href="xpath.html">XPath</a> | + <a href="apiref.html">API Reference</a> | + <a href="toc.html">Table of Contents</a> +</td> +<td width="*" align="right"><div class="spirit-nav"> +<a accesskey="p" href="xpath.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../manual.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../manual.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="apiref.html"><img src="../images/next.png" alt="Next"></a> +</div></td> +</tr></table> +</body> +</html> diff --git a/docs/manual/dom.html b/docs/manual/dom.html new file mode 100644 index 0000000..e4f1579 --- /dev/null +++ b/docs/manual/dom.html @@ -0,0 +1,649 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<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="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 | + <a href="../manual.html">Overview</a> | + <a href="install.html">Installation</a> | + Document: + <b>Object model</b> · <a href="loading.html">Loading</a> · <a href="access.html">Accessing</a> · <a href="modify.html">Modifying</a> · <a href="saving.html">Saving</a> | + <a href="xpath.html">XPath</a> | + <a href="apiref.html">API Reference</a> | + <a href="toc.html">Table of Contents</a> +</td> +<td width="*" align="right"><div class="spirit-nav"> +<a accesskey="p" href="install.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../manual.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../manual.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="loading.html"><img src="../images/next.png" alt="Next"></a> +</div></td> +</tr></table> +<hr> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="manual.dom"></a><a class="link" href="dom.html" title="Document object model"> Document object model</a> +</h2></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="dom.html#manual.dom.tree"> Tree structure</a></span></dt> +<dt><span class="section"><a href="dom.html#manual.dom.cpp"> C++ interface</a></span></dt> +<dt><span class="section"><a href="dom.html#manual.dom.unicode"> Unicode interface</a></span></dt> +<dt><span class="section"><a href="dom.html#manual.dom.thread"> Thread-safety guarantees</a></span></dt> +<dt><span class="section"><a href="dom.html#manual.dom.exception"> Exception guarantees</a></span></dt> +<dt><span class="section"><a href="dom.html#manual.dom.memory"> Memory management</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="dom.html#manual.dom.memory.custom"> Custom memory allocation/deallocation + functions</a></span></dt> +<dt><span class="section"><a href="dom.html#manual.dom.memory.internals"> Document memory management + internals</a></span></dt> +</dl></dd> +</dl></div> +<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, + C++ I/O stream or custom transport). + </p> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.dom.tree"></a><a class="link" href="dom.html#manual.dom.tree" title="Tree structure"> Tree structure</a> +</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). + </p> +<a name="xml_node_type"></a><p> + The tree nodes can be of one of the following types (which together form + the enumeration <code class="computeroutput"><span class="identifier">xml_node_type</span></code>): + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<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> + + </li> +<li class="listitem"> + Element/tag node ( <a name="node_element"></a><code class="literal">node_element</code>) - this + 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: + </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>, + 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> + and does not have any attributes or child nodes. + </p></blockquote></div> +<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: + </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> +<div class="blockquote"><blockquote class="blockquote"><p> + Here <code class="computeroutput"><span class="string">"node"</span></code> element + has three children, two of which are PCDATA nodes with values <code class="computeroutput"><span class="string">"text1"</span></code> and <code class="computeroutput"><span class="string">"text2"</span></code>. + </p></blockquote></div> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + Character data nodes ( <a name="node_cdata"></a><code class="literal">node_cdata</code>) represent + text in XML that is quoted in a special way. CDATA nodes do not differ + from PCDATA nodes except in XML representation - the above text example + looks like this with CDATA: + </li></ul></div> +<pre class="programlisting"><span class="special"><</span><span class="identifier">node</span><span class="special">></span> <span class="special"><![</span><span class="identifier">CDATA</span><span class="special">[[</span><span class="identifier">text1</span><span class="special">]]></span> <span class="special"><</span><span class="identifier">child</span><span class="special">/></span> <span class="special"><![</span><span class="identifier">CDATA</span><span class="special">[[</span><span class="identifier">text2</span><span class="special">]]></span> <span class="special"></</span><span class="identifier">node</span><span class="special">></span> +</pre> +<div class="blockquote"><blockquote class="blockquote"><p> + CDATA nodes make it easy to include non-escaped <, & and > characters + in plain text. CDATA value can not contain the character sequence ]]>, + since it is used to determine the end of node contents. + </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: + </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> +<div class="blockquote"><blockquote class="blockquote"><p> + 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> + 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: + </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> +<div class="blockquote"><blockquote class="blockquote"><p> + 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. + </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. + 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: + </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> +<div class="blockquote"><blockquote class="blockquote"><p> + Here the node has name <code class="computeroutput"><span class="string">"xml"</span></code> + 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. + </p></blockquote></div> +<p> + Finally, here is a complete example of XML document and the corresponding + tree representation (<a href="../samples/tree.xml" target="_top">samples/tree.xml</a>): + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +</colgroup> +<tbody><tr> +<td> + <p> + +</p> +<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-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> +<span class="special"><</span><span class="identifier">mesh</span> <span class="identifier">name</span><span class="special">=</span><span class="string">"mesh_root"</span><span class="special">></span> + <span class="special"><!--</span> <span class="identifier">here</span> <span class="identifier">is</span> <span class="identifier">a</span> <span class="identifier">mesh</span> <span class="identifier">node</span> <span class="special">--></span> + <span class="identifier">some</span> <span class="identifier">text</span> + <span class="special"><![</span><span class="identifier">CDATA</span><span class="special">[</span><span class="identifier">someothertext</span><span class="special">]]></span> + <span class="identifier">some</span> <span class="identifier">more</span> <span class="identifier">text</span> + <span class="special"><</span><span class="identifier">node</span> <span class="identifier">attr1</span><span class="special">=</span><span class="string">"value1"</span> <span class="identifier">attr2</span><span class="special">=</span><span class="string">"value2"</span> <span class="special">/></span> + <span class="special"><</span><span class="identifier">node</span> <span class="identifier">attr1</span><span class="special">=</span><span class="string">"value2"</span><span class="special">></span> + <span class="special"><</span><span class="identifier">innernode</span><span class="special">/></span> + <span class="special"></</span><span class="identifier">node</span><span class="special">></span> +<span class="special"></</span><span class="identifier">mesh</span><span class="special">></span> +<span class="special"><?</span><span class="identifier">include</span> <span class="identifier">somedata</span><span class="special">?></span> +</pre> +<p> + </p> + </td> +<td> + <p> + <a href="../images/dom_tree.png" target="_top"><span class="inlinemediaobject"><img src="../images/dom_tree_thumb.png" alt="dom_tree_thumb"></span></a> + </p> + </td> +</tr></tbody> +</table></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.dom.cpp"></a><a class="link" href="dom.html#manual.dom.cpp" title="C++ interface"> C++ interface</a> +</h3></div></div></div> +<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> + All pugixml classes and functions are located in <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. + </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>, + <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. + </p> +<a name="xml_document"></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>, + 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. + </p> +<a name="xml_document::ctor"></a><a name="xml_document::dtor"></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> + 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> +<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> + While technically node/attribute handles can be alive when the tree they're + referring to is destroyed, calling any member function of 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. + </p></td></tr> +</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> + 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> + objects by value without additional overhead. + </p> +<a name="node_null"></a><p> + There is a special value of <code class="computeroutput"><span class="identifier">xml_node</span></code> + type, known as null node or empty node (such nodes have type <code class="computeroutput"><span class="identifier">node_null</span></code>). It does not correspond to any + node in any document, and thus resembles null pointer. However, all operations + are defined on empty nodes; generally the operations don't do anything and + return empty nodes/attributes or empty strings as their result (see documentation + 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. + </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. + </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 + which initializes them to null objects. + </p> +<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 + 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). + </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> + <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>. + Alternatively you can check if a given <code class="computeroutput"><span class="identifier">xml_node</span></code>/<code class="computeroutput"><span class="identifier">xml_attribute</span></code> handle is null by calling + the following methods: + </p> +<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">empty</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<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 + 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. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.dom.unicode"></a><a class="link" href="dom.html#manual.dom.unicode" title="Unicode interface"> Unicode interface</a> +</h3></div></div></div> +<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. + </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> + 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. + </p></td></tr> +</table></div> +<p> + All tree functions that work with strings work with either C-style null terminated + strings or STL strings of the selected character type. For example, node + name accessors look like this in char mode: + </p> +<pre class="programlisting"><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">xml_node</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="keyword">bool</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">set_name</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">value</span><span class="special">);</span> +</pre> +<p> + and like this in wchar_t mode: + </p> +<pre class="programlisting"><span class="keyword">const</span> <span class="keyword">wchar_t</span><span class="special">*</span> <span class="identifier">xml_node</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="keyword">bool</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">set_name</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">wchar_t</span><span class="special">*</span> <span class="identifier">value</span><span class="special">);</span> +</pre> +<a name="char_t"></a><a name="string_t"></a><p> + There is a special type, <code class="computeroutput"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">char_t</span></code>, + that is defined as the character type and depends on the library configuration; + it will be also used in the documentation hereafter. There is also a type + <code class="computeroutput"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">string_t</span></code>, which is defined as the STL string + of the character type; it corresponds to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code> + in char mode and to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wstring</span></code> in wchar_t mode. + </p> +<p> + In addition to the interface, the internal implementation changes to store + XML data as <code class="computeroutput"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">char_t</span></code>; this means that these two modes + have different memory usage characteristics. The conversion to <code class="computeroutput"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">char_t</span></code> upon document loading and from + <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 + is probably a better choice. + </p> +<a name="as_utf8"></a><a name="as_wide"></a><p> + There are cases when you'll have to convert string data between UTF-8 and + wchar_t encodings; the following helper functions are provided for such purposes: + </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="keyword">wchar_t</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="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. + <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. + </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> + 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 + have to make is to pass <code class="computeroutput"><span class="keyword">wchar_t</span></code> + string literals, i.e. instead of + </p> +<p> + <code class="computeroutput"><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">child</span><span class="special">(</span><span class="string">"bookstore"</span><span class="special">).</span><span class="identifier">find_child_by_attribute</span><span class="special">(</span><span class="string">"book"</span><span class="special">,</span> <span class="string">"id"</span><span class="special">,</span> <span class="string">"12345"</span><span class="special">);</span></code> + </p> +<p> + you'll have to do + </p> +<p> + <code class="computeroutput"><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">child</span><span class="special">(</span><span class="identifier">L</span><span class="string">"bookstore"</span><span class="special">).</span><span class="identifier">find_child_by_attribute</span><span class="special">(</span><span class="identifier">L</span><span class="string">"book"</span><span class="special">,</span> <span class="identifier">L</span><span class="string">"id"</span><span class="special">,</span> <span class="identifier">L</span><span class="string">"12345"</span><span class="special">);</span></code> + </p> +</td></tr> +</table></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.dom.thread"></a><a class="link" href="dom.html#manual.dom.thread" title="Thread-safety guarantees"> Thread-safety guarantees</a> +</h3></div></div></div> +<p> + Almost all functions in pugixml have the following thread-safety guarantees: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + it is safe to call free functions from multiple threads + </li> +<li class="listitem"> + it is safe to perform concurrent read-only accesses to the same tree + (all constant member functions do not modify the tree) + </li> +<li class="listitem"> + it is safe to perform concurrent read/write accesses, if there is only + one read or write access to the single tree at a time + </li> +</ul></div> +<p> + Concurrent modification and traversing of a single tree requires synchronization, + for example via reader-writer lock. Modification includes altering document + 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>; + 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>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.dom.exception"></a><a class="link" href="dom.html#manual.dom.exception" title="Exception guarantees"> Exception guarantees</a> +</h3></div></div></div> +<p> + With the exception of XPath, pugixml itself does not throw any exceptions. + Additionally, most pugixml functions have a no-throw exception guarantee. + </p> +<p> + 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. + </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. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.dom.memory"></a><a class="link" href="dom.html#manual.dom.memory" title="Memory management"> Memory management</a> +</h3></div></div></div> +<p> + pugixml requests the memory needed for document storage in big chunks, and + allocates document data inside those chunks. This section discusses replacing + functions used for chunk allocation and internal memory management implementation. + </p> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="manual.dom.memory.custom"></a><a class="link" href="dom.html#manual.dom.memory.custom" title="Custom memory allocation/deallocation functions"> Custom memory allocation/deallocation + 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: + </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> +</pre> +<a name="set_memory_management_functions"></a><a name="get_memory_allocation_function"></a><a name="get_memory_deallocation_function"></a><p> + You can use the following accessor functions to change or get current memory + management functions: + </p> +<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">set_memory_management_functions</span><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> +<span class="identifier">allocation_function</span> <span class="identifier">get_memory_allocation_function</span><span class="special">();</span> +<span class="identifier">deallocation_function</span> <span class="identifier">get_memory_deallocation_function</span><span class="special">();</span> +</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. + </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>): + </p> +<p> + +</p> +<pre class="programlisting"><span class="keyword">void</span><span class="special">*</span> <span class="identifier">custom_allocate</span><span class="special">(</span><span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">return</span> <span class="keyword">new</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">nothrow</span><span class="special">)</span> <span class="keyword">char</span><span class="special">[</span><span class="identifier">size</span><span class="special">];</span> +<span class="special">}</span> + +<span class="keyword">void</span> <span class="identifier">custom_deallocate</span><span class="special">(</span><span class="keyword">void</span><span class="special">*</span> <span class="identifier">ptr</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">delete</span><span class="special">[]</span> <span class="keyword">static_cast</span><span class="special"><</span><span class="keyword">char</span><span class="special">*>(</span><span class="identifier">ptr</span><span class="special">);</span> +<span class="special">}</span> +</pre> +<p> + </p> +<p> + +</p> +<pre class="programlisting"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">set_memory_management_functions</span><span class="special">(</span><span class="identifier">custom_allocate</span><span class="special">,</span> <span class="identifier">custom_deallocate</span><span class="special">);</span> +</pre> +<p> + </p> +<p> + When setting new memory management functions, care must be taken to make + sure that there are no live pugixml objects. Otherwise when the objects + 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"> +<a name="manual.dom.memory.internals"></a><a class="link" href="dom.html#manual.dom.memory.internals" title="Document memory management internals"> Document memory management + internals</a> +</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> + object. + </p> +<p> + When the document is loaded from file/buffer, unless an inplace loading + 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. + </p> +<p> + All additional memory, such as memory for document structure (node/attribute + objects) and memory for node/attribute names/values is allocated in pages + on the order of 32 kilobytes; actual objects are allocated inside the pages + using a memory management scheme optimized for fast allocation/deallocation + of many small objects. Because of the scheme specifics, the pages are only + destroyed if all objects inside them are destroyed; also, generally destroying + an object does not mean that subsequent object creation will reuse the + same memory. This means that it is possible to devise a usage scheme which + will lead to higher memory usage than expected; one example is adding a + lot of nodes, and them removing all even numbered ones; not a single page + is reclaimed in the process. However this is an example specifically crafted + to produce unsatisfying behavior; in all practical usage scenarios the + memory consumption is less than that of a general-purpose allocator because + allocation meta-data is very small in size. + </p> +</div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2010 Arseny Kapoulkine<p> + Distributed under the MIT License + </p> +</div></td> +</tr></table> +<hr> +<table width="100%"><tr> +<td>pugixml 0.9 manual | + <a href="../manual.html">Overview</a> | + <a href="install.html">Installation</a> | + Document: + <b>Object model</b> · <a href="loading.html">Loading</a> · <a href="access.html">Accessing</a> · <a href="modify.html">Modifying</a> · <a href="saving.html">Saving</a> | + <a href="xpath.html">XPath</a> | + <a href="apiref.html">API Reference</a> | + <a href="toc.html">Table of Contents</a> +</td> +<td width="*" align="right"><div class="spirit-nav"> +<a accesskey="p" href="install.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../manual.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../manual.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="loading.html"><img src="../images/next.png" alt="Next"></a> +</div></td> +</tr></table> +</body> +</html> diff --git a/docs/manual/install.html b/docs/manual/install.html new file mode 100644 index 0000000..0c3e94e --- /dev/null +++ b/docs/manual/install.html @@ -0,0 +1,445 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<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="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 | + <a href="../manual.html">Overview</a> | + <b>Installation</b> | + Document: + <a href="dom.html">Object model</a> · <a href="loading.html">Loading</a> · <a href="access.html">Accessing</a> · <a href="modify.html">Modifying</a> · <a href="saving.html">Saving</a> | + <a href="xpath.html">XPath</a> | + <a href="apiref.html">API Reference</a> | + <a href="toc.html">Table of Contents</a> +</td> +<td width="*" align="right"><div class="spirit-nav"> +<a accesskey="p" href="../manual.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../manual.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../manual.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="dom.html"><img src="../images/next.png" alt="Next"></a> +</div></td> +</tr></table> +<hr> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="manual.install"></a><a class="link" href="install.html" title="Installation"> Installation</a> +</h2></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="install.html#manual.install.getting"> Getting pugixml</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="install.html#manual.install.getting.source"> Source distributions</a></span></dt> +<dt><span class="section"><a href="install.html#manual.install.getting.subversion"> Subversion repository</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="install.html#manual.install.building"> Building pugixml</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="install.html#manual.install.building.embed"> Building pugixml as + a part of another static library/executable</a></span></dt> +<dt><span class="section"><a href="install.html#manual.install.building.static"> Building pugixml as + a standalone static library</a></span></dt> +<dt><span class="section"><a href="install.html#manual.install.building.shared"> Building pugixml as + a standalone shared library</a></span></dt> +<dt><span class="section"><a href="install.html#manual.install.building.config"> Additional configuration + options</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="install.html#manual.install.portability"> Portability</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.install.getting"></a><a class="link" href="install.html#manual.install.getting" title="Getting pugixml"> Getting pugixml</a> +</h3></div></div></div> +<p> + pugixml is distributed in source form. You can either download a source distribution + or checkout the Subversion repository. + </p> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="manual.install.getting.source"></a><a class="link" href="install.html#manual.install.getting.source" title="Source distributions"> Source distributions</a> +</h4></div></div></div> +<p> + 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> +<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. + </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 + archive</a>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="manual.install.getting.subversion"></a><a class="link" href="install.html#manual.install.getting.subversion" title="Subversion repository"> Subversion repository</a> +</h4></div></div></div> +<p> + The Subversion repository is located at <a href="http://pugixml.googlecode.com/svn/" target="_top">http://pugixml.googlecode.com/svn/</a>. + There is a Subversion tag "release-{version}" for each version; + also there is the "latest" tag, which always points to the latest + stable release. + </p> +<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> +<p> + To checkout the latest version, you can use this command: + </p> +<pre class="programlisting">svn checkout http://pugixml.googlecode.com/svn/tags/latest pugixml</pre> +<p> + The repository contains library source, documentation, code examples and + full unit test suite. + </p> +<p> + Use latest version tag if you want to automatically get new versions via + <code class="literal">svn update</code>. Use other tags if you want to switch to + new versions only explicitly (for example, using <code class="literal">svn switch</code> + command). Also please note that Subversion trunk contains the work-in-progress + version of the code; while this means that you can get new features and + bug fixes from trunk without waiting for a new release, this also means + that occasionally the code can be broken in some configurations. + </p> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.install.building"></a><a class="link" href="install.html#manual.install.building" title="Building pugixml"> Building pugixml</a> +</h3></div></div></div> +<p> + pugixml is distributed in source form without any pre-built binaries; you + 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; + <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 + 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>) + 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="id1323403" href="#ftn.id1323403" 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. + </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> +<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): + </p> +<div class="informaltable"><table class="table"> +<colgroup><col></colgroup> +<tbody><tr><td> + <p> + <a href="../images/vs2005_pch1.png" target="_top"><span class="inlinemediaobject"><img src="../images/vs2005_pch1_thumb.png" alt="vs2005_pch1_thumb"></span></a> <span class="inlinemediaobject"><img src="../images/next.png" alt="next"></span> <a href="../images/vs2005_pch2.png" target="_top"><span class="inlinemediaobject"><img src="../images/vs2005_pch2_thumb.png" alt="vs2005_pch2_thumb"></span></a> <span class="inlinemediaobject"><img src="../images/next.png" alt="next"></span> <a href="../images/vs2005_pch3.png" target="_top"><span class="inlinemediaobject"><img src="../images/vs2005_pch3_thumb.png" alt="vs2005_pch3_thumb"></span></a> <span class="inlinemediaobject"><img src="../images/next.png" alt="next"></span> <a href="../images/vs2005_pch4.png" target="_top"><span class="inlinemediaobject"><img src="../images/vs2005_pch4_thumb.png" alt="vs2005_pch4_thumb"></span></a> + </p> + </td></tr></tbody> +</table></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="manual.install.building.static"></a><a class="link" href="install.html#manual.install.building.static" title="Building pugixml as a standalone static library"> Building pugixml as + a standalone static library</a> +</h4></div></div></div> +<p> + It's possible to compile pugixml as a standalone static library. This process + depends on the method of building your application; pugixml distribution + comes with project files for several popular IDEs/build systems. There + are project files for Apple XCode3, Code::Blocks, Codelite, Microsoft Visual + Studio 2005, 2008, 2010, and configuration scripts for CMake and premake4. + You're welcome to submit project files/build scripts for other software; + see <a class="xref" href="../manual.html#manual.overview.feedback" title="Feedback"> Feedback</a>. + </p> +<p> + There are two projects for each version of Microsoft Visual Studio: one + for dynamically linked CRT, which has a name like <code class="filename">pugixml_vs2008.vcproj</code>, + and another one for statically linked CRT, which has a name like <code class="filename">pugixml_vs2008_static.vcproj</code>. + You should select the version that matches the CRT used in your application; + the default option for new projects created by Microsoft Visual Studio + is dynamically linked CRT, so unless you changed the defaults, you should + use the version with dynamic CRT (i.e. <code class="filename">pugixml_vs2008.vcproj</code> for Microsoft + Visual Studio 2008). + </p> +<p> + In addition to adding pugixml project to your workspace, you'll have to + make sure that your application links with pugixml library. If you're using + Microsoft Visual Studio 2005/2008, you can add a dependency from your application + project to pugixml one. If you're using Microsoft Visual Studio 2010, you'll + have to add a reference to your application project instead. For other + IDEs/systems, consult the relevant documentation. + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Microsoft Visual Studio 2005/2008 + </p> + </th> +<th> + <p> + Microsoft Visual Studio 2010 + </p> + </th> +</tr></thead> +<tbody><tr> +<td> + <p> + <a href="../images/vs2005_link1.png" target="_top"><span class="inlinemediaobject"><img src="../images/vs2005_link1_thumb.png" alt="vs2005_link1_thumb"></span></a> <span class="inlinemediaobject"><img src="../images/next.png" alt="next"></span> <a href="../images/vs2005_link2.png" target="_top"><span class="inlinemediaobject"><img src="../images/vs2005_link2_thumb.png" alt="vs2005_link2_thumb"></span></a> + </p> + </td> +<td> + <p> + <a href="../images/vs2010_link1.png" target="_top"><span class="inlinemediaobject"><img src="../images/vs2010_link1_thumb.png" alt="vs2010_link1_thumb"></span></a> <span class="inlinemediaobject"><img src="../images/next.png" alt="next"></span> <a href="../images/vs2010_link2.png" target="_top"><span class="inlinemediaobject"><img src="../images/vs2010_link2_thumb.png" alt="vs2010_link2_thumb"></span></a> + </p> + </td> +</tr></tbody> +</table></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="manual.install.building.shared"></a><a class="link" href="install.html#manual.install.building.shared" title="Building pugixml as a standalone shared library"> Building pugixml as + a standalone shared library</a> +</h4></div></div></div> +<p> + It's possible to compile pugixml as a standalone shared library. The process + is usually similar to the static library approach; however, no preconfigured + projects/scripts are included into pugixml distribution, so you'll have + to do it yourself. Generally, if you're using GCC-based toolchain, the + 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> + macro, i.e. via <code class="filename">pugiconfig.hpp</code>: + </p> +<pre class="programlisting"><span class="preprocessor">#ifdef</span> <span class="identifier">_DLL</span> +<span class="preprocessor">#define</span> <span class="identifier">PUGIXML_API</span> <span class="identifier">__declspec</span><span class="special">(</span><span class="identifier">dllexport</span><span class="special">)</span> +<span class="preprocessor">#else</span> +<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> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="manual.install.building.config"></a><a class="link" href="install.html#manual.install.building.config" title="Additional configuration options"> Additional configuration + options</a> +</h4></div></div></div> +<p> + 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. + </p> +<p> + <a name="PUGIXML_WCHAR_MODE"></a><code class="literal">PUGIXML_WCHAR_MODE</code> define toggles + between UTF-8 style interface (the in-memory text encoding is assumed to + be UTF-8, most functions use <code class="computeroutput"><span class="keyword">char</span></code> + as character type) and UTF-16/32 style interface (the in-memory text encoding + is assumed to be UTF-16/32, depending on <code class="computeroutput"><span class="keyword">wchar_t</span></code> + size, most functions use <code class="computeroutput"><span class="keyword">wchar_t</span></code> + as character type). See <a class="xref" href="dom.html#manual.dom.unicode" title="Unicode interface"> Unicode interface</a> for more details. + </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. + </p> +<p> + <a name="PUGIXML_NO_STL"></a><code class="literal">PUGIXML_NO_STL</code> define disables use of + STL in pugixml. The functions that operate on STL types are no longer present + (i.e. load/save via iostream) if this macro is defined. This option is + 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 + </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 + specify custom attributes (i.e. declspec or calling conventions) for pugixml + classes and non-member functions. In absence of <code class="computeroutput"><span class="identifier">PUGIXML_CLASS</span></code> + or <code class="computeroutput"><span class="identifier">PUGIXML_FUNCTION</span></code> definitions, + <code class="computeroutput"><span class="identifier">PUGIXML_API</span></code> definition + is used instead. For example, to specify fixed calling convention, you + can define <code class="computeroutput"><span class="identifier">PUGIXML_FUNCTION</span></code> + to i.e. <code class="computeroutput"><span class="identifier">__fastcall</span></code>. Another + example is DLL import/export attributes in MSVC (see <a class="xref" href="install.html#manual.install.building.shared" title="Building pugixml as a standalone shared library"> Building pugixml as + a standalone shared library</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> + In that example <code class="computeroutput"><span class="identifier">PUGIXML_API</span></code> + is inconsistent between several source files; this is an exception to + the consistency rule. + </p></td></tr> +</table></div> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.install.portability"></a><a class="link" href="install.html#manual.install.portability" title="Portability"> Portability</a> +</h3></div></div></div> +<p> + pugixml is written in standard-compliant C++ with some compiler-specific + workarounds where appropriate. pugixml is compatible with the upcoming C++0x + standard (verified using GCC 4.5). Each version is tested with a unit test + suite (with code coverage about 99%) on the following platforms: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Microsoft Windows: + <div class="itemizedlist"><ul class="itemizedlist" type="circle"> +<li class="listitem"> + Borland C++ Compiler 5.82 + </li> +<li class="listitem"> + Digital Mars C++ Compiler 8.51 + </li> +<li class="listitem"> + Intel C++ Compiler 8.0, 9.0 x86/x64, 10.0 x86/x64, 11.0 x86/x64 + </li> +<li class="listitem"> + Metrowerks CodeWarrior 8.0 + </li> +<li class="listitem"> + Microsoft Visual C++ 6.0, 7.0 (2002), 7.1 (2003), 8.0 (2005) x86/x64, + 9.0 (2008) x86/x64, 10.0 (2010) x86/x64 + </li> +<li class="listitem"> + MinGW (GCC) 3.4, 4.4, 4.5, 4.6 x64 + </li> +</ul></div> + </li> +<li class="listitem"> + Linux (GCC 4.4.3 x86/x64) + </li> +<li class="listitem"> + FreeBSD (GCC 4.2.1 x86/x64) + </li> +<li class="listitem"> + Apple MacOSX (GCC 4.0.1 x86/x64/PowerPC) + </li> +<li class="listitem"> + Microsoft Xbox 360 + </li> +<li class="listitem"> + Nintendo Wii (Metrowerks CodeWarrior 4.1) + </li> +<li class="listitem"> + Sony Playstation Portable (GCC 3.4.2) + </li> +<li class="listitem"> + Sony Playstation 3 (GCC 4.1.1, SNC 310.1) + </li> +</ul></div> +</div> +<div class="footnotes"> +<br><hr width="100" align="left"> +<div class="footnote"><p><sup>[<a name="ftn.id1323403" href="#id1323403" 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"></td> +<td align="right"><div class="copyright-footer">Copyright © 2010 Arseny Kapoulkine<p> + Distributed under the MIT License + </p> +</div></td> +</tr></table> +<hr> +<table width="100%"><tr> +<td>pugixml 0.9 manual | + <a href="../manual.html">Overview</a> | + <b>Installation</b> | + Document: + <a href="dom.html">Object model</a> · <a href="loading.html">Loading</a> · <a href="access.html">Accessing</a> · <a href="modify.html">Modifying</a> · <a href="saving.html">Saving</a> | + <a href="xpath.html">XPath</a> | + <a href="apiref.html">API Reference</a> | + <a href="toc.html">Table of Contents</a> +</td> +<td width="*" align="right"><div class="spirit-nav"> +<a accesskey="p" href="../manual.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../manual.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../manual.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="dom.html"><img src="../images/next.png" alt="Next"></a> +</div></td> +</tr></table> +</body> +</html> diff --git a/docs/manual/loading.html b/docs/manual/loading.html new file mode 100644 index 0000000..a3c1515 --- /dev/null +++ b/docs/manual/loading.html @@ -0,0 +1,840 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<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="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 | + <a href="../manual.html">Overview</a> | + <a href="install.html">Installation</a> | + Document: + <a href="dom.html">Object model</a> · <b>Loading</b> · <a href="access.html">Accessing</a> · <a href="modify.html">Modifying</a> · <a href="saving.html">Saving</a> | + <a href="xpath.html">XPath</a> | + <a href="apiref.html">API Reference</a> | + <a href="toc.html">Table of Contents</a> +</td> +<td width="*" align="right"><div class="spirit-nav"> +<a accesskey="p" href="dom.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../manual.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../manual.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="access.html"><img src="../images/next.png" alt="Next"></a> +</div></td> +</tr></table> +<hr> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="manual.loading"></a><a class="link" href="loading.html" title="Loading document"> Loading document</a> +</h2></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="loading.html#manual.loading.file"> Loading document from file</a></span></dt> +<dt><span class="section"><a href="loading.html#manual.loading.memory"> Loading document from memory</a></span></dt> +<dt><span class="section"><a href="loading.html#manual.loading.stream"> Loading document from C++ IOstreams</a></span></dt> +<dt><span class="section"><a href="loading.html#manual.loading.errors"> Handling parsing errors</a></span></dt> +<dt><span class="section"><a href="loading.html#manual.loading.options"> Parsing options</a></span></dt> +<dt><span class="section"><a href="loading.html#manual.loading.encoding"> Encodings</a></span></dt> +<dt><span class="section"><a href="loading.html#manual.loading.w3c"> Conformance to W3C specification</a></span></dt> +</dl></div> +<p> + pugixml provides several functions for loading XML data from various places + - files, C++ iostreams, memory buffers. All functions use an extremely fast + 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 + more information. + </p> +<p> + XML data is always converted to internal character format (see <a class="xref" href="dom.html#manual.dom.unicode" title="Unicode interface"> Unicode interface</a>) + before parsing. pugixml supports all popular Unicode encodings (UTF-8, UTF-16 + (big and little endian), UTF-32 (big and little endian); UCS-2 is naturally + supported since it's a strict subset of UTF-16) and handles all encoding conversions + automatically. Unless explicit encoding is specified, loading functions perform + automatic encoding detection based on first few characters of XML data, so + in almost all cases you do not have to specify document encoding. Encoding + conversion is described in more detail in <a class="xref" href="loading.html#manual.loading.encoding" title="Encodings"> Encodings</a>. + </p> +<div class="section"> +<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: + </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> +</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 + 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. + </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 + (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> +<p> + +</p> +<pre class="programlisting"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_document</span> <span class="identifier">doc</span><span class="special">;</span> + +<span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_parse_result</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">load_file</span><span class="special">(</span><span class="string">"tree.xml"</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">"Load result: "</span> <span class="special"><<</span> <span class="identifier">result</span><span class="special">.</span><span class="identifier">description</span><span class="special">()</span> <span class="special"><<</span> <span class="string">", mesh name: "</span> <span class="special"><<</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">child</span><span class="special">(</span><span class="string">"mesh"</span><span class="special">).</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"name"</span><span class="special">).</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> +</pre> +<p> + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<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. + 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 + from memory. First you should prepare a contiguous memory block with all + XML data; then you have to invoke one of buffer loading functions. These + functions will handle the necessary encoding conversions, if any, and then + will parse the data into the corresponding XML tree. There are several buffer + loading functions, which differ in the behavior and thus in performance/memory + usage: + </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_buffer</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">void</span><span class="special">*</span> <span class="identifier">contents</span><span class="special">,</span> <span class="identifier">size_t</span> <span class="identifier">size</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_buffer_inplace</span><span class="special">(</span><span class="keyword">void</span><span class="special">*</span> <span class="identifier">contents</span><span class="special">,</span> <span class="identifier">size_t</span> <span class="identifier">size</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_buffer_inplace_own</span><span class="special">(</span><span class="keyword">void</span><span class="special">*</span> <span class="identifier">contents</span><span class="special">,</span> <span class="identifier">size_t</span> <span class="identifier">size</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> + All functions accept the buffer which is represented by a pointer to XML + data, <code class="computeroutput"><span class="identifier">contents</span></code>, and data + size in bytes. Also there are 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 buffer does not have to be zero-terminated. + </p> +<p> + <code class="computeroutput"><span class="identifier">load_buffer</span></code> function works + with immutable buffer - it does not ever modify the buffer. Because of this + restriction it has to create a private buffer and copy XML data to it before + parsing (applying encoding conversions if necessary). This copy operation + carries a performance penalty, so inplace functions are provided - <code class="computeroutput"><span class="identifier">load_buffer_inplace</span></code> and <code class="computeroutput"><span class="identifier">load_buffer_inplace_own</span></code> + store the document data in the buffer, modifying it in the process. In order + for the document to stay valid, you have to make sure that the buffer's lifetime + exceeds that of the tree if you're using inplace functions. In addition to + that, <code class="computeroutput"><span class="identifier">load_buffer_inplace</span></code> + does not assume ownership of the buffer, so you'll have to destroy it yourself; + <code class="computeroutput"><span class="identifier">load_buffer_inplace_own</span></code> assumes + ownership of the buffer and destroys it once it is not needed. This means + that if you're using <code class="computeroutput"><span class="identifier">load_buffer_inplace_own</span></code>, + you have to allocate memory with pugixml allocation function (you can get + it via <a class="link" href="dom.html#get_memory_allocation_function">get_memory_allocation_function</a>). + </p> +<p> + The best way from the performance/memory point of view is to load document + using <code class="computeroutput"><span class="identifier">load_buffer_inplace_own</span></code>; + this function has maximum control of the buffer with XML data so it is able + to avoid redundant copies and reduce peak memory usage while parsing. This + is the recommended function if you have to load the document from memory + and performance is critical. + </p> +<a name="xml_document::load_string"></a><p> + There is also a simple helper function for cases when you want to load the + XML document from null-terminated character string: + </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</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">contents</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> +</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. + </p> +<p> + This is an example of loading XML document from memory using different functions + (<a href="../samples/load_memory.cpp" target="_top">samples/load_memory.cpp</a>): + </p> +<p> + +</p> +<pre class="programlisting"><span class="keyword">const</span> <span class="keyword">char</span> <span class="identifier">source</span><span class="special">[]</span> <span class="special">=</span> <span class="string">"<mesh name='sphere'><bounds>0 0 1 1</bounds></mesh>"</span><span class="special">;</span> +<span class="identifier">size_t</span> <span class="identifier">size</span> <span class="special">=</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">source</span><span class="special">);</span> +</pre> +<p> + </p> +<p> + +</p> +<pre class="programlisting"><span class="comment">// You can use load_buffer to load document from immutable memory block: +</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_parse_result</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">load_buffer</span><span class="special">(</span><span class="identifier">source</span><span class="special">,</span> <span class="identifier">size</span><span class="special">);</span> +</pre> +<p> + </p> +<p> + +</p> +<pre class="programlisting"><span class="comment">// You can use load_buffer_inplace to load document from mutable memory block; the block's lifetime must exceed that of document +</span><span class="keyword">char</span><span class="special">*</span> <span class="identifier">buffer</span> <span class="special">=</span> <span class="keyword">new</span> <span class="keyword">char</span><span class="special">[</span><span class="identifier">size</span><span class="special">];</span> +<span class="identifier">memcpy</span><span class="special">(</span><span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">source</span><span class="special">,</span> <span class="identifier">size</span><span class="special">);</span> + +<span class="comment">// The block can be allocated by any method; the block is modified during parsing +</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_parse_result</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">load_buffer_inplace</span><span class="special">(</span><span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">size</span><span class="special">);</span> + +<span class="comment">// You have to destroy the block yourself after the document is no longer used +</span><span class="keyword">delete</span><span class="special">[]</span> <span class="identifier">buffer</span><span class="special">;</span> +</pre> +<p> + </p> +<p> + +</p> +<pre class="programlisting"><span class="comment">// You can use load_buffer_inplace_own to load document from mutable memory block and to pass the ownership of this block +</span><span class="comment">// The block has to be allocated via pugixml allocation function - using i.e. operator new here is incorrect +</span><span class="keyword">char</span><span class="special">*</span> <span class="identifier">buffer</span> <span class="special">=</span> <span class="keyword">static_cast</span><span class="special"><</span><span class="keyword">char</span><span class="special">*>(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">get_memory_allocation_function</span><span class="special">()(</span><span class="identifier">size</span><span class="special">));</span> +<span class="identifier">memcpy</span><span class="special">(</span><span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">source</span><span class="special">,</span> <span class="identifier">size</span><span class="special">);</span> + +<span class="comment">// The block will be deleted by the document +</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_parse_result</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">load_buffer_inplace_own</span><span class="special">(</span><span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">size</span><span class="special">);</span> +</pre> +<p> + </p> +<p> + +</p> +<pre class="programlisting"><span class="comment">// You can use load to load document from null-terminated strings, for example literals: +</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_parse_result</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">load</span><span class="special">(</span><span class="string">"<mesh name='sphere'><bounds>0 0 1 1</bounds></mesh>"</span><span class="special">);</span> +</pre> +<p> + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<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 + 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 + Iostreams). There are two functions, one works with narrow character streams, + another handles wide character ones: + </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</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">istream</span><span class="special">&</span> <span class="identifier">stream</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</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">wistream</span><span class="special">&</span> <span class="identifier">stream</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> +</pre> +<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">istream</span></code> + argument loads the document from stream from the current read position to + the end, treating the stream contents as a byte stream of the specified encoding + (with encoding autodetection as necessary). Thus calling <code class="computeroutput"><span class="identifier">xml_document</span><span class="special">::</span><span class="identifier">load</span></code> + on an opened <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ifstream</span></code> object is equivalent to calling + <code class="computeroutput"><span class="identifier">xml_document</span><span class="special">::</span><span class="identifier">load_file</span></code>. + </p> +<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> + 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. + </p> +<p> + This is a simple example of loading XML document from file using streams + (<a href="../samples/load_stream.cpp" target="_top">samples/load_stream.cpp</a>); read + the sample code for more complex examples involving wide streams and locales: + </p> +<p> + +</p> +<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ifstream</span> <span class="identifier">stream</span><span class="special">(</span><span class="string">"weekly-utf-8.xml"</span><span class="special">);</span> +<span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_parse_result</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">load</span><span class="special">(</span><span class="identifier">stream</span><span class="special">);</span> +</pre> +<p> + </p> +<p> + Stream loading requires working seek/tell functions and therefore may fail + when used with some stream implementations like gzstream. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.loading.errors"></a><a class="link" href="loading.html#manual.loading.errors" title="Handling parsing errors"> Handling parsing errors</a> +</h3></div></div></div> +<a name="xml_parse_result"></a><p> + All document loading functions return the parsing result via <code class="computeroutput"><span class="identifier">xml_parse_result</span></code> object. It contains parsing + status, the offset of last successfully parsed character from the beginning + of the source stream, and the encoding of the source stream: + </p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">xml_parse_result</span> +<span class="special">{</span> + <span class="identifier">xml_parse_status</span> <span class="identifier">status</span><span class="special">;</span> + <span class="identifier">ptrdiff_t</span> <span class="identifier">offset</span><span class="special">;</span> + <span class="identifier">xml_encoding</span> <span class="identifier">encoding</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="xml_parse_status"></a><a name="xml_parse_result::status"></a><p> + Parsing status is represented as the <code class="computeroutput"><span class="identifier">xml_parse_status</span></code> + enumeration and can be one of the following: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + <a name="status_ok"></a><code class="literal">status_ok</code> means that no error was encountered + during parsing; the source stream represents the valid XML document which + was fully parsed and converted to a tree. <br><br> + + </li> +<li class="listitem"> + <a name="status_file_not_found"></a><code class="literal">status_file_not_found</code> is only + returned by <code class="computeroutput"><span class="identifier">load_file</span></code> + function and means that file could not be opened. + </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. + </li> +<li class="listitem"> + <a name="status_out_of_memory"></a><code class="literal">status_out_of_memory</code> means that + there was not enough memory during some allocation; any allocation failure + during parsing results in this error. + </li> +<li class="listitem"> + <a name="status_internal_error"></a><code class="literal">status_internal_error</code> means that + something went horribly wrong; currently this error does not occur <br><br> + + </li> +<li class="listitem"> + <a name="status_unrecognized_tag"></a><code class="literal">status_unrecognized_tag</code> means + that parsing stopped due to a tag with either an empty name or a name + which starts with incorrect character, such as <code class="literal">#</code>. + </li> +<li class="listitem"> + <a name="status_bad_pi"></a><code class="literal">status_bad_pi</code> means that parsing stopped + due to incorrect document declaration/processing instruction + </li> +<li class="listitem"> + <a name="status_bad_comment"></a><code class="literal">status_bad_comment</code>, <a name="status_bad_cdata"></a><code class="literal">status_bad_cdata</code>, + <a name="status_bad_doctype"></a><code class="literal">status_bad_doctype</code> and <a name="status_bad_pcdata"></a><code class="literal">status_bad_pcdata</code> + mean that parsing stopped due to the invalid construct of the respective + type + </li> +<li class="listitem"> + <a name="status_bad_start_element"></a><code class="literal">status_bad_start_element</code> means + that parsing stopped because starting tag either had no closing <code class="computeroutput"><span class="special">></span></code> symbol or contained some incorrect + symbol + </li> +<li class="listitem"> + <a name="status_bad_attribute"></a><code class="literal">status_bad_attribute</code> means that + parsing stopped because there was an incorrect attribute, such as an + attribute without value or with value that is not quoted (note that + <code class="computeroutput"><span class="special"><</span><span class="identifier">node</span> + <span class="identifier">attr</span><span class="special">=</span><span class="number">1</span><span class="special">></span></code> is + incorrect in XML) + </li> +<li class="listitem"> + <a name="status_bad_end_element"></a><code class="literal">status_bad_end_element</code> means + that parsing stopped because ending tag had incorrect syntax (i.e. extra + non-whitespace symbols between tag name and <code class="computeroutput"><span class="special">></span></code>) + </li> +<li class="listitem"> + <a name="status_end_element_mismatch"></a><code class="literal">status_end_element_mismatch</code> + means that parsing stopped because the closing tag did not match the + opening one (i.e. <code class="computeroutput"><span class="special"><</span><span class="identifier">node</span><span class="special">></</span><span class="identifier">nedo</span><span class="special">></span></code>) or because some tag was not closed + at all + </li> +</ul></div> +<a name="xml_parse_result::description"></a><p> + <code class="computeroutput"><span class="identifier">description</span><span class="special">()</span></code> + member function can be used to convert parsing status to a string; the returned + message is always in English, so you'll have to write your own function if + you need a localized string. However please note that the exact messages + returned by <code class="computeroutput"><span class="identifier">description</span><span class="special">()</span></code> + function may change from version to version, so any complex status handling + should be based on <code class="computeroutput"><span class="identifier">status</span></code> + value. + </p> +<p> + If parsing failed because the source data was not a valid XML, the resulting + tree is not destroyed - despite the fact that load function returns error, + you can use the part of the tree that was successfully parsed. Obviously, + the last element may have an unexpected name/value; for example, if the attribute + value does not end with the necessary quotation mark, like in <code class="literal"><node + attr="value>some data</node></code> example, the value of + attribute <code class="computeroutput"><span class="identifier">attr</span></code> will contain + the string <code class="computeroutput"><span class="identifier">value</span><span class="special">></span><span class="identifier">some</span> <span class="identifier">data</span><span class="special"></</span><span class="identifier">node</span><span class="special">></span></code>. + </p> +<a name="xml_parse_result::offset"></a><p> + In addition to the status code, parsing result has an <code class="computeroutput"><span class="identifier">offset</span></code> + 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). + </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> + Offset is calculated in the XML buffer in native encoding; if encoding + conversion is performed during parsing, offset can not be used to reliably + track the error position. + </p></td></tr> +</table></div> +<a name="xml_parse_result::encoding"></a><p> + Parsing result also has an <code class="computeroutput"><span class="identifier">encoding</span></code> + member, which can be used to check that the source data encoding was correctly + guessed. It is equal to the exact encoding used during parsing (i.e. with + the exact endianness); see <a class="xref" href="loading.html#manual.loading.encoding" title="Encodings"> Encodings</a> for more information. + </p> +<a name="xml_parse_result::bool"></a><p> + Parsing result object can be implicitly converted to <code class="computeroutput"><span class="keyword">bool</span></code>; + if you do not want to handle parsing errors thoroughly, you can just check + the return value of load functions as if it was a <code class="computeroutput"><span class="keyword">bool</span></code>: + <code class="computeroutput"><span class="keyword">if</span> <span class="special">(</span><span class="identifier">doc</span><span class="special">.</span><span class="identifier">load_file</span><span class="special">(</span><span class="string">"file.xml"</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 handling loading errors (<a href="../samples/load_error_handling.cpp" target="_top">samples/load_error_handling.cpp</a>): + </p> +<p> + +</p> +<pre class="programlisting"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_document</span> <span class="identifier">doc</span><span class="special">;</span> +<span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_parse_result</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">load</span><span class="special">(</span><span class="identifier">source</span><span class="special">);</span> + +<span class="keyword">if</span> <span class="special">(</span><span class="identifier">result</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">"XML ["</span> <span class="special"><<</span> <span class="identifier">source</span> <span class="special"><<</span> <span class="string">"] parsed without errors, attr value: ["</span> <span class="special"><<</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">child</span><span class="special">(</span><span class="string">"node"</span><span class="special">).</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"attr"</span><span class="special">).</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"]\n\n"</span><span class="special">;</span> +<span class="keyword">else</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">"XML ["</span> <span class="special"><<</span> <span class="identifier">source</span> <span class="special"><<</span> <span class="string">"] parsed with errors, attr value: ["</span> <span class="special"><<</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">child</span><span class="special">(</span><span class="string">"node"</span><span class="special">).</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"attr"</span><span class="special">).</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"]\n"</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">"Error description: "</span> <span class="special"><<</span> <span class="identifier">result</span><span class="special">.</span><span class="identifier">description</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"\n"</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">"Error offset: "</span> <span class="special"><<</span> <span class="identifier">result</span><span class="special">.</span><span class="identifier">offset</span> <span class="special"><<</span> <span class="string">" (error at [..."</span> <span class="special"><<</span> <span class="special">(</span><span class="identifier">source</span> <span class="special">+</span> <span class="identifier">result</span><span class="special">.</span><span class="identifier">offset</span><span class="special">)</span> <span class="special"><<</span> <span class="string">"]\n\n"</span><span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.loading.options"></a><a class="link" href="loading.html#manual.loading.options" title="Parsing options"> Parsing options</a> +</h3></div></div></div> +<p> + All document loading functions accept the optional parameter <code class="computeroutput"><span class="identifier">options</span></code>. This is a bitmask that customizes + the parsing process: you can select the node types that are parsed and various + transformations that are performed with the XML text. Disabling certain transformations + can improve parsing performance for some documents; however, the code for + all transformations is very well optimized, and thus the majority of documents + won't get any performance benefit. As a rule of thumb, only modify parsing + flags if you want to get some nodes in the document that are excluded by + default (i.e. declaration or comment nodes). + </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 should use the usual bitwise arithmetics to manipulate the bitmask: + to enable a flag, use <code class="computeroutput"><span class="identifier">mask</span> <span class="special">|</span> <span class="identifier">flag</span></code>; + to disable a flag, use <code class="computeroutput"><span class="identifier">mask</span> <span class="special">&</span> <span class="special">~</span><span class="identifier">flag</span></code>. + </p></td></tr> +</table></div> +<p> + These flags control the resulting tree contents: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<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> + + </li> +<li class="listitem"> + <a name="parse_pi"></a><code class="literal">parse_pi</code> determines if processing instructions + (nodes with type <a class="link" href="dom.html#node_pi">node_pi</a>) are to be put + in DOM tree. If this flag is off, they are not put in the tree, but are + still parsed and checked for correctness. Note that <code class="computeroutput"><span class="special"><?</span><span class="identifier">xml</span> <span class="special">...?></span></code> + (document declaration) is not considered to be a PI. This flag is <span class="bold"><strong>off</strong></span> by default. <br><br> + + </li> +<li class="listitem"> + <a name="parse_comments"></a><code class="literal">parse_comments</code> determines if comments + (nodes with type <a class="link" href="dom.html#node_comment">node_comment</a>) are + to be put in DOM tree. If this flag is off, they are not put in the tree, + but are 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_cdata"></a><code class="literal">parse_cdata</code> determines if CDATA sections + (nodes with type <a class="link" href="dom.html#node_cdata">node_cdata</a>) are to + be put in DOM tree. If this flag is off, they are not put in the tree, + but are still parsed and checked for correctness. This flag is <span class="bold"><strong>on</strong></span> by default. <br><br> + + </li> +<li class="listitem"> + <a name="parse_ws_pcdata"></a><code class="literal">parse_ws_pcdata</code> determines if PCDATA + nodes (nodes with type <a class="link" href="dom.html#node_pcdata">node_pcdata</a>) + that consist only of whitespace characters are to be put in DOM tree. + Often whitespace-only data is not significant for the application, and + 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> + 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> + is not set. This flag is <span class="bold"><strong>off</strong></span> by default. + </li> +</ul></div> +<p> + These flags control the transformation of tree element contents: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + <a name="parse_escapes"></a><code class="literal">parse_escapes</code> determines if character + and entity references are to be expanded during the parsing process. + Character references have the form <code class="literal">&#...;</code> or + <code class="literal">&#x...;</code> (<code class="literal">...</code> is Unicode numeric + representation of character in either decimal (<code class="literal">&#...;</code>) + or hexadecimal (<code class="literal">&#x...;</code>) form), entity references + are <code class="literal">&lt;</code>, <code class="literal">&gt;</code>, <code class="literal">&amp;</code>, + <code class="literal">&apos;</code> and <code class="literal">&quot;</code> (note + 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> + + </li> +<li class="listitem"> + <a name="parse_eol"></a><code class="literal">parse_eol</code> determines if EOL handling (that + is, replacing sequences <code class="computeroutput"><span class="number">0x0d</span> <span class="number">0x0a</span></code> by a single <code class="computeroutput"><span class="number">0x0a</span></code> + character, and replacing all standalone <code class="computeroutput"><span class="number">0x0d</span></code> + characters by <code class="computeroutput"><span class="number">0x0a</span></code>) is to + be performed on input data (that is, comments contents, PCDATA/CDATA + contents and attribute values). This flag is <span class="bold"><strong>on</strong></span> + by default. <br><br> + + </li> +<li class="listitem"> + <a name="parse_wconv_attribute"></a><code class="literal">parse_wconv_attribute</code> determines + 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> + 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> + by default. <br><br> + + </li> +<li class="listitem"> + <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> + 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> + has no effect if this flag is on. This flag is <span class="bold"><strong>off</strong></span> + by default. + </li> +</ul></div> +<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> + <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> + 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> + is the default option. + </p></td></tr> +</table></div> +<p> + Additionally there are two 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> + + </li> +<li class="listitem"> + <a name="parse_default"></a><code class="literal">parse_default</code> is the default set of flags, + i.e. it has all options set to their default values. It includes parsing + CDATA sections (comments/PIs are not parsed), 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 (by default) + for performance reasons. + </li> +</ul></div> +<p> + This is an example of using different parsing options (<a href="../samples/load_options.cpp" target="_top">samples/load_options.cpp</a>): + </p> +<p> + +</p> +<pre class="programlisting"><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">source</span> <span class="special">=</span> <span class="string">"<!--comment--><node>&lt;</node>"</span><span class="special">;</span> + +<span class="comment">// Parsing with default options; note that comment node is not added to the tree, and entity reference &lt; is expanded +</span><span class="identifier">doc</span><span class="special">.</span><span class="identifier">load</span><span class="special">(</span><span class="identifier">source</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">"First node value: ["</span> <span class="special"><<</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">first_child</span><span class="special">().</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"], node child value: ["</span> <span class="special"><<</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">child_value</span><span class="special">(</span><span class="string">"node"</span><span class="special">)</span> <span class="special"><<</span> <span class="string">"]\n"</span><span class="special">;</span> + +<span class="comment">// Parsing with additional parse_comments option; comment node is now added to the tree +</span><span class="identifier">doc</span><span class="special">.</span><span class="identifier">load</span><span class="special">(</span><span class="identifier">source</span><span class="special">,</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">parse_default</span> <span class="special">|</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">parse_comments</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">"First node value: ["</span> <span class="special"><<</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">first_child</span><span class="special">().</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"], node child value: ["</span> <span class="special"><<</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">child_value</span><span class="special">(</span><span class="string">"node"</span><span class="special">)</span> <span class="special"><<</span> <span class="string">"]\n"</span><span class="special">;</span> + +<span class="comment">// Parsing with additional parse_comments option and without the (default) parse_escapes option; &lt; is not expanded +</span><span class="identifier">doc</span><span class="special">.</span><span class="identifier">load</span><span class="special">(</span><span class="identifier">source</span><span class="special">,</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">parse_default</span> <span class="special">|</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">parse_comments</span><span class="special">)</span> <span class="special">&</span> <span class="special">~</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">parse_escapes</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">"First node value: ["</span> <span class="special"><<</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">first_child</span><span class="special">().</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"], node child value: ["</span> <span class="special"><<</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">child_value</span><span class="special">(</span><span class="string">"node"</span><span class="special">)</span> <span class="special"><<</span> <span class="string">"]\n"</span><span class="special">;</span> + +<span class="comment">// Parsing with minimal option mask; comment node is not added to the tree, and &lt; is not expanded +</span><span class="identifier">doc</span><span class="special">.</span><span class="identifier">load</span><span class="special">(</span><span class="identifier">source</span><span class="special">,</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">parse_minimal</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">"First node value: ["</span> <span class="special"><<</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">first_child</span><span class="special">().</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"], node child value: ["</span> <span class="special"><<</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">child_value</span><span class="special">(</span><span class="string">"node"</span><span class="special">)</span> <span class="special"><<</span> <span class="string">"]\n"</span><span class="special">;</span> +</pre> +<p> + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.loading.encoding"></a><a class="link" href="loading.html#manual.loading.encoding" title="Encodings"> Encodings</a> +</h3></div></div></div> +<a name="xml_encoding"></a><p> + pugixml supports all popular Unicode encodings (UTF-8, UTF-16 (big and little + endian), UTF-32 (big and little endian); UCS-2 is naturally supported since + it's a strict subset of UTF-16) and handles all encoding conversions. Most + loading functions accept the optional parameter <code class="computeroutput"><span class="identifier">encoding</span></code>. + This is a value of enumeration type <code class="computeroutput"><span class="identifier">xml_encoding</span></code>, + that can have the following values: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + <a name="encoding_auto"></a><code class="literal">encoding_auto</code> means that pugixml will + try to guess the encoding based on source XML data. The algorithm is + a modified version of the one presented in Appendix F.1 of XML recommendation; + it tries to match the first few bytes of input data with the following + patterns in strict order: <br><br> + <div class="itemizedlist"><ul class="itemizedlist" type="circle"> +<li class="listitem"> + If first four bytes match UTF-32 BOM (Byte Order Mark), encoding + is assumed to be UTF-32 with the endianness equal to that of BOM; + </li> +<li class="listitem"> + If first two bytes match UTF-16 BOM, encoding is assumed to be + UTF-16 with the endianness equal to that of BOM; + </li> +<li class="listitem"> + If first three bytes match UTF-8 BOM, encoding is assumed to be + UTF-8; + </li> +<li class="listitem"> + If first four bytes match UTF-32 representation of <code class="literal"><</code>, + encoding is assumed to be UTF-32 with the corresponding endianness; + </li> +<li class="listitem"> + If first four bytes match UTF-16 representation of <code class="literal"><?</code>, + encoding is assumed to be UTF-16 with the corresponding endianness; + </li> +<li class="listitem"> + If first two bytes match UTF-16 representation of <code class="literal"><</code>, + encoding is assumed to be UTF-16 with the corresponding endianness + (this guess may yield incorrect result, but it's better than UTF-8); + </li> +<li class="listitem"> + Otherwise encoding is assumed to be UTF-8. <br><br> + + </li> +</ul></div> + </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. + </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 + 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 + 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. + </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. + </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. + </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. + </li> +<li class="listitem"> + <a name="encoding_wchar"></a><code class="literal">encoding_wchar</code> corresponds to the encoding + of <code class="computeroutput"><span class="keyword">wchar_t</span></code> type; it has + the same meaning as either <code class="computeroutput"><span class="identifier">encoding_utf16</span></code> + or <code class="computeroutput"><span class="identifier">encoding_utf32</span></code>, depending + on <code class="computeroutput"><span class="keyword">wchar_t</span></code> size. + </li> +</ul></div> +<p> + The algorithm used for <code class="computeroutput"><span class="identifier">encoding_auto</span></code> + correctly detects any supported Unicode encoding for all well-formed XML + documents (since they start with document declaration) and for all other + XML documents that start with <code class="literal"><</code>; if your XML document + does not start with <code class="literal"><</code> and has encoding that is different + from UTF-8, use the specific encoding. + </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 current behavior for Unicode conversion is to skip all invalid UTF + sequences during conversion. This behavior should not be relied upon; moreover, + in case no encoding conversion is performed, the invalid sequences are + not removed, so you'll get them as is in node/attribute contents. + </p></td></tr> +</table></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.loading.w3c"></a><a class="link" href="loading.html#manual.loading.w3c" title="Conformance to W3C specification"> Conformance to W3C specification</a> +</h3></div></div></div> +<p> + pugixml 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. + </p> +<p> + There is only one non-conformant behavior when dealing with valid XML documents: + pugixml does not use information supplied in document type declaration for + parsing. This means that entities declared in DOCTYPE are not expanded, and + all attribute/PCDATA values are always processed in a uniform way that depends + only on parsing options. + </p> +<p> + As for rejecting invalid XML documents, there are a number of incompatibilities + with W3C specification, including: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Multiple attributes of the same node can have equal names. + </li> +<li class="listitem"> + All non-ASCII characters are treated in the same way as symbols of English + alphabet, so some invalid tag names are not rejected. + </li> +<li class="listitem"> + Attribute values which contain <code class="literal"><</code> are not rejected. + </li> +<li class="listitem"> + Invalid entity/character references are not rejected and are instead + left as is. + </li> +<li class="listitem"> + Comment values can contain <code class="literal">--</code>. + </li> +<li class="listitem"> + XML data is not required to begin with document declaration; additionally, + document declaration can appear after comments and other nodes. + </li> +<li class="listitem"> + Invalid document type declarations are silently ignored in some cases. + </li> +</ul></div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2010 Arseny Kapoulkine<p> + Distributed under the MIT License + </p> +</div></td> +</tr></table> +<hr> +<table width="100%"><tr> +<td>pugixml 0.9 manual | + <a href="../manual.html">Overview</a> | + <a href="install.html">Installation</a> | + Document: + <a href="dom.html">Object model</a> · <b>Loading</b> · <a href="access.html">Accessing</a> · <a href="modify.html">Modifying</a> · <a href="saving.html">Saving</a> | + <a href="xpath.html">XPath</a> | + <a href="apiref.html">API Reference</a> | + <a href="toc.html">Table of Contents</a> +</td> +<td width="*" align="right"><div class="spirit-nav"> +<a accesskey="p" href="dom.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../manual.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../manual.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="access.html"><img src="../images/next.png" alt="Next"></a> +</div></td> +</tr></table> +</body> +</html> diff --git a/docs/manual/modify.html b/docs/manual/modify.html new file mode 100644 index 0000000..f00e657 --- /dev/null +++ b/docs/manual/modify.html @@ -0,0 +1,541 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<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="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 | + <a href="../manual.html">Overview</a> | + <a href="install.html">Installation</a> | + Document: + <a href="dom.html">Object model</a> · <a href="loading.html">Loading</a> · <a href="access.html">Accessing</a> · <b>Modifying</b> · <a href="saving.html">Saving</a> | + <a href="xpath.html">XPath</a> | + <a href="apiref.html">API Reference</a> | + <a href="toc.html">Table of Contents</a> +</td> +<td width="*" align="right"><div class="spirit-nav"> +<a accesskey="p" href="access.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../manual.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../manual.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="saving.html"><img src="../images/next.png" alt="Next"></a> +</div></td> +</tr></table> +<hr> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="manual.modify"></a><a class="link" href="modify.html" title="Modifying document data"> Modifying document data</a> +</h2></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="modify.html#manual.modify.nodedata"> Setting node data</a></span></dt> +<dt><span class="section"><a href="modify.html#manual.modify.attrdata"> Setting attribute data</a></span></dt> +<dt><span class="section"><a href="modify.html#manual.modify.add"> Adding nodes/attributes</a></span></dt> +<dt><span class="section"><a href="modify.html#manual.modify.remove"> Removing nodes/attributes</a></span></dt> +<dt><span class="section"><a href="modify.html#manual.modify.clone"> Cloning nodes/attributes</a></span></dt> +</dl></div> +<p> + The document in pugixml is fully mutable: you can completely change the document + structure and modify the data of nodes/attributes. This section provides documentation + for the relevant functions. All functions take care of memory management and + structural integrity themselves, so they always result in structurally valid + tree - however, it is possible to create an invalid XML tree (for example, + by adding two attributes with the same name or by setting attribute/node name + to empty/invalid string). Tree modification is optimized for performance and + for memory consumption, so if you have enough memory you can create documents + from scratch with pugixml and later save them to file/stream instead of relying + on error-prone manual text writing and without too much overhead. + </p> +<p> + All member functions that change node/attribute data or structure are non-constant + and thus can not be called on constant handles. However, you can easily convert + constant handle to non-constant one by simple assignment: <code class="computeroutput"><span class="keyword">void</span> + <span class="identifier">foo</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> + <span class="special">{</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">nc</span> <span class="special">=</span> <span class="identifier">n</span><span class="special">;</span> <span class="special">}</span></code>, so const-correctness + here mainly provides additional documentation. + </p> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.modify.nodedata"></a><a class="link" href="modify.html#manual.modify.nodedata" title="Setting node data"> Setting node data</a> +</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> + 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> +<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">set_name</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">rhs</span><span class="special">);</span> +<span class="keyword">bool</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">set_value</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">rhs</span><span class="special">);</span> +</pre> +<p> + 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. + </p> +<p> + There is no equivalent of <code class="computeroutput"><span class="identifier">child_value</span></code> + function for modifying text children of the node. + </p> +<p> + This is an example of setting node name and value (<a href="../samples/modify_base.cpp" target="_top">samples/modify_base.cpp</a>): + </p> +<p> + +</p> +<pre class="programlisting"><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">child</span><span class="special">(</span><span class="string">"node"</span><span class="special">);</span> + +<span class="comment">// change node name +</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</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">"notnode"</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">", new node name: "</span> <span class="special"><<</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">name</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> + +<span class="comment">// change comment text +</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">last_child</span><span class="special">().</span><span class="identifier">set_value</span><span class="special">(</span><span class="string">"useless comment"</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">", new comment text: "</span> <span class="special"><<</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">last_child</span><span class="special">().</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> + +<span class="comment">// we can't change value of the element or name of the comment +</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">set_value</span><span class="special">(</span><span class="string">"1"</span><span class="special">)</span> <span class="special"><<</span> <span class="string">", "</span> <span class="special"><<</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">last_child</span><span class="special">().</span><span class="identifier">set_name</span><span class="special">(</span><span class="string">"2"</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> +</pre> +<p> + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.modify.attrdata"></a><a class="link" href="modify.html#manual.modify.attrdata" title="Setting attribute data"> Setting attribute data</a> +</h3></div></div></div> +<a name="xml_attribute::set_name"></a><a name="xml_attribute::set_value"></a><p> + All attributes have name and value, both of which are strings (value may + be empty). You can set them with the following functions: + </p> +<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">set_name</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">rhs</span><span class="special">);</span> +<span class="keyword">bool</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">set_value</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">rhs</span><span class="special">);</span> +</pre> +<p> + Both functions try to set the name/value to the specified string, and return + the operation result. The operation fails if the attribute 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> + In addition to string functions, several functions are provided for handling + attributes with numbers and booleans as values: + </p> +<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">set_value</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">rhs</span><span class="special">);</span> +<span class="keyword">bool</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">set_value</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">rhs</span><span class="special">);</span> +<span class="keyword">bool</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">set_value</span><span class="special">(</span><span class="keyword">double</span> <span class="identifier">rhs</span><span class="special">);</span> +<span class="keyword">bool</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">set_value</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">rhs</span><span class="special">);</span> +</pre> +<p> + The above functions convert the argument to string and then call the base + <code class="computeroutput"><span class="identifier">set_value</span></code> function. Integers + are converted to a decimal form, floating-point numbers are converted to + either decimal or scientific form, depending on the number magnitude, boolean + values are converted to either <code class="computeroutput"><span class="string">"true"</span></code> + or <code class="computeroutput"><span class="string">"false"</span></code>. + </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> + Number conversion functions depend on current C locale as set with <code class="computeroutput"><span class="identifier">setlocale</span></code>, so may generate unexpected + results if the locale is different from <code class="computeroutput"><span class="string">"C"</span></code>. + </p></td></tr> +</table></div> +<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> + There are no portable 64-bit types in C++, so there is no corresponding + <code class="computeroutput"><span class="identifier">set_value</span></code> function. If + your platform has a 64-bit integer, you can easily write such a function + yourself. + </p></td></tr> +</table></div> +<a name="xml_attribute::assign"></a><p> + For convenience, all <code class="computeroutput"><span class="identifier">set_value</span></code> + functions have the corresponding assignment operators: + </p> +<pre class="programlisting"><span class="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="keyword">operator</span><span class="special">=(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">rhs</span><span class="special">);</span> +<span class="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="keyword">operator</span><span class="special">=(</span><span class="keyword">int</span> <span class="identifier">rhs</span><span class="special">);</span> +<span class="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="keyword">operator</span><span class="special">=(</span><span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">rhs</span><span class="special">);</span> +<span class="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="keyword">operator</span><span class="special">=(</span><span class="keyword">double</span> <span class="identifier">rhs</span><span class="special">);</span> +<span class="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="keyword">operator</span><span class="special">=(</span><span class="keyword">bool</span> <span class="identifier">rhs</span><span class="special">);</span> +</pre> +<p> + 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. + </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>): + </p> +<p> + +</p> +<pre class="programlisting"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_attribute</span> <span class="identifier">attr</span> <span class="special">=</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"id"</span><span class="special">);</span> + +<span class="comment">// change attribute name/value +</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">attr</span><span class="special">.</span><span class="identifier">set_name</span><span class="special">(</span><span class="string">"key"</span><span class="special">)</span> <span class="special"><<</span> <span class="string">", "</span> <span class="special"><<</span> <span class="identifier">attr</span><span class="special">.</span><span class="identifier">set_value</span><span class="special">(</span><span class="string">"345"</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">", new attribute: "</span> <span class="special"><<</span> <span class="identifier">attr</span><span class="special">.</span><span class="identifier">name</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"="</span> <span class="special"><<</span> <span class="identifier">attr</span><span class="special">.</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> + +<span class="comment">// we can use numbers or booleans +</span><span class="identifier">attr</span><span class="special">.</span><span class="identifier">set_value</span><span class="special">(</span><span class="number">1.234</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">"new attribute value: "</span> <span class="special"><<</span> <span class="identifier">attr</span><span class="special">.</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> + +<span class="comment">// we can also use assignment operators for more concise code +</span><span class="identifier">attr</span> <span class="special">=</span> <span class="keyword">true</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">"final attribute value: "</span> <span class="special"><<</span> <span class="identifier">attr</span><span class="special">.</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> +</pre> +<p> + </p> +</div> +<div class="section"> +<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: + </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">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">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> +</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">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. + </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. + </p> +<p> + All functions return the handle to newly created object on success, and null + handle on failure. There are several reasons for failure: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + 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; + </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; + </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; + </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; + </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. + </li> +</ul></div> +<p> + Even if the operation fails, the document remains in consistent state, but + the requested node/attribute is not added. + </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> + attribute() and child() functions do not add attributes or nodes to the + tree, so code like <code class="computeroutput"><span class="identifier">node</span><span class="special">.</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"id"</span><span class="special">)</span> <span class="special">=</span> <span class="number">123</span><span class="special">;</span></code> will not do anything if <code class="computeroutput"><span class="identifier">node</span></code> does not have an attribute with + name <code class="computeroutput"><span class="string">"id"</span></code>. Make sure + you're operating with existing attributes/nodes by adding them if necessary. + </p></td></tr> +</table></div> +<p> + This is an example of adding new attributes/nodes to the document (<a href="../samples/modify_add.cpp" target="_top">samples/modify_add.cpp</a>): + </p> +<p> + +</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 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 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 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> +<span class="identifier">param</span><span class="special">.</span><span class="identifier">append_attribute</span><span class="special">(</span><span class="string">"value"</span><span class="special">)</span> <span class="special">=</span> <span class="number">1.1</span><span class="special">;</span> +<span class="identifier">param</span><span class="special">.</span><span class="identifier">insert_attribute_after</span><span class="special">(</span><span class="string">"type"</span><span class="special">,</span> <span class="identifier">param</span><span class="special">.</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"name"</span><span class="special">))</span> <span class="special">=</span> <span class="string">"float"</span><span class="special">;</span> +</pre> +<p> + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.modify.remove"></a><a class="link" href="modify.html#manual.modify.remove" title="Removing nodes/attributes"> Removing nodes/attributes</a> +</h3></div></div></div> +<a name="xml_node::remove_attribute"></a><a name="xml_node::remove_child"></a><p> + If you do not want your document to contain some node or attribute, you can + remove it with one of the following functions: + </p> +<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">remove_attribute</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">a</span><span class="special">);</span> +<span class="keyword">bool</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">remove_child</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> +</pre> +<p> + <code class="computeroutput"><span class="identifier">remove_attribute</span></code> removes + the attribute from the attribute list of the node, and returns the operation + result. <code class="computeroutput"><span class="identifier">remove_child</span></code> removes + the child node with the entire subtree (including all descendant nodes and + attributes) from the document, and returns the operation result. Removing + fails if one of the following is true: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + The node the function is called on is null; + </li> +<li class="listitem"> + The attribute/node to be removed is null; + </li> +<li class="listitem"> + The attribute/node to be removed is not in the node's attribute/child + list. + </li> +</ul></div> +<p> + Removing the attribute or node invalidates all handles to the same underlying + object, and also invalidates all iterators pointing to the same object. Removing + node also invalidates all past-the-end iterators to its attribute or child + node list. Be careful to ensure that all such handles and iterators either + do not exist or are not used after the attribute/node is removed. + </p> +<p> + If you want to remove the attribute or child node by its name, two additional + helper functions are available: + </p> +<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">remove_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="keyword">bool</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">remove_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> +</pre> +<p> + These functions look for the first attribute or child with the specified + name, and then remove it, returning the result. If there is no attribute + or child with such name, the function returns <code class="computeroutput"><span class="keyword">false</span></code>; + if there are two nodes with the given name, only the first node is deleted. + If you want to delete all nodes with the specified name, you can use code + like this: <code class="computeroutput"><span class="keyword">while</span> <span class="special">(</span><span class="identifier">node</span><span class="special">.</span><span class="identifier">remove_child</span><span class="special">(</span><span class="string">"tool"</span><span class="special">))</span> <span class="special">;</span></code>. + </p> +<p> + This is an example of removing attributes/nodes from the document (<a href="../samples/modify_remove.cpp" target="_top">samples/modify_remove.cpp</a>): + </p> +<p> + +</p> +<pre class="programlisting"><span class="comment">// remove description node with the whole subtree +</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">child</span><span class="special">(</span><span class="string">"node"</span><span class="special">);</span> +<span class="identifier">node</span><span class="special">.</span><span class="identifier">remove_child</span><span class="special">(</span><span class="string">"description"</span><span class="special">);</span> + +<span class="comment">// remove id attribute +</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">child</span><span class="special">(</span><span class="string">"param"</span><span class="special">);</span> +<span class="identifier">param</span><span class="special">.</span><span class="identifier">remove_attribute</span><span class="special">(</span><span class="string">"value"</span><span class="special">);</span> + +<span class="comment">// we can also remove nodes/attributes by handles +</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_attribute</span> <span class="identifier">id</span> <span class="special">=</span> <span class="identifier">param</span><span class="special">.</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"name"</span><span class="special">);</span> +<span class="identifier">param</span><span class="special">.</span><span class="identifier">remove_attribute</span><span class="special">(</span><span class="identifier">id</span><span class="special">);</span> +</pre> +<p> + </p> +</div> +<div class="section"> +<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> + 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 + 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">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">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. + </p> +<p> + The attribute is copied along with the name and value; the node is copied + along with its type, name and value; additionally attribute list and all + children are recursively cloned, resulting in the deep subtree clone. The + prototype object can be a part of the same document, or a part of any other + document. + </p> +<p> + The failure conditions resemble those 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, <a class="link" href="modify.html#xml_node::append_child">consult their documentation + for more information</a>. There are additional caveats specific to cloning + functions: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Cloning null handles results in operation failure; + </li> +<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> + is not a valid insertion type. The example below provides a workaround. + </li> +<li class="listitem"> + It is possible to copy a subtree as a child of some node inside this + subtree, i.e. <code class="computeroutput"><span class="identifier">node</span><span class="special">.</span><span class="identifier">append_copy</span><span class="special">(</span><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>. + This is a valid operation, and it results in a clone of the subtree in + the state before cloning started, i.e. no infinite recursion takes place. + </li> +</ul></div> +<p> + This is an example with one possible implementation of include tags in XML + (<a href="../samples/include.cpp" target="_top">samples/include.cpp</a>). It illustrates + node cloning and usage of other document modification functions: + </p> +<p> + +</p> +<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">load_preprocess</span><span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_document</span><span class="special">&</span> <span class="identifier">doc</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">bool</span> <span class="identifier">preprocess</span><span class="special">(</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="special">{</span> + <span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">child</span> <span class="special">=</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">first_child</span><span class="special">();</span> <span class="identifier">child</span><span class="special">;</span> <span class="special">)</span> + <span class="special">{</span> + <span class="keyword">if</span> <span class="special">(</span><span class="identifier">child</span><span class="special">.</span><span class="identifier">type</span><span class="special">()</span> <span class="special">==</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">node_pi</span> <span class="special">&&</span> <span class="identifier">strcmp</span><span class="special">(</span><span class="identifier">child</span><span class="special">.</span><span class="identifier">name</span><span class="special">(),</span> <span class="string">"include"</span><span class="special">)</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span> + <span class="special">{</span> + <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">include</span> <span class="special">=</span> <span class="identifier">child</span><span class="special">;</span> + + <span class="comment">// load new preprocessed document (note: ideally this should handle relative paths) +</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="identifier">include</span><span class="special">.</span><span class="identifier">value</span><span class="special">();</span> + + <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_document</span> <span class="identifier">doc</span><span class="special">;</span> + <span class="keyword">if</span> <span class="special">(!</span><span class="identifier">load_preprocess</span><span class="special">(</span><span class="identifier">doc</span><span class="special">,</span> <span class="identifier">path</span><span class="special">))</span> <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span> + + <span class="comment">// insert the comment marker above include directive +</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_comment</span><span class="special">,</span> <span class="identifier">include</span><span class="special">).</span><span class="identifier">set_value</span><span class="special">(</span><span class="identifier">path</span><span class="special">);</span> + + <span class="comment">// copy the document above the include directive (this retains the original order!) +</span> <span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">ic</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">first_child</span><span class="special">();</span> <span class="identifier">ic</span><span class="special">;</span> <span class="identifier">ic</span> <span class="special">=</span> <span class="identifier">ic</span><span class="special">.</span><span class="identifier">next_sibling</span><span class="special">())</span> + <span class="special">{</span> + <span class="identifier">node</span><span class="special">.</span><span class="identifier">insert_copy_before</span><span class="special">(</span><span class="identifier">ic</span><span class="special">,</span> <span class="identifier">include</span><span class="special">);</span> + <span class="special">}</span> + + <span class="comment">// remove the include node and move to the next child +</span> <span class="identifier">child</span> <span class="special">=</span> <span class="identifier">child</span><span class="special">.</span><span class="identifier">next_sibling</span><span class="special">();</span> + + <span class="identifier">node</span><span class="special">.</span><span class="identifier">remove_child</span><span class="special">(</span><span class="identifier">include</span><span class="special">);</span> + <span class="special">}</span> + <span class="keyword">else</span> + <span class="special">{</span> + <span class="keyword">if</span> <span class="special">(!</span><span class="identifier">preprocess</span><span class="special">(</span><span class="identifier">child</span><span class="special">))</span> <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span> + + <span class="identifier">child</span> <span class="special">=</span> <span class="identifier">child</span><span class="special">.</span><span class="identifier">next_sibling</span><span class="special">();</span> + <span class="special">}</span> + <span class="special">}</span> + + <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> +<span class="special">}</span> + +<span class="keyword">bool</span> <span class="identifier">load_preprocess</span><span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_document</span><span class="special">&</span> <span class="identifier">doc</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="special">{</span> + <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_parse_result</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">load_file</span><span class="special">(</span><span class="identifier">path</span><span class="special">,</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">parse_default</span> <span class="special">|</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">parse_pi</span><span class="special">);</span> <span class="comment">// for <?include?> +</span> + <span class="keyword">return</span> <span class="identifier">result</span> <span class="special">?</span> <span class="identifier">preprocess</span><span class="special">(</span><span class="identifier">doc</span><span class="special">)</span> <span class="special">:</span> <span class="keyword">false</span><span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + </p> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2010 Arseny Kapoulkine<p> + Distributed under the MIT License + </p> +</div></td> +</tr></table> +<hr> +<table width="100%"><tr> +<td>pugixml 0.9 manual | + <a href="../manual.html">Overview</a> | + <a href="install.html">Installation</a> | + Document: + <a href="dom.html">Object model</a> · <a href="loading.html">Loading</a> · <a href="access.html">Accessing</a> · <b>Modifying</b> · <a href="saving.html">Saving</a> | + <a href="xpath.html">XPath</a> | + <a href="apiref.html">API Reference</a> | + <a href="toc.html">Table of Contents</a> +</td> +<td width="*" align="right"><div class="spirit-nav"> +<a accesskey="p" href="access.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../manual.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../manual.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="saving.html"><img src="../images/next.png" alt="Next"></a> +</div></td> +</tr></table> +</body> +</html> diff --git a/docs/manual/saving.html b/docs/manual/saving.html new file mode 100644 index 0000000..e12b31d --- /dev/null +++ b/docs/manual/saving.html @@ -0,0 +1,473 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<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="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 | + <a href="../manual.html">Overview</a> | + <a href="install.html">Installation</a> | + Document: + <a href="dom.html">Object model</a> · <a href="loading.html">Loading</a> · <a href="access.html">Accessing</a> · <a href="modify.html">Modifying</a> · <b>Saving</b> | + <a href="xpath.html">XPath</a> | + <a href="apiref.html">API Reference</a> | + <a href="toc.html">Table of Contents</a> +</td> +<td width="*" align="right"><div class="spirit-nav"> +<a accesskey="p" href="modify.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../manual.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../manual.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="xpath.html"><img src="../images/next.png" alt="Next"></a> +</div></td> +</tr></table> +<hr> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="manual.saving"></a><a class="link" href="saving.html" title="Saving document"> Saving document</a> +</h2></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="saving.html#manual.saving.file"> Saving document to a file</a></span></dt> +<dt><span class="section"><a href="saving.html#manual.saving.stream"> Saving document to C++ IOstreams</a></span></dt> +<dt><span class="section"><a href="saving.html#manual.saving.writer"> Saving document via writer interface</a></span></dt> +<dt><span class="section"><a href="saving.html#manual.saving.subtree"> Saving a single subtree</a></span></dt> +<dt><span class="section"><a href="saving.html#manual.saving.options"> Output options</a></span></dt> +<dt><span class="section"><a href="saving.html#manual.saving.encoding"> Encodings</a></span></dt> +</dl></div> +<p> + Often after creating a new document or loading the existing one and processing + it, it is necessary to save the result back to file. Also it is occasionally + useful to output the whole document or a subtree to some stream; use cases + include debug printing, serialization via network or other text-oriented medium, + etc. pugixml provides several functions to output any subtree of the document + to a file, stream or another generic transport interface; these functions allow + to customize the output format (see <a class="xref" href="saving.html#manual.saving.options" title="Output options"> Output options</a>), and also perform + necessary encoding conversions (see <a class="xref" href="saving.html#manual.saving.encoding" title="Encodings"> Encodings</a>). This section documents + 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 + 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> +<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: + </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> +</pre> +<p> + This function accepts 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. + </p> +<a name="xml_writer_file"></a><p> + <code class="computeroutput"><span class="identifier">save_file</span></code> opens the target + file for writing, outputs the requested header (by default a document declaration + is output, unless the document already has one), and then saves the document + contents. If the file could not be opened, the function returns <code class="computeroutput"><span class="keyword">false</span></code>. Calling <code class="computeroutput"><span class="identifier">save_file</span></code> + is equivalent to creating an <code class="computeroutput"><span class="identifier">xml_writer_file</span></code> + object with <code class="computeroutput"><span class="identifier">FILE</span><span class="special">*</span></code> + 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> +<p> + +</p> +<pre class="programlisting"><span class="comment">// save document to file +</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Saving result: "</span> <span class="special"><<</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">save_file</span><span class="special">(</span><span class="string">"save_file_output.xml"</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> +</pre> +<p> + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<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> + stream as saving target. There are two functions, one works with narrow character + streams, another handles wide character ones: + </p> +<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">xml_document</span><span class="special">::</span><span class="identifier">save</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">stream</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">void</span> <span class="identifier">xml_document</span><span class="special">::</span><span class="identifier">save</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">stream</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">const</span><span class="special">;</span> +</pre> +<p> + <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">ostream</span></code> + 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> + 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> + function). Generally use of wide streams is discouraged, however it provides + you with the ability to save documents to non-Unicode encodings, i.e. you + can save Shift-JIS encoded data if you set the correct locale. + </p> +<a name="xml_writer_stream"></a><p> + Calling <code class="computeroutput"><span class="identifier">save</span></code> with stream + target is equivalent to creating an <code class="computeroutput"><span class="identifier">xml_writer_stream</span></code> + object with stream 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> +<p> + This is a simple example of saving XML document to standard output (<a href="../samples/save_stream.cpp" target="_top">samples/save_stream.cpp</a>): + </p> +<p> + +</p> +<pre class="programlisting"><span class="comment">// save document to standard output +</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Document:\n"</span><span class="special">;</span> +<span class="identifier">doc</span><span class="special">.</span><span class="identifier">save</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.saving.writer"></a><a class="link" href="saving.html#manual.saving.writer" title="Saving document via writer interface"> Saving document via writer interface</a> +</h3></div></div></div> +<a name="xml_document::save"></a><a name="xml_writer"></a><a name="xml_writer::write"></a><p> + All of the above saving functions are implemented in terms of writer interface. + This is a simple interface with a single function, which is called several + times during output process with chunks of document data as input: + </p> +<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">xml_writer</span> +<span class="special">{</span> +<span class="keyword">public</span><span class="special">:</span> + <span class="keyword">virtual</span> <span class="keyword">void</span> <span class="identifier">write</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">void</span><span class="special">*</span> <span class="identifier">data</span><span class="special">,</span> <span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">)</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> +<span class="special">};</span> + +<span class="keyword">void</span> <span class="identifier">xml_document</span><span class="special">::</span><span class="identifier">save</span><span class="special">(</span><span class="identifier">xml_writer</span><span class="special">&</span> <span class="identifier">writer</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> + In order to output the document via some custom transport, for example sockets, + you should create an object which implements <code class="computeroutput"><span class="identifier">xml_writer_file</span></code> + interface and pass it to <code class="computeroutput"><span class="identifier">save</span></code> + function. <code class="computeroutput"><span class="identifier">xml_writer_file</span><span class="special">::</span><span class="identifier">write</span></code> + function is called with a buffer as an input, where <code class="computeroutput"><span class="identifier">data</span></code> + points to buffer start, and <code class="computeroutput"><span class="identifier">size</span></code> + is equal to the buffer size in bytes. <code class="computeroutput"><span class="identifier">write</span></code> + implementation must write the buffer to the transport; it can not save the + passed buffer pointer, as the buffer contents will change after <code class="computeroutput"><span class="identifier">write</span></code> returns. The buffer contains the + chunk of document data in the desired encoding. + </p> +<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> + is set, and last block, which may be small), so there is often no need for + additional buffering in the implementation. + </p> +<p> + This is a simple example of custom writer for saving document data to STL + string (<a href="../samples/save_custom_writer.cpp" target="_top">samples/save_custom_writer.cpp</a>); + read the sample code for more complex examples: + </p> +<p> + +</p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">xml_string_writer</span><span class="special">:</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_writer</span> +<span class="special">{</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">result</span><span class="special">;</span> + + <span class="keyword">virtual</span> <span class="keyword">void</span> <span class="identifier">write</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">void</span><span class="special">*</span> <span class="identifier">data</span><span class="special">,</span> <span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">)</span> + <span class="special">{</span> + <span class="identifier">result</span> <span class="special">+=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">(</span><span class="keyword">static_cast</span><span class="special"><</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*>(</span><span class="identifier">data</span><span class="special">),</span> <span class="identifier">size</span><span class="special">);</span> + <span class="special">}</span> +<span class="special">};</span> +</pre> +<p> + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<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: + </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> +<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">xml_writer</span><span class="special">&</span> <span class="identifier">writer</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> +</pre> +<p> + These functions have the same arguments with the same meaning as the corresponding + <code class="computeroutput"><span class="identifier">xml_document</span><span class="special">::</span><span class="identifier">save</span></code> functions, and allow you to save the + subtree to either a C++ IOstream or to any object that implements <code class="computeroutput"><span class="identifier">xml_writer</span></code> interface. + </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 + 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: + </p> +<p> + +</p> +<pre class="programlisting"><span class="comment">// get a test document +</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_document</span> <span class="identifier">doc</span><span class="special">;</span> +<span class="identifier">doc</span><span class="special">.</span><span class="identifier">load</span><span class="special">(</span><span class="string">"<foo bar='baz'><call>hey</call></foo>"</span><span class="special">);</span> + +<span class="comment">// print document to standard output (prints <?xml version="1.0"?><foo bar="baz"><call>hey</call></foo>) +</span><span class="identifier">doc</span><span class="special">.</span><span class="identifier">save</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">""</span><span class="special">,</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">format_raw</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">endl</span><span class="special">;</span> + +<span class="comment">// print document to standard output as a regular node (prints <foo bar="baz"><call>hey</call></foo>) +</span><span class="identifier">doc</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="string">""</span><span class="special">,</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">format_raw</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">endl</span><span class="special">;</span> + +<span class="comment">// print a subtree to standard output (prints <call>hey</call>) +</span><span class="identifier">doc</span><span class="special">.</span><span class="identifier">child</span><span class="special">(</span><span class="string">"foo"</span><span class="special">).</span><span class="identifier">child</span><span class="special">(</span><span class="string">"call"</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="string">""</span><span class="special">,</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">format_raw</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">endl</span><span class="special">;</span> +</pre> +<p> + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.saving.options"></a><a class="link" href="saving.html#manual.saving.options" title="Output options"> Output options</a> +</h3></div></div></div> +<p> + All saving functions accept the optional parameter <code class="computeroutput"><span class="identifier">flags</span></code>. + This is a bitmask that customizes the output format; you can select the way + the document nodes are printed and select the needed additional information + that is output before the document contents. + </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 should use the usual bitwise arithmetics to manipulate the bitmask: + to enable a flag, use <code class="computeroutput"><span class="identifier">mask</span> <span class="special">|</span> <span class="identifier">flag</span></code>; + to disable a flag, use <code class="computeroutput"><span class="identifier">mask</span> <span class="special">&</span> <span class="special">~</span><span class="identifier">flag</span></code>. + </p></td></tr> +</table></div> +<p> + These flags control the resulting tree contents: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + <a name="format_indent"></a><code class="literal">format_indent</code> determines if all nodes + should be indented with the indentation string (this is an additional + parameter for all saving functions, and is <code class="computeroutput"><span class="string">"\t"</span></code> + 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> + + </li> +<li class="listitem"> + <a name="format_raw"></a><code class="literal">format_raw</code> switches between formatted and + raw output. If this flag is on, the nodes are not indented in any way, + 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. + </li> +</ul></div> +<p> + These flags control the additional output information: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + <a name="format_no_declaration"></a><code class="literal">format_no_declaration</code> allows + to disable default node declaration output. By default, if the document + is saved via <code class="computeroutput"><span class="identifier">save</span></code> or + <code class="computeroutput"><span class="identifier">save_file</span></code> function, and + it does not have any document declaration, a default declaration is output + before the document contents. Enabling this flag disables this declaration. + This flag has no effect in <code class="computeroutput"><span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">print</span></code> + functions: they never output the default declaration. This flag is <span class="bold"><strong>off</strong></span> by default. <br><br> + + </li> +<li class="listitem"> + <a name="format_write_bom"></a><code class="literal">format_write_bom</code> allows to enable + Byte Order Mark (BOM) output. By default, no BOM is output, so in case + of non UTF-8 encodings the resulting document's encoding may not be recognized + by some parsers and text editors, if they do not implement sophisticated + encoding detection. Enabling this flag adds an encoding-specific BOM + to the output. This flag has no effect in <code class="computeroutput"><span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">print</span></code> + functions: they never output the BOM. This flag is <span class="bold"><strong>off</strong></span> + by default. + </li> +</ul></div> +<p> + Additionally, there is one predefined option mask: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + <a name="format_default"></a><code class="literal">format_default</code> is the default set of + flags, i.e. it has all options set to their default values. It sets formatted + output with indentation, without BOM and with default node declaration, + if necessary. + </li></ul></div> +<p> + This is an example that shows the outputs of different output options (<a href="../samples/save_options.cpp" target="_top">samples/save_options.cpp</a>): + </p> +<p> + +</p> +<pre class="programlisting"><span class="comment">// get a test document +</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_document</span> <span class="identifier">doc</span><span class="special">;</span> +<span class="identifier">doc</span><span class="special">.</span><span class="identifier">load</span><span class="special">(</span><span class="string">"<foo bar='baz'><call>hey</call></foo>"</span><span class="special">);</span> + +<span class="comment">// default options; prints +</span><span class="comment">// <?xml version="1.0"?> +</span><span class="comment">// <foo bar="baz"> +</span><span class="comment">// <call>hey</call> +</span><span class="comment">// </foo> +</span><span class="identifier">doc</span><span class="special">.</span><span class="identifier">save</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="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> + +<span class="comment">// default options with custom indentation string; prints +</span><span class="comment">// <?xml version="1.0"?> +</span><span class="comment">// <foo bar="baz"> +</span><span class="comment">// --<call>hey</call> +</span><span class="comment">// </foo> +</span><span class="identifier">doc</span><span class="special">.</span><span class="identifier">save</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">"--"</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">endl</span><span class="special">;</span> + +<span class="comment">// default options without indentation; prints +</span><span class="comment">// <?xml version="1.0"?> +</span><span class="comment">// <foo bar="baz"> +</span><span class="comment">// <call>hey</call> +</span><span class="comment">// </foo> +</span><span class="identifier">doc</span><span class="special">.</span><span class="identifier">save</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">"\t"</span><span class="special">,</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">format_default</span> <span class="special">&</span> <span class="special">~</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">format_indent</span><span class="special">);</span> <span class="comment">// can also pass "" instead of indentation string for the same effect +</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">endl</span><span class="special">;</span> + +<span class="comment">// raw output; prints +</span><span class="comment">// <?xml version="1.0"?><foo bar="baz"><call>hey</call></foo> +</span><span class="identifier">doc</span><span class="special">.</span><span class="identifier">save</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">"\t"</span><span class="special">,</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">format_raw</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">endl</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> + +<span class="comment">// raw output without declaration; prints +</span><span class="comment">// <foo bar="baz"><call>hey</call></foo> +</span><span class="identifier">doc</span><span class="special">.</span><span class="identifier">save</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">"\t"</span><span class="special">,</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">format_raw</span> <span class="special">|</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">format_no_declaration</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">endl</span><span class="special">;</span> +</pre> +<p> + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.saving.encoding"></a><a class="link" href="saving.html#manual.saving.encoding" title="Encodings"> Encodings</a> +</h3></div></div></div> +<p> + pugixml supports all popular Unicode encodings (UTF-8, UTF-16 (big and little + endian), UTF-32 (big and little endian); UCS-2 is naturally supported since + it's a strict subset of UTF-16) and handles all encoding conversions during + output. The output encoding is set via the <code class="computeroutput"><span class="identifier">encoding</span></code> + parameter of saving functions, which is of type <code class="computeroutput"><span class="identifier">xml_encoding</span></code>. + The possible values for the encoding are documented in <a class="xref" href="loading.html#manual.loading.encoding" title="Encodings"> Encodings</a>; + the only flag that has a different meaning is <code class="computeroutput"><span class="identifier">encoding_auto</span></code>. + </p> +<p> + While all other flags set the exact encoding, <code class="computeroutput"><span class="identifier">encoding_auto</span></code> + is meant for automatic encoding detection. The automatic detection does not + make sense for output encoding, since there is usually nothing to infer the + actual encoding from, so here <code class="computeroutput"><span class="identifier">encoding_auto</span></code> + means UTF-8 encoding, which is the most popular encoding for XML data storage. + This is also the default value of output encoding; specify another value + if you do not want UTF-8 encoded output. + </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> + encoding. + </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 current behavior for Unicode conversion is to skip all invalid UTF + sequences during conversion. This behavior should not be relied upon; if + your node/attribute names do not contain any valid UTF sequences, they + may be output as if they are empty, which will result in malformed XML + document. + </p></td></tr> +</table></div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2010 Arseny Kapoulkine<p> + Distributed under the MIT License + </p> +</div></td> +</tr></table> +<hr> +<table width="100%"><tr> +<td>pugixml 0.9 manual | + <a href="../manual.html">Overview</a> | + <a href="install.html">Installation</a> | + Document: + <a href="dom.html">Object model</a> · <a href="loading.html">Loading</a> · <a href="access.html">Accessing</a> · <a href="modify.html">Modifying</a> · <b>Saving</b> | + <a href="xpath.html">XPath</a> | + <a href="apiref.html">API Reference</a> | + <a href="toc.html">Table of Contents</a> +</td> +<td width="*" align="right"><div class="spirit-nav"> +<a accesskey="p" href="modify.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../manual.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../manual.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="xpath.html"><img src="../images/next.png" alt="Next"></a> +</div></td> +</tr></table> +</body> +</html> diff --git a/docs/manual/toc.html b/docs/manual/toc.html new file mode 100644 index 0000000..60a054a --- /dev/null +++ b/docs/manual/toc.html @@ -0,0 +1,130 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<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="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 | + <a href="../manual.html">Overview</a> | + <a href="install.html">Installation</a> | + Document: + <a href="dom.html">Object model</a> · <a href="loading.html">Loading</a> · <a href="access.html">Accessing</a> · <a href="modify.html">Modifying</a> · <a href="saving.html">Saving</a> | + <a href="xpath.html">XPath</a> | + <a href="apiref.html">API Reference</a> | + <b>Table of Contents</b> +</td> +<td width="*" align="right"><div class="spirit-nav"> +<a accesskey="p" href="apiref.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../manual.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../manual.html"><img src="../images/home.png" alt="Home"></a> +</div></td> +</tr></table> +<hr> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="manual.toc"></a><a class="link" href="toc.html" title="Table of Contents"> Table of Contents</a> +</h2></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="manual.html#manual.overview"> Overview</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="manual.html#manual.overview.introduction"> Introduction</a></span></dt> +<dt><span class="section"><a href="manual.html#manual.overview.feedback"> Feedback</a></span></dt> +<dt><span class="section"><a href="manual.html#manual.overview.thanks"> Acknowledgments</a></span></dt> +<dt><span class="section"><a href="manual.html#manual.overview.license"> License</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="manual/install.html"> Installation</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="manual/install.html#manual.install.getting"> Getting pugixml</a></span></dt> +<dt><span class="section"><a href="manual/install.html#manual.install.building"> Building pugixml</a></span></dt> +<dt><span class="section"><a href="manual/install.html#manual.install.portability"> Portability</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="manual/dom.html"> Document object model</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="manual/dom.html#manual.dom.tree"> Tree structure</a></span></dt> +<dt><span class="section"><a href="manual/dom.html#manual.dom.cpp"> C++ interface</a></span></dt> +<dt><span class="section"><a href="manual/dom.html#manual.dom.unicode"> Unicode interface</a></span></dt> +<dt><span class="section"><a href="manual/dom.html#manual.dom.thread"> Thread-safety guarantees</a></span></dt> +<dt><span class="section"><a href="manual/dom.html#manual.dom.exception"> Exception guarantees</a></span></dt> +<dt><span class="section"><a href="manual/dom.html#manual.dom.memory"> Memory management</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="manual/loading.html"> Loading document</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="manual/loading.html#manual.loading.file"> Loading document from file</a></span></dt> +<dt><span class="section"><a href="manual/loading.html#manual.loading.memory"> Loading document from memory</a></span></dt> +<dt><span class="section"><a href="manual/loading.html#manual.loading.stream"> Loading document from C++ IOstreams</a></span></dt> +<dt><span class="section"><a href="manual/loading.html#manual.loading.errors"> Handling parsing errors</a></span></dt> +<dt><span class="section"><a href="manual/loading.html#manual.loading.options"> Parsing options</a></span></dt> +<dt><span class="section"><a href="manual/loading.html#manual.loading.encoding"> Encodings</a></span></dt> +<dt><span class="section"><a href="manual/loading.html#manual.loading.w3c"> Conformance to W3C specification</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="manual/access.html"> Accessing document data</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="manual/access.html#manual.access.basic"> Basic traversal functions</a></span></dt> +<dt><span class="section"><a href="manual/access.html#manual.access.nodedata"> Getting node data</a></span></dt> +<dt><span class="section"><a href="manual/access.html#manual.access.attrdata"> Getting attribute data</a></span></dt> +<dt><span class="section"><a href="manual/access.html#manual.access.contents"> Contents-based traversal functions</a></span></dt> +<dt><span class="section"><a href="manual/access.html#manual.access.iterators"> Traversing node/attribute lists + via iterators</a></span></dt> +<dt><span class="section"><a href="manual/access.html#manual.access.walker"> Recursive traversal with xml_tree_walker</a></span></dt> +<dt><span class="section"><a href="manual/access.html#manual.access.predicate"> Searching for nodes/attributes + with predicates</a></span></dt> +<dt><span class="section"><a href="manual/access.html#manual.access.misc"> Miscellaneous functions</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="manual/modify.html"> Modifying document data</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="manual/modify.html#manual.modify.nodedata"> Setting node data</a></span></dt> +<dt><span class="section"><a href="manual/modify.html#manual.modify.attrdata"> Setting attribute data</a></span></dt> +<dt><span class="section"><a href="manual/modify.html#manual.modify.add"> Adding nodes/attributes</a></span></dt> +<dt><span class="section"><a href="manual/modify.html#manual.modify.remove"> Removing nodes/attributes</a></span></dt> +<dt><span class="section"><a href="manual/modify.html#manual.modify.clone"> Cloning nodes/attributes</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="manual/saving.html"> Saving document</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="manual/saving.html#manual.saving.file"> Saving document to a file</a></span></dt> +<dt><span class="section"><a href="manual/saving.html#manual.saving.stream"> Saving document to C++ IOstreams</a></span></dt> +<dt><span class="section"><a href="manual/saving.html#manual.saving.writer"> Saving document via writer interface</a></span></dt> +<dt><span class="section"><a href="manual/saving.html#manual.saving.subtree"> Saving a single subtree</a></span></dt> +<dt><span class="section"><a href="manual/saving.html#manual.saving.options"> Output options</a></span></dt> +<dt><span class="section"><a href="manual/saving.html#manual.saving.encoding"> Encodings</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="manual/xpath.html"> XPath</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="manual/xpath.html#manual.xpath.types"> XPath types</a></span></dt> +<dt><span class="section"><a href="manual/xpath.html#manual.xpath.select"> Selecting nodes via XPath expression</a></span></dt> +<dt><span class="section"><a href="manual/xpath.html#manual.xpath.query"> Using query objects</a></span></dt> +<dt><span class="section"><a href="manual/xpath.html#manual.xpath.errors"> Error handling</a></span></dt> +<dt><span class="section"><a href="manual/xpath.html#manual.xpath.w3c"> Conformance to W3C specification</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="manual/changes.html"> Changelog</a></span></dt> +<dt><span class="section"><a href="manual/apiref.html"> API Reference</a></span></dt> +<dt><span class="section"><a href="manual/toc.html"> Table of Contents</a></span></dt> +</dl></div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2010 Arseny Kapoulkine<p> + Distributed under the MIT License + </p> +</div></td> +</tr></table> +<hr> +<table width="100%"><tr> +<td>pugixml 0.9 manual | + <a href="../manual.html">Overview</a> | + <a href="install.html">Installation</a> | + Document: + <a href="dom.html">Object model</a> · <a href="loading.html">Loading</a> · <a href="access.html">Accessing</a> · <a href="modify.html">Modifying</a> · <a href="saving.html">Saving</a> | + <a href="xpath.html">XPath</a> | + <a href="apiref.html">API Reference</a> | + <b>Table of Contents</b> +</td> +<td width="*" align="right"><div class="spirit-nav"> +<a accesskey="p" href="apiref.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../manual.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../manual.html"><img src="../images/home.png" alt="Home"></a> +</div></td> +</tr></table> +</body> +</html> diff --git a/docs/manual/xpath.html b/docs/manual/xpath.html new file mode 100644 index 0000000..731a969 --- /dev/null +++ b/docs/manual/xpath.html @@ -0,0 +1,494 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<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="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 | + <a href="../manual.html">Overview</a> | + <a href="install.html">Installation</a> | + Document: + <a href="dom.html">Object model</a> · <a href="loading.html">Loading</a> · <a href="access.html">Accessing</a> · <a href="modify.html">Modifying</a> · <a href="saving.html">Saving</a> | + <b>XPath</b> | + <a href="apiref.html">API Reference</a> | + <a href="toc.html">Table of Contents</a> +</td> +<td width="*" align="right"><div class="spirit-nav"> +<a accesskey="p" href="saving.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../manual.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../manual.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="changes.html"><img src="../images/next.png" alt="Next"></a> +</div></td> +</tr></table> +<hr> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="manual.xpath"></a><a class="link" href="xpath.html" title="XPath"> XPath</a> +</h2></div></div></div> +<div class="toc"><dl> +<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.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> +<p> + If the task at hand is to select a subset of document nodes that match some + criteria, it is possible to code a function using the existing traversal functionality + for any practical criteria. However, often either a data-driven approach is + desirable, in case the criteria are not predefined and come from a file, or + it is inconvenient to use traversal interfaces and a higher-level DSL is required. + There is a standard language for XML processing, XPath, that can be useful + for these cases. pugixml implements an almost complete subset of XPath 1.0. + Because of differences in document object model and some performance implications, + there are minor violations of the official specifications, which can be found + in <a class="xref" href="xpath.html#manual.xpath.w3c" title="Conformance to W3C specification"> Conformance to W3C specification</a>. The rest of this section describes the interface for XPath + functionality. Please note that if you wish to learn to use XPath language, + you have to look for other tutorials or manuals; for example, you can read + <a href="http://www.w3schools.com/xpath/" target="_top">W3Schools XPath tutorial</a>, + <a href="http://www.tizag.com/xmlTutorial/xpathtutorial.php" target="_top">XPath tutorial + 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> +</h3></div></div></div> +<a name="xpath_value_type"></a><a name="xpath_type_number"></a><a name="xpath_type_string"></a><a name="xpath_type_boolean"></a><a name="xpath_type_node_set"></a><a name="xpath_type_none"></a><p> + Each XPath expression can have one of the following types: boolean, number, + string or node set. Boolean type corresponds to <code class="computeroutput"><span class="keyword">bool</span></code> + 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, + <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>, + accordingly. + </p> +<a name="xpath_node"></a><a name="xpath_node::node"></a><a name="xpath_node::attribute"></a><a name="xpath_node::parent"></a><p> + Because an XPath node can be either a node or an attribute, there is a special + type, <code class="computeroutput"><span class="identifier">xpath_node</span></code>, which is + a discriminated union of these types. A value of this type contains two node + handles, one of <code class="computeroutput"><span class="identifier">xml_node</span></code> + type, and another one of <code class="computeroutput"><span class="identifier">xml_attribute</span></code> + type; at most one of them can be non-null. The accessors to get these handles + are available: + </p> +<pre class="programlisting"><span class="identifier">xml_node</span> <span class="identifier">xpath_node</span><span class="special">::</span><span class="identifier">node</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="identifier">xml_attribute</span> <span class="identifier">xpath_node</span><span class="special">::</span><span class="identifier">attribute</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<p> + XPath nodes can be null, in which case both accessors return null handles. + </p> +<p> + Note that as per XPath specification, each XPath node has a parent, which + can be retrieved via this function: + </p> +<pre class="programlisting"><span class="identifier">xml_node</span> <span class="identifier">xpath_node</span><span class="special">::</span><span class="identifier">parent</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<p> + <code class="computeroutput"><span class="identifier">parent</span></code> function returns the + node's parent if the XPath node corresponds to <code class="computeroutput"><span class="identifier">xml_node</span></code> + handle (equivalent to <code class="computeroutput"><span class="identifier">node</span><span class="special">().</span><span class="identifier">parent</span><span class="special">()</span></code>), or the node to which the attribute belongs + to, if the XPath node corresponds to <code class="computeroutput"><span class="identifier">xml_attribute</span></code> + handle. For null nodes, <code class="computeroutput"><span class="identifier">parent</span></code> + returns null handle. + </p> +<a name="xpath_node::unspecified_bool_type"></a><a name="xpath_node::comparison"></a><p> + Like node and attribute handles, XPath node handles can be implicitly cast + to boolean-like object to check if it is a null node, and also can be compared + 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 + 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. + </p> +<a name="xpath_node_set"></a><p> + XPath expressions operate not on single nodes, but instead on node sets. + A node set is a collection of nodes, which can be optionally ordered in either + a forward document order or a reverse one. Document order is defined in XPath + specification; an XPath node is before another node in document order if + it appears before it in XML representation of the corresponding document. + </p> +<a name="xpath_node_set::const_iterator"></a><a name="xpath_node_set::begin"></a><a name="xpath_node_set::end"></a><p> + Node sets are represented by <code class="computeroutput"><span class="identifier">xpath_node_set</span></code> + object, which has an interface that resembles one of sequential random-access + containers. It has an iterator type along with usual begin/past-the-end iterator + accessors: + </p> +<pre class="programlisting"><span class="keyword">typedef</span> <span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">*</span> <span class="identifier">xpath_node_set</span><span class="special">::</span><span class="identifier">const_iterator</span><span class="special">;</span> +<span class="identifier">const_iterator</span> <span class="identifier">xpath_node_set</span><span class="special">::</span><span class="identifier">begin</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="identifier">const_iterator</span> <span class="identifier">xpath_node_set</span><span class="special">::</span><span class="identifier">end</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<a name="xpath_node_set::index"></a><a name="xpath_node_set::size"></a><a name="xpath_node_set::empty"></a><p> + And it also can be iterated via indices, just like <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code>: + </p> +<pre class="programlisting"><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span> <span class="identifier">xpath_node_set</span><span class="special">::</span><span class="keyword">operator</span><span class="special">[](</span><span class="identifier">size_t</span> <span class="identifier">index</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +<span class="identifier">size_t</span> <span class="identifier">xpath_node_set</span><span class="special">::</span><span class="identifier">size</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="keyword">bool</span> <span class="identifier">xpath_node_set</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> + All of the above operations have the same semantics as that of <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code>: + 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. + </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 + order can be queried via the following function: + </p> +<pre class="programlisting"><span class="keyword">enum</span> <span class="identifier">xpath_node_set</span><span class="special">::</span><span class="identifier">type_t</span> <span class="special">{</span><span class="identifier">type_unsorted</span><span class="special">,</span> <span class="identifier">type_sorted</span><span class="special">,</span> <span class="identifier">type_sorted_reverse</span><span class="special">};</span> +<span class="identifier">type_t</span> <span class="identifier">xpath_node_set</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> + <code class="computeroutput"><span class="identifier">type</span></code> function returns the + current order of nodes; <code class="computeroutput"><span class="identifier">type_sorted</span></code> + means that the nodes are in forward document order, <code class="computeroutput"><span class="identifier">type_sorted_reverse</span></code> + means that the nodes are in reverse document order, and <code class="computeroutput"><span class="identifier">type_unsorted</span></code> + means that neither order is guaranteed (nodes can accidentally be in a sorted + order even if <code class="computeroutput"><span class="identifier">type</span><span class="special">()</span></code> + returns <code class="computeroutput"><span class="identifier">type_unsorted</span></code>). If + you require a specific order of iteration, you can change it via <code class="computeroutput"><span class="identifier">sort</span></code> function: + </p> +<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">xpath_node_set</span><span class="special">::</span><span class="identifier">sort</span><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> +</pre> +<p> + Calling <code class="computeroutput"><span class="identifier">sort</span></code> sorts the nodes + in either forward or reverse document order, depending on the argument; after + this call <code class="computeroutput"><span class="identifier">type</span><span class="special">()</span></code> + will return <code class="computeroutput"><span class="identifier">type_sorted</span></code> or + <code class="computeroutput"><span class="identifier">type_sorted_reverse</span></code>. + </p> +<a name="xpath_node_set::first"></a><p> + Often the actual iteration is not needed; instead, only the first element + in document order is required. For this, a special accessor is provided: + </p> +<pre class="programlisting"><span class="identifier">xpath_node</span> <span class="identifier">xpath_node_set</span><span class="special">::</span><span class="identifier">first</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<p> + This function returns the first node in forward document order from the set, + or null node if the set is empty. Note that while the result of the node + does not depend on the order of nodes in the set (i.e. on the result of + <code class="computeroutput"><span class="identifier">type</span><span class="special">()</span></code>), + the complexity does - if the set is sorted, the complexity is constant, otherwise + it is linear in the number of elements or worse. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.xpath.select"></a><a class="link" href="xpath.html#manual.xpath.select" title="Selecting nodes via XPath expression"> Selecting nodes via XPath expression</a> +</h3></div></div></div> +<a name="xml_node::select_single_node"></a><a name="xml_node::select_nodes"></a><p> + 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> +<p> + <code class="computeroutput"><span class="identifier">select_nodes</span></code> function compiles + the expression and then executes it with the node as a context node, and + returns the resulting node set. <code class="computeroutput"><span class="identifier">select_single_node</span></code> + returns only the first node in document order from the result, and is equivalent + to calling <code class="computeroutput"><span class="identifier">select_nodes</span><span class="special">(</span><span class="identifier">query</span><span class="special">).</span><span class="identifier">first</span><span class="special">()</span></code>. + If the XPath expression does not match anything, or the node handle is null, + <code class="computeroutput"><span class="identifier">select_nodes</span></code> returns an empty + set, and <code class="computeroutput"><span class="identifier">select_single_node</span></code> + returns null XPath node. + </p> +<p> + Both functions throw <code class="computeroutput"><span class="identifier">xpath_exception</span></code> + 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> +<a name="xml_node::select_single_node_precomp"></a><a name="xml_node::select_nodes_precomp"></a><p> + While compiling expressions is fast, the compilation time can introduce a + significant overhead if the same expression is used many times on small subtrees. + If you're doing many similar queries, consider compiling them into query + objects (see <a class="xref" href="xpath.html#manual.xpath.query" title="Using query objects"> Using query objects</a> for further reference). Once you get a compiled + query object, you can pass it to select functions instead of an expression + string: + </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">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> +<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 the query returns a value with type other than node set. + </p> +<p> + This is an example of selecting nodes using XPath expressions (<a href="../samples/xpath_select.cpp" target="_top">samples/xpath_select.cpp</a>): + </p> +<p> + +</p> +<pre class="programlisting"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_node_set</span> <span class="identifier">tools</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='true' and @DeriveCaptionFrom='lastparam']"</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">"Tools:"</span><span class="special">;</span> + +<span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</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">it</span> <span class="special">=</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">begin</span><span class="special">();</span> <span class="identifier">it</span> <span class="special">!=</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">end</span><span class="special">();</span> <span class="special">++</span><span class="identifier">it</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_node</span> <span class="identifier">node</span> <span class="special">=</span> <span class="special">*</span><span class="identifier">it</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">" "</span> <span class="special"><<</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">node</span><span class="special">().</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"Filename"</span><span class="special">).</span><span class="identifier">value</span><span class="special">();</span> +<span class="special">}</span> + +<span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_node</span> <span class="identifier">build_tool</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">select_single_node</span><span class="special">(</span><span class="string">"//Tool[contains(Description, 'build system')]"</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">"\nBuild tool: "</span> <span class="special"><<</span> <span class="identifier">build_tool</span><span class="special">.</span><span class="identifier">node</span><span class="special">().</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"Filename"</span><span class="special">).</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"\n"</span><span class="special">;</span> +</pre> +<p> + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.xpath.query"></a><a class="link" href="xpath.html#manual.xpath.query" title="Using query objects"> Using query objects</a> +</h3></div></div></div> +<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: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + You can precompile expressions to query objects to save compilation time + if it becomes an issue; + </li> +<li class="listitem"> + You can use query objects to evaluate XPath expressions which result + in booleans, numbers or strings; + </li> +<li class="listitem"> + You can get the type of expression value via query object. + </li> +</ul></div> +<p> + Query objects correspond to <code class="computeroutput"><span class="identifier">xpath_query</span></code> + type. They are immutable and non-copyable: they are bound to the expression + at creation time and can not be cloned. If you want to put query objects + in a container, allocate them on heap via <code class="computeroutput"><span class="keyword">new</span></code> + operator and store pointers to <code class="computeroutput"><span class="identifier">xpath_query</span></code> + in the container. + </p> +<a name="xpath_query::ctor"></a><p> + 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> +<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: + </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> +<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. + </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> + Calling <code class="computeroutput"><span class="identifier">node</span><span class="special">.</span><span class="identifier">select_nodes</span><span class="special">(</span><span class="string">"query"</span><span class="special">)</span></code> + 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> +<p> + This is an example of using query objects (<a href="../samples/xpath_query.cpp" target="_top">samples/xpath_query.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_query</span> <span class="identifier">query_remote_tools</span><span class="special">(</span><span class="string">"/Profile/Tools/Tool[@AllowRemote='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</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</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="comment">// Evaluate numbers via compiled query +</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_query</span> <span class="identifier">query_timeouts</span><span class="special">(</span><span class="string">"sum(//Tool/@Timeout)"</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">query_timeouts</span><span class="special">.</span><span class="identifier">evaluate_number</span><span class="special">(</span><span class="identifier">doc</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> + +<span class="comment">// Evaluate strings via compiled query for different context nodes +</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_query</span> <span class="identifier">query_name_valid</span><span class="special">(</span><span class="string">"string-length(substring-before(@Filename, '_')) > 0 and @OutputFileMasks"</span><span class="special">);</span> +<span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_query</span> <span class="identifier">query_name</span><span class="special">(</span><span class="string">"concat(substring-before(@Filename, '_'), ' produces ', @OutputFileMasks)"</span><span class="special">);</span> + +<span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">tool</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">first_element_by_path</span><span class="special">(</span><span class="string">"Profile/Tools/Tool"</span><span class="special">);</span> <span class="identifier">tool</span><span class="special">;</span> <span class="identifier">tool</span> <span class="special">=</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">next_sibling</span><span class="special">())</span> +<span class="special">{</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">s</span> <span class="special">=</span> <span class="identifier">query_name</span><span class="special">.</span><span class="identifier">evaluate_string</span><span class="special">(</span><span class="identifier">tool</span><span class="special">);</span> + + <span class="keyword">if</span> <span class="special">(</span><span class="identifier">query_name_valid</span><span class="special">.</span><span class="identifier">evaluate_boolean</span><span class="special">(</span><span class="identifier">tool</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">s</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</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> +<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> +<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> +</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. + </p> +<p> + This is an example of XPath error handling (<a href="../samples/xpath_error.cpp" target="_top">samples/xpath_error.cpp</a>): + </p> +<p> + +</p> +<pre class="programlisting"><span class="comment">// Exception is thrown for incorrect query syntax +</span><span class="keyword">try</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">"//nodes[#true()]"</span><span class="special">);</span> +<span class="special">}</span> +<span class="keyword">catch</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_exception</span><span class="special">&</span> <span class="identifier">e</span><span class="special">)</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">"Select failed: "</span> <span class="special"><<</span> <span class="identifier">e</span><span class="special">.</span><span class="identifier">what</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> +<span class="special">}</span> + +<span class="comment">// Exception is thrown for incorrect query semantics +</span><span class="keyword">try</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">"(123)/next"</span><span class="special">);</span> +<span class="special">}</span> +<span class="keyword">catch</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_exception</span><span class="special">&</span> <span class="identifier">e</span><span class="special">)</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">"Select failed: "</span> <span class="special"><<</span> <span class="identifier">e</span><span class="special">.</span><span class="identifier">what</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> +<span class="special">}</span> + +<span class="comment">// Exception is thrown for query with incorrect return type +</span><span class="keyword">try</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">"123"</span><span class="special">);</span> +<span class="special">}</span> +<span class="keyword">catch</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_exception</span><span class="special">&</span> <span class="identifier">e</span><span class="special">)</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">"Select failed: "</span> <span class="special"><<</span> <span class="identifier">e</span><span class="special">.</span><span class="identifier">what</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="manual.xpath.w3c"></a><a class="link" href="xpath.html#manual.xpath.w3c" title="Conformance to W3C specification"> Conformance to W3C specification</a> +</h3></div></div></div> +<p> + Because of the differences in document object models, performance considerations + and implementation complexity, pugixml does not provide a fully conformant + XPath 1.0 implementation. This is the current list of incompatibilities: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Consecutive text nodes sharing the same parent are not merged, i.e. in + <code class="computeroutput"><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">CDATA</span><span class="special">[</span><span class="identifier">data</span><span class="special">]]></span> <span class="identifier">text2</span><span class="special"></</span><span class="identifier">node</span><span class="special">></span></code> node should have one text node children, + 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> + function always returns an empty node set. + </li> +<li class="listitem"> + Namespace nodes are not supported (affects namespace:: axis). + </li> +<li class="listitem"> + Name tests are performed on QNames in XML document instead of expanded + names; for <code class="computeroutput"><span class="special"><</span><span class="identifier">foo</span> + <span class="identifier">xmlns</span><span class="special">:</span><span class="identifier">ns1</span><span class="special">=</span><span class="char">'uri'</span> <span class="identifier">xmlns</span><span class="special">:</span><span class="identifier">ns2</span><span class="special">=</span><span class="char">'uri'</span><span class="special">><</span><span class="identifier">ns1</span><span class="special">:</span><span class="identifier">child</span><span class="special">/><</span><span class="identifier">ns2</span><span class="special">:</span><span class="identifier">child</span><span class="special">/></</span><span class="identifier">foo</span><span class="special">></span></code>, + query <code class="computeroutput"><span class="identifier">foo</span><span class="special">/</span><span class="identifier">ns1</span><span class="special">:*</span></code> + will return only the first child, not both of them. Compliant XPath implementations + can return both nodes if the user provides appropriate namespace declarations. + </li> +<li class="listitem"> + String functions consider a character to be either a single <code class="computeroutput"><span class="keyword">char</span></code> value or a single <code class="computeroutput"><span class="keyword">wchar_t</span></code> + 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> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2010 Arseny Kapoulkine<p> + Distributed under the MIT License + </p> +</div></td> +</tr></table> +<hr> +<table width="100%"><tr> +<td>pugixml 0.9 manual | + <a href="../manual.html">Overview</a> | + <a href="install.html">Installation</a> | + Document: + <a href="dom.html">Object model</a> · <a href="loading.html">Loading</a> · <a href="access.html">Accessing</a> · <a href="modify.html">Modifying</a> · <a href="saving.html">Saving</a> | + <b>XPath</b> | + <a href="apiref.html">API Reference</a> | + <a href="toc.html">Table of Contents</a> +</td> +<td width="*" align="right"><div class="spirit-nav"> +<a accesskey="p" href="saving.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../manual.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../manual.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="changes.html"><img src="../images/next.png" alt="Next"></a> +</div></td> +</tr></table> +</body> +</html> diff --git a/docs/quickstart.html b/docs/quickstart.html new file mode 100644 index 0000000..4fc4524 --- /dev/null +++ b/docs/quickstart.html @@ -0,0 +1,828 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>pugixml 0.9</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"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="book"><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> +</h2></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="quickstart.html#quickstart.main.introduction"> Introduction</a></span></dt> +<dt><span class="section"><a href="quickstart.html#quickstart.main.install"> Installation</a></span></dt> +<dt><span class="section"><a href="quickstart.html#quickstart.main.dom"> Document object model</a></span></dt> +<dt><span class="section"><a href="quickstart.html#quickstart.main.loading"> Loading document</a></span></dt> +<dt><span class="section"><a href="quickstart.html#quickstart.main.access"> Accessing document data</a></span></dt> +<dt><span class="section"><a href="quickstart.html#quickstart.main.modify"> Modifying document data</a></span></dt> +<dt><span class="section"><a href="quickstart.html#quickstart.main.saving"> Saving document</a></span></dt> +<dt><span class="section"><a href="quickstart.html#quickstart.main.feedback"> Feedback</a></span></dt> +<dt><span class="section"><a href="quickstart.html#quickstart.main.license"> License</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<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. + </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. + </p> +<p> + This is the quick start guide for pugixml, which purpose is to enable you + to start using the library quickly. Many important library features are either + not described at all or only mentioned briefly; for more complete information + you <a href="manual.html" target="_top">should read the complete manual</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> + No documentation is perfect, neither is this one. If you encounter a description + that is unclear, please file an issue as described in <a class="xref" href="quickstart.html#quickstart.main.feedback" title="Feedback"> Feedback</a>. Also if + you can spare the time for a full proof-reading, including spelling and + grammar, that would be great! Please <a class="link" href="quickstart.html#email">send me an e-mail</a>; + as a token of appreciation, your name will be included into the corresponding + section of the manual. + </p></td></tr> +</table></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="quickstart.main.install"></a><a class="link" href="quickstart.html#quickstart.main.install" title="Installation"> Installation</a> +</h3></div></div></div> +<p> + 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> +<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. + </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 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>) + 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> +<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="id1329323" href="#ftn.id1329323" 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. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="quickstart.main.dom"></a><a class="link" href="quickstart.html#quickstart.main.dom" title="Document object model"> Document object model</a> +</h3></div></div></div> +<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, + C++ I/O stream or custom transport). + </p> +<p> + 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). + </p> +<p> + The most common node types are: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + Document node (<code class="computeroutput"><span class="identifier">node_document</span></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. + </li> +<li class="listitem"> + Element/tag node (<code class="computeroutput"><span class="identifier">node_element</span></code>) + - this 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. + </li> +<li class="listitem"> + Plain character data nodes (<code class="computeroutput"><span class="identifier">node_pcdata</span></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. + </li> +</ul></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>, + <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. + </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> + All pugixml classes and functions are located in <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>). + </p></td></tr> +</table></div> +<p> + <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. + </p> +<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. 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. + </p> +<p> + There is a special value of <code class="computeroutput"><span class="identifier">xml_node</span></code> + type, known as null node or empty node. It does not correspond to any node + in any document, and thus resembles null pointer. However, all operations + are defined on empty nodes; generally the operations don't do anything and + return empty nodes/attributes or empty strings as their result. 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. You can test if a handle is null via + implicit boolean cast: <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></code>. + </p> +<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. + </p> +<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. 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. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="quickstart.main.loading"></a><a class="link" href="quickstart.html#quickstart.main.loading" title="Loading document"> Loading document</a> +</h3></div></div></div> +<p> + pugixml provides several functions for loading XML data from various places + - files, C++ iostreams, memory buffers. All functions use an extremely fast + 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. XML data is always converted + to internal character format before parsing. pugixml supports all popular + Unicode encodings (UTF-8, UTF-16 (big and little endian), UTF-32 (big and + little endian); UCS-2 is naturally supported since it's a strict subset of + UTF-16) and handles all encoding conversions automatically. + </p> +<p> + The most common source of XML data is files; pugixml provides a separate + function for loading XML document from file. This function accepts file path + as its first argument, and also two optional arguments, which specify parsing + options and input data encoding, which are described in the manual. + </p> +<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> +<p> + +</p> +<pre class="programlisting"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_document</span> <span class="identifier">doc</span><span class="special">;</span> + +<span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_parse_result</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">load_file</span><span class="special">(</span><span class="string">"tree.xml"</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">"Load result: "</span> <span class="special"><<</span> <span class="identifier">result</span><span class="special">.</span><span class="identifier">description</span><span class="special">()</span> <span class="special"><<</span> <span class="string">", mesh name: "</span> <span class="special"><<</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">child</span><span class="special">(</span><span class="string">"mesh"</span><span class="special">).</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"name"</span><span class="special">).</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> +</pre> +<p> + </p> +<p> + <code class="computeroutput"><span class="identifier">load_file</span></code>, as well as other + loading functions, 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 + (i.e. last successfully parsed position in the input file, if parsing fails). + </p> +<p> + Parsing result object can be implicitly converted to <code class="computeroutput"><span class="keyword">bool</span></code>; + if you do not want to handle parsing errors thoroughly, you can just check + the return value of load functions as if it was a <code class="computeroutput"><span class="keyword">bool</span></code>: + <code class="computeroutput"><span class="keyword">if</span> <span class="special">(</span><span class="identifier">doc</span><span class="special">.</span><span class="identifier">load_file</span><span class="special">(</span><span class="string">"file.xml"</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>. + Otherwise you can use the <code class="computeroutput"><span class="identifier">status</span></code> + member to get parsing status, or the <code class="computeroutput"><span class="identifier">description</span><span class="special">()</span></code> member function to get the status in a + string form. + </p> +<p> + This is an example of handling loading errors (<a href="samples/load_error_handling.cpp" target="_top">samples/load_error_handling.cpp</a>): + </p> +<p> + +</p> +<pre class="programlisting"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_document</span> <span class="identifier">doc</span><span class="special">;</span> +<span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_parse_result</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">load</span><span class="special">(</span><span class="identifier">source</span><span class="special">);</span> + +<span class="keyword">if</span> <span class="special">(</span><span class="identifier">result</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">"XML ["</span> <span class="special"><<</span> <span class="identifier">source</span> <span class="special"><<</span> <span class="string">"] parsed without errors, attr value: ["</span> <span class="special"><<</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">child</span><span class="special">(</span><span class="string">"node"</span><span class="special">).</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"attr"</span><span class="special">).</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"]\n\n"</span><span class="special">;</span> +<span class="keyword">else</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">"XML ["</span> <span class="special"><<</span> <span class="identifier">source</span> <span class="special"><<</span> <span class="string">"] parsed with errors, attr value: ["</span> <span class="special"><<</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">child</span><span class="special">(</span><span class="string">"node"</span><span class="special">).</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"attr"</span><span class="special">).</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"]\n"</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">"Error description: "</span> <span class="special"><<</span> <span class="identifier">result</span><span class="special">.</span><span class="identifier">description</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"\n"</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">"Error offset: "</span> <span class="special"><<</span> <span class="identifier">result</span><span class="special">.</span><span class="identifier">offset</span> <span class="special"><<</span> <span class="string">" (error at [..."</span> <span class="special"><<</span> <span class="special">(</span><span class="identifier">source</span> <span class="special">+</span> <span class="identifier">result</span><span class="special">.</span><span class="identifier">offset</span><span class="special">)</span> <span class="special"><<</span> <span class="string">"]\n\n"</span><span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + </p> +<p> + Sometimes XML data should be loaded from some other source than 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. These scenarios either require loading document + from memory, in which case you should prepare a contiguous memory block with + all XML data and to pass it to one of buffer loading functions, or loading + document from C++ IOstream, in which case you should provide an object which + implements <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">istream</span></code> or <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wistream</span></code> + interface. + </p> +<p> + There are different functions for loading document from memory; they treat + the passed buffer as either an immutable one (<code class="computeroutput"><span class="identifier">load_buffer</span></code>), + a mutable buffer which is owned by the caller (<code class="computeroutput"><span class="identifier">load_buffer_inplace</span></code>), + or a mutable buffer which ownership belongs to pugixml (<code class="computeroutput"><span class="identifier">load_buffer_inplace_own</span></code>). + There is also a simple helper function, <code class="computeroutput"><span class="identifier">xml_document</span><span class="special">::</span><span class="identifier">load</span></code>, + for cases when you want to load the XML document from null-terminated character + string. + </p> +<p> + This is an example of loading XML document from memory using one of these + functions (<a href="samples/load_memory.cpp" target="_top">samples/load_memory.cpp</a>); + read the sample code for more examples: + </p> +<p> + +</p> +<pre class="programlisting"><span class="keyword">const</span> <span class="keyword">char</span> <span class="identifier">source</span><span class="special">[]</span> <span class="special">=</span> <span class="string">"<mesh name='sphere'><bounds>0 0 1 1</bounds></mesh>"</span><span class="special">;</span> +<span class="identifier">size_t</span> <span class="identifier">size</span> <span class="special">=</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">source</span><span class="special">);</span> +</pre> +<p> + </p> +<p> + +</p> +<pre class="programlisting"><span class="comment">// You can use load_buffer_inplace to load document from mutable memory block; the block's lifetime must exceed that of document +</span><span class="keyword">char</span><span class="special">*</span> <span class="identifier">buffer</span> <span class="special">=</span> <span class="keyword">new</span> <span class="keyword">char</span><span class="special">[</span><span class="identifier">size</span><span class="special">];</span> +<span class="identifier">memcpy</span><span class="special">(</span><span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">source</span><span class="special">,</span> <span class="identifier">size</span><span class="special">);</span> + +<span class="comment">// The block can be allocated by any method; the block is modified during parsing +</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_parse_result</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">load_buffer_inplace</span><span class="special">(</span><span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">size</span><span class="special">);</span> + +<span class="comment">// You have to destroy the block yourself after the document is no longer used +</span><span class="keyword">delete</span><span class="special">[]</span> <span class="identifier">buffer</span><span class="special">;</span> +</pre> +<p> + </p> +<p> + This is a simple example of loading XML document from file using streams + (<a href="samples/load_stream.cpp" target="_top">samples/load_stream.cpp</a>); read + the sample code for more complex examples involving wide streams and locales: + </p> +<p> + +</p> +<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ifstream</span> <span class="identifier">stream</span><span class="special">(</span><span class="string">"weekly-utf-8.xml"</span><span class="special">);</span> +<span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_parse_result</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">load</span><span class="special">(</span><span class="identifier">stream</span><span class="special">);</span> +</pre> +<p> + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="quickstart.main.access"></a><a class="link" href="quickstart.html#quickstart.main.access" title="Accessing document data"> Accessing document data</a> +</h3></div></div></div> +<p> + pugixml features an extensive interface for getting various types of data + from the document and for traversing the document. You can use various accessors + to get node/attribute data, you can traverse the child node/attribute lists + via accessors or iterators, you can do depth-first traversals with <code class="computeroutput"><span class="identifier">xml_tree_walker</span></code> objects, and you can use + XPath for complex data-driven queries. + </p> +<p> + You can get node or attribute name via <code class="computeroutput"><span class="identifier">name</span><span class="special">()</span></code> accessor, and value via <code class="computeroutput"><span class="identifier">value</span><span class="special">()</span></code> accessor. Note that both functions never + return null pointers - they either return a string with the relevant content, + or an empty string if name/value is absent or if the handle is null. Also + there are two notable things for reading values: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + 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 <code class="computeroutput"><span class="identifier">child_value</span><span class="special">()</span></code> helper functions to parse such data. + </li> +<li class="listitem"> + 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. + </li> +</ul></div> +<p> + This is an example of using these functions (<a href="samples/traverse_base.cpp" target="_top">samples/traverse_base.cpp</a>): + </p> +<p> + +</p> +<pre class="programlisting"><span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">tool</span> <span class="special">=</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">child</span><span class="special">(</span><span class="string">"Tool"</span><span class="special">);</span> <span class="identifier">tool</span><span class="special">;</span> <span class="identifier">tool</span> <span class="special">=</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">next_sibling</span><span class="special">(</span><span class="string">"Tool"</span><span class="special">))</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">"Tool "</span> <span class="special"><<</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"Filename"</span><span class="special">).</span><span class="identifier">value</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">": AllowRemote "</span> <span class="special"><<</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"AllowRemote"</span><span class="special">).</span><span class="identifier">as_bool</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">", Timeout "</span> <span class="special"><<</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"Timeout"</span><span class="special">).</span><span class="identifier">as_int</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">", Description '"</span> <span class="special"><<</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">child_value</span><span class="special">(</span><span class="string">"Description"</span><span class="special">)</span> <span class="special"><<</span> <span class="string">"'\n"</span><span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + </p> +<p> + Since a lot of document traversal consists of finding the node/attribute + with the correct name, there are special functions for that purpose. For + example, <code class="computeroutput"><span class="identifier">child</span><span class="special">(</span><span class="string">"Tool"</span><span class="special">)</span></code> + returns the first node which has the name <code class="computeroutput"><span class="string">"Tool"</span></code>, + or null handle if there is no such node. This is an example of using such + functions (<a href="samples/traverse_base.cpp" target="_top">samples/traverse_base.cpp</a>): + </p> +<p> + +</p> +<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Tool for *.dae generation: "</span> <span class="special"><<</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">find_child_by_attribute</span><span class="special">(</span><span class="string">"Tool"</span><span class="special">,</span> <span class="string">"OutputFileMasks"</span><span class="special">,</span> <span class="string">"*.dae"</span><span class="special">).</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"Filename"</span><span class="special">).</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"\n"</span><span class="special">;</span> + +<span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">tool</span> <span class="special">=</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">child</span><span class="special">(</span><span class="string">"Tool"</span><span class="special">);</span> <span class="identifier">tool</span><span class="special">;</span> <span class="identifier">tool</span> <span class="special">=</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">next_sibling</span><span class="special">(</span><span class="string">"Tool"</span><span class="special">))</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">"Tool "</span> <span class="special"><<</span> <span class="identifier">tool</span><span class="special">.</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"Filename"</span><span class="special">).</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"\n"</span><span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + </p> +<p> + Child node lists and attribute lists are simply double-linked lists; while + you can use <code class="computeroutput"><span class="identifier">previous_sibling</span></code>/<code class="computeroutput"><span class="identifier">next_sibling</span></code> and other such functions for + iteration, pugixml additionally provides node and attribute iterators, so + that you can treat nodes as containers of other nodes or attributes. All + iterators are bidirectional and support all usual iterator operations. The + iterators are invalidated if the node/attribute objects they're pointing + to are removed from the tree; adding nodes/attributes does not invalidate + any iterators. + </p> +<p> + Here is an example of using iterators for document traversal (<a href="samples/traverse_iter.cpp" target="_top">samples/traverse_iter.cpp</a>): + </p> +<p> + +</p> +<pre class="programlisting"><span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node_iterator</span> <span class="identifier">it</span> <span class="special">=</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">begin</span><span class="special">();</span> <span class="identifier">it</span> <span class="special">!=</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">end</span><span class="special">();</span> <span class="special">++</span><span class="identifier">it</span><span class="special">)</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">"Tool:"</span><span class="special">;</span> + + <span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_attribute_iterator</span> <span class="identifier">ait</span> <span class="special">=</span> <span class="identifier">it</span><span class="special">-></span><span class="identifier">attributes_begin</span><span class="special">();</span> <span class="identifier">ait</span> <span class="special">!=</span> <span class="identifier">it</span><span class="special">-></span><span class="identifier">attributes_end</span><span class="special">();</span> <span class="special">++</span><span class="identifier">ait</span><span class="special">)</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">" "</span> <span class="special"><<</span> <span class="identifier">ait</span><span class="special">-></span><span class="identifier">name</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"="</span> <span class="special"><<</span> <span class="identifier">ait</span><span class="special">-></span><span class="identifier">value</span><span class="special">();</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">endl</span><span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + </p> +<p> + The methods described above allow traversal of immediate children of some + node; if you want to do a deep tree traversal, you'll have to do it via a + recursive function or some equivalent method. However, pugixml provides a + helper for depth-first traversal of a subtree. In order to use it, you have + to implement <code class="computeroutput"><span class="identifier">xml_tree_walker</span></code> + interface and to call <code class="computeroutput"><span class="identifier">traverse</span></code> + function. + </p> +<p> + This is an example of traversing tree hierarchy with xml_tree_walker (<a href="samples/traverse_walker.cpp" target="_top">samples/traverse_walker.cpp</a>): + </p> +<p> + +</p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">simple_walker</span><span class="special">:</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_tree_walker</span> +<span class="special">{</span> + <span class="keyword">virtual</span> <span class="keyword">bool</span> <span class="identifier">for_each</span><span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">node</span><span class="special">)</span> + <span class="special">{</span> + <span class="keyword">for</span> <span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special"><</span> <span class="identifier">depth</span><span class="special">();</span> <span class="special">++</span><span class="identifier">i</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">" "</span><span class="special">;</span> <span class="comment">// indentation +</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">node_types</span><span class="special">[</span><span class="identifier">node</span><span class="special">.</span><span class="identifier">type</span><span class="special">()]</span> <span class="special"><<</span> <span class="string">": name='"</span> <span class="special"><<</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">name</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"', value='"</span> <span class="special"><<</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"'\n"</span><span class="special">;</span> + + <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> <span class="comment">// continue traversal +</span> <span class="special">}</span> +<span class="special">};</span> +</pre> +<p> + </p> +<p> + +</p> +<pre class="programlisting"><span class="identifier">simple_walker</span> <span class="identifier">walker</span><span class="special">;</span> +<span class="identifier">doc</span><span class="special">.</span><span class="identifier">traverse</span><span class="special">(</span><span class="identifier">walker</span><span class="special">);</span> +</pre> +<p> + </p> +<p> + Finally, for complex queries often a higher-level DSL is needed. pugixml + provides an implementation of XPath 1.0 language for such queries. The complete + description of XPath usage can be found in the manual, but here are some + examples: + </p> +<p> + +</p> +<pre class="programlisting"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_node_set</span> <span class="identifier">tools</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='true' and @DeriveCaptionFrom='lastparam']"</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">"Tools:"</span><span class="special">;</span> + +<span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</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">it</span> <span class="special">=</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">begin</span><span class="special">();</span> <span class="identifier">it</span> <span class="special">!=</span> <span class="identifier">tools</span><span class="special">.</span><span class="identifier">end</span><span class="special">();</span> <span class="special">++</span><span class="identifier">it</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_node</span> <span class="identifier">node</span> <span class="special">=</span> <span class="special">*</span><span class="identifier">it</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">" "</span> <span class="special"><<</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">node</span><span class="special">().</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"Filename"</span><span class="special">).</span><span class="identifier">value</span><span class="special">();</span> +<span class="special">}</span> + +<span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_node</span> <span class="identifier">build_tool</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">select_single_node</span><span class="special">(</span><span class="string">"//Tool[contains(Description, 'build system')]"</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">"\nBuild tool: "</span> <span class="special"><<</span> <span class="identifier">build_tool</span><span class="special">.</span><span class="identifier">node</span><span class="special">().</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"Filename"</span><span class="special">).</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"\n"</span><span class="special">;</span> +</pre> +<p> + </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> + XPath functions throw <code class="computeroutput"><span class="identifier">xpath_exception</span></code> + objects on error; the sample above does not catch these exceptions. + </p></td></tr> +</table></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="quickstart.main.modify"></a><a class="link" href="quickstart.html#quickstart.main.modify" title="Modifying document data"> Modifying document data</a> +</h3></div></div></div> +<p> + The document in pugixml is fully mutable: you can completely change the document + structure and modify the data of nodes/attributes. All functions take care + of memory management and structural integrity themselves, so they always + result in structurally valid tree - however, it is possible to create an + invalid XML tree (for example, by adding two attributes with the same name + or by setting attribute/node name to empty/invalid string). Tree modification + is optimized for performance and for memory consumption, so if you have enough + memory you can create documents from scratch with pugixml and later save + them to file/stream instead of relying on error-prone manual text writing + and without too much overhead. + </p> +<p> + All member functions that change node/attribute data or structure are non-constant + and thus can not be called on constant handles. However, you can easily convert + constant handle to non-constant one by simple assignment: <code class="computeroutput"><span class="keyword">void</span> + <span class="identifier">foo</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="special">{</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">nc</span> <span class="special">=</span> <span class="identifier">n</span><span class="special">;</span> <span class="special">}</span></code>, so const-correctness + here mainly provides additional documentation. + </p> +<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. You can use <code class="computeroutput"><span class="identifier">set_name</span></code> and <code class="computeroutput"><span class="identifier">set_value</span></code> + member functions to set them. Similar functions are available for attributes; + however, the <code class="computeroutput"><span class="identifier">set_value</span></code> function + is overloaded for some other types except strings, like floating-point numbers. + Also, attribute value can be set using an assignment operator. This is an + example of setting node/attribute name and value (<a href="samples/modify_base.cpp" target="_top">samples/modify_base.cpp</a>): + </p> +<p> + +</p> +<pre class="programlisting"><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">child</span><span class="special">(</span><span class="string">"node"</span><span class="special">);</span> + +<span class="comment">// change node name +</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</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">"notnode"</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">", new node name: "</span> <span class="special"><<</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">name</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> + +<span class="comment">// change comment text +</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">last_child</span><span class="special">().</span><span class="identifier">set_value</span><span class="special">(</span><span class="string">"useless comment"</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">", new comment text: "</span> <span class="special"><<</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">last_child</span><span class="special">().</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> + +<span class="comment">// we can't change value of the element or name of the comment +</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">set_value</span><span class="special">(</span><span class="string">"1"</span><span class="special">)</span> <span class="special"><<</span> <span class="string">", "</span> <span class="special"><<</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">last_child</span><span class="special">().</span><span class="identifier">set_name</span><span class="special">(</span><span class="string">"2"</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> +</pre> +<p> + </p> +<p> + +</p> +<pre class="programlisting"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_attribute</span> <span class="identifier">attr</span> <span class="special">=</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"id"</span><span class="special">);</span> + +<span class="comment">// change attribute name/value +</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">attr</span><span class="special">.</span><span class="identifier">set_name</span><span class="special">(</span><span class="string">"key"</span><span class="special">)</span> <span class="special"><<</span> <span class="string">", "</span> <span class="special"><<</span> <span class="identifier">attr</span><span class="special">.</span><span class="identifier">set_value</span><span class="special">(</span><span class="string">"345"</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">", new attribute: "</span> <span class="special"><<</span> <span class="identifier">attr</span><span class="special">.</span><span class="identifier">name</span><span class="special">()</span> <span class="special"><<</span> <span class="string">"="</span> <span class="special"><<</span> <span class="identifier">attr</span><span class="special">.</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> + +<span class="comment">// we can use numbers or booleans +</span><span class="identifier">attr</span><span class="special">.</span><span class="identifier">set_value</span><span class="special">(</span><span class="number">1.234</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">"new attribute value: "</span> <span class="special"><<</span> <span class="identifier">attr</span><span class="special">.</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> + +<span class="comment">// we can also use assignment operators for more concise code +</span><span class="identifier">attr</span> <span class="special">=</span> <span class="keyword">true</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">"final attribute value: "</span> <span class="special"><<</span> <span class="identifier">attr</span><span class="special">.</span><span class="identifier">value</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> +</pre> +<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. + </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> + attribute() and child() functions do not add attributes or nodes to the + tree, so code like <code class="computeroutput"><span class="identifier">node</span><span class="special">.</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"id"</span><span class="special">)</span> <span class="special">=</span> <span class="number">123</span><span class="special">;</span></code> will not do anything if <code class="computeroutput"><span class="identifier">node</span></code> does not have an attribute with + name <code class="computeroutput"><span class="string">"id"</span></code>. Make sure + you're operating with existing attributes/nodes by adding them if necessary. + </p></td></tr> +</table></div> +<p> + This is an example of adding new attributes/nodes to the document (<a href="samples/modify_add.cpp" target="_top">samples/modify_add.cpp</a>): + </p> +<p> + +</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 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 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 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> +<span class="identifier">param</span><span class="special">.</span><span class="identifier">append_attribute</span><span class="special">(</span><span class="string">"value"</span><span class="special">)</span> <span class="special">=</span> <span class="number">1.1</span><span class="special">;</span> +<span class="identifier">param</span><span class="special">.</span><span class="identifier">insert_attribute_after</span><span class="special">(</span><span class="string">"type"</span><span class="special">,</span> <span class="identifier">param</span><span class="special">.</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"name"</span><span class="special">))</span> <span class="special">=</span> <span class="string">"float"</span><span class="special">;</span> +</pre> +<p> + </p> +<a name="xml_node::remove_attribute"></a><a name="xml_node::remove_child"></a><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. + Removing the attribute or node invalidates all handles to the same underlying + object, and also invalidates all iterators pointing to the same object. Removing + node also invalidates all past-the-end iterators to its attribute or child + node list. Be careful to ensure that all such handles and iterators either + do not exist or are not used after the attribute/node is removed. + </p> +<p> + This is an example of removing attributes/nodes from the document (<a href="samples/modify_remove.cpp" target="_top">samples/modify_remove.cpp</a>): + </p> +<p> + +</p> +<pre class="programlisting"><span class="comment">// remove description node with the whole subtree +</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">child</span><span class="special">(</span><span class="string">"node"</span><span class="special">);</span> +<span class="identifier">node</span><span class="special">.</span><span class="identifier">remove_child</span><span class="special">(</span><span class="string">"description"</span><span class="special">);</span> + +<span class="comment">// remove id attribute +</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">child</span><span class="special">(</span><span class="string">"param"</span><span class="special">);</span> +<span class="identifier">param</span><span class="special">.</span><span class="identifier">remove_attribute</span><span class="special">(</span><span class="string">"value"</span><span class="special">);</span> + +<span class="comment">// we can also remove nodes/attributes by handles +</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_attribute</span> <span class="identifier">id</span> <span class="special">=</span> <span class="identifier">param</span><span class="special">.</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"name"</span><span class="special">);</span> +<span class="identifier">param</span><span class="special">.</span><span class="identifier">remove_attribute</span><span class="special">(</span><span class="identifier">id</span><span class="special">);</span> +</pre> +<p> + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="quickstart.main.saving"></a><a class="link" href="quickstart.html#quickstart.main.saving" title="Saving document"> Saving document</a> +</h3></div></div></div> +<p> + Often after creating a new document or loading the existing one and processing + it, it is necessary to save the result back to file. Also it is occasionally + useful to output the whole document or a subtree to some stream; use cases + include debug printing, serialization via network or other text-oriented + medium, etc. pugixml provides several functions to output any subtree of + the document to a file, stream or another generic transport interface; these + functions allow to customize the output format, and also perform necessary + encoding conversions. + </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 + 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 + of saving XML document to file (<a href="samples/save_file.cpp" target="_top">samples/save_file.cpp</a>): + </p> +<p> + +</p> +<pre class="programlisting"><span class="comment">// save document to file +</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Saving result: "</span> <span class="special"><<</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">save_file</span><span class="special">(</span><span class="string">"save_file_output.xml"</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> +</pre> +<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> + stream as saving target. There are two functions, one works with narrow character + streams, another handles wide character ones. + </p> +<p> + This is a simple example of saving XML document to standard output (<a href="samples/save_stream.cpp" target="_top">samples/save_stream.cpp</a>): + </p> +<p> + +</p> +<pre class="programlisting"><span class="comment">// save document to standard output +</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Document:\n"</span><span class="special">;</span> +<span class="identifier">doc</span><span class="special">.</span><span class="identifier">save</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> +<p> + All of the above saving functions are implemented in terms of writer interface. + This is a simple interface with a single function, which is called several + times during output process with chunks of document data as input. In order + to output the document via some custom transport, for example sockets, you + should create an object which implements <code class="computeroutput"><span class="identifier">xml_writer_file</span></code> + interface and pass it to <code class="computeroutput"><span class="identifier">xml_document</span><span class="special">::</span><span class="identifier">save</span></code> + function. + </p> +<p> + This is a simple example of custom writer for saving document data to STL + string (<a href="samples/save_custom_writer.cpp" target="_top">samples/save_custom_writer.cpp</a>); + read the sample code for more complex examples: + </p> +<p> + +</p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">xml_string_writer</span><span class="special">:</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_writer</span> +<span class="special">{</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">result</span><span class="special">;</span> + + <span class="keyword">virtual</span> <span class="keyword">void</span> <span class="identifier">write</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">void</span><span class="special">*</span> <span class="identifier">data</span><span class="special">,</span> <span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">)</span> + <span class="special">{</span> + <span class="identifier">result</span> <span class="special">+=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">(</span><span class="keyword">static_cast</span><span class="special"><</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*>(</span><span class="identifier">data</span><span class="special">),</span> <span class="identifier">size</span><span class="special">);</span> + <span class="special">}</span> +<span class="special">};</span> +</pre> +<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. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="quickstart.main.feedback"></a><a class="link" href="quickstart.html#quickstart.main.feedback" title="Feedback"> Feedback</a> +</h3></div></div></div> +<p> + If you believe you've found a bug in pugixml, please file an issue via <a href="http://code.google.com/p/pugixml/issues/entry" target="_top">issue submission form</a>. + Be sure to include the relevant information so that the bug can be reproduced: + the version of pugixml, compiler version and target architecture, the code + that uses pugixml and exhibits the bug, etc. Feature requests and contributions + can be filed as issues, too. + </p> +<a name="email"></a><p> + If filing an issue is not possible due to privacy or other concerns, you + can contact pugixml author by e-mail directly: <a href="mailto:arseny.kapoulkine@gmail.com" target="_top">arseny.kapoulkine@gmail.com</a>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="quickstart.main.license"></a><a class="link" href="quickstart.html#quickstart.main.license" title="License"> License</a> +</h3></div></div></div> +<p> + The pugixml library is distributed under the MIT license: + </p> +<div class="blockquote"><blockquote class="blockquote"> +<p> + Copyright (c) 2006-2010 Arseny Kapoulkine + </p> +<p> + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the Software + is furnished to do so, subject to the following conditions: + </p> +<p> + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + </p> +<p> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS + IN THE SOFTWARE. + </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 11, 2010 at 16:13:56 GMT</small></p></td> +<td align="right"><div class="copyright-footer"></div></td> +</tr></table> +</body> +</html> |