summaryrefslogtreecommitdiff
path: root/docs/quickstart.html
diff options
context:
space:
mode:
Diffstat (limited to 'docs/quickstart.html')
-rw-r--r--docs/quickstart.html828
1 files changed, 828 insertions, 0 deletions
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">&lt;</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">&gt;</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">&lt;&lt;</span> <span class="string">"Load result: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">result</span><span class="special">.</span><span class="identifier">description</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">", mesh name: "</span> <span class="special">&lt;&lt;</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">&lt;&lt;</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">&lt;&lt;</span> <span class="string">"XML ["</span> <span class="special">&lt;&lt;</span> <span class="identifier">source</span> <span class="special">&lt;&lt;</span> <span class="string">"] parsed without errors, attr value: ["</span> <span class="special">&lt;&lt;</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">&lt;&lt;</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">&lt;&lt;</span> <span class="string">"XML ["</span> <span class="special">&lt;&lt;</span> <span class="identifier">source</span> <span class="special">&lt;&lt;</span> <span class="string">"] parsed with errors, attr value: ["</span> <span class="special">&lt;&lt;</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">&lt;&lt;</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">&lt;&lt;</span> <span class="string">"Error description: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">result</span><span class="special">.</span><span class="identifier">description</span><span class="special">()</span> <span class="special">&lt;&lt;</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">&lt;&lt;</span> <span class="string">"Error offset: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">result</span><span class="special">.</span><span class="identifier">offset</span> <span class="special">&lt;&lt;</span> <span class="string">" (error at [..."</span> <span class="special">&lt;&lt;</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">&lt;&lt;</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">"&lt;mesh name='sphere'&gt;&lt;bounds&gt;0 0 1 1&lt;/bounds&gt;&lt;/mesh&gt;"</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">&lt;</span><span class="identifier">node</span><span class="special">&gt;&lt;</span><span class="identifier">description</span><span class="special">&gt;</span><span class="identifier">This</span>
+ <span class="identifier">is</span> <span class="identifier">a</span>
+ <span class="identifier">node</span><span class="special">&lt;/</span><span class="identifier">description</span><span class="special">&gt;&lt;/</span><span class="identifier">node</span><span class="special">&gt;</span></code>.
+ In this case, <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">description</span><span class="special">&gt;</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">&lt;&lt;</span> <span class="string">"Tool "</span> <span class="special">&lt;&lt;</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">&lt;&lt;</span> <span class="string">": AllowRemote "</span> <span class="special">&lt;&lt;</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">&lt;&lt;</span> <span class="string">", Timeout "</span> <span class="special">&lt;&lt;</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">&lt;&lt;</span> <span class="string">", Description '"</span> <span class="special">&lt;&lt;</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">&lt;&lt;</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">&lt;&lt;</span> <span class="string">"Tool for *.dae generation: "</span> <span class="special">&lt;&lt;</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">&lt;&lt;</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">&lt;&lt;</span> <span class="string">"Tool "</span> <span class="special">&lt;&lt;</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">&lt;&lt;</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">&lt;&lt;</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">-&gt;</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">-&gt;</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">&lt;&lt;</span> <span class="string">" "</span> <span class="special">&lt;&lt;</span> <span class="identifier">ait</span><span class="special">-&gt;</span><span class="identifier">name</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">"="</span> <span class="special">&lt;&lt;</span> <span class="identifier">ait</span><span class="special">-&gt;</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">&lt;&lt;</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">&amp;</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">&lt;</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">&lt;&lt;</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">&lt;&lt;</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">&lt;&lt;</span> <span class="string">": name='"</span> <span class="special">&lt;&lt;</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">name</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">"', value='"</span> <span class="special">&lt;&lt;</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">value</span><span class="special">()</span> <span class="special">&lt;&lt;</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">&lt;&lt;</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">&lt;&lt;</span> <span class="string">" "</span> <span class="special">&lt;&lt;</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">&lt;&lt;</span> <span class="string">"\nBuild tool: "</span> <span class="special">&lt;&lt;</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">&lt;&lt;</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">&amp;</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">&lt;&lt;</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">&lt;&lt;</span> <span class="string">", new node name: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">name</span><span class="special">()</span> <span class="special">&lt;&lt;</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">&lt;&lt;</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">&lt;&lt;</span> <span class="string">", new comment text: "</span> <span class="special">&lt;&lt;</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">&lt;&lt;</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">&lt;&lt;</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">&lt;&lt;</span> <span class="string">", "</span> <span class="special">&lt;&lt;</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">&lt;&lt;</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">&lt;&lt;</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">&lt;&lt;</span> <span class="string">", "</span> <span class="special">&lt;&lt;</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">&lt;&lt;</span> <span class="string">", new attribute: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">attr</span><span class="special">.</span><span class="identifier">name</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">"="</span> <span class="special">&lt;&lt;</span> <span class="identifier">attr</span><span class="special">.</span><span class="identifier">value</span><span class="special">()</span> <span class="special">&lt;&lt;</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">&lt;&lt;</span> <span class="string">"new attribute value: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">attr</span><span class="special">.</span><span class="identifier">value</span><span class="special">()</span> <span class="special">&lt;&lt;</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">&lt;&lt;</span> <span class="string">"final attribute value: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">attr</span><span class="special">.</span><span class="identifier">value</span><span class="special">()</span> <span class="special">&lt;&lt;</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 &lt; and &amp;,
+ 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">&lt;&lt;</span> <span class="string">"Saving result: "</span> <span class="special">&lt;&lt;</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">&lt;&lt;</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">&lt;&lt;</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">&lt;</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*&gt;(</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>