summaryrefslogtreecommitdiff
path: root/docs/quickstart.html
diff options
context:
space:
mode:
authorArseny Kapoulkine <arseny.kapoulkine@gmail.com>2015-03-21 21:04:28 -0700
committerArseny Kapoulkine <arseny.kapoulkine@gmail.com>2015-03-21 21:04:28 -0700
commit2843f91d008990e9940e19dbdf8cd906ad1c057d (patch)
tree1020355943afcb5ae9a1a19484958f5868911f43 /docs/quickstart.html
parent1a450b302a6339319ed2430312f536ca7690b6a6 (diff)
docs: Remove old HTML documentation
Diffstat (limited to 'docs/quickstart.html')
-rw-r--r--docs/quickstart.html880
1 files changed, 0 insertions, 880 deletions
diff --git a/docs/quickstart.html b/docs/quickstart.html
deleted file mode 100644
index b67765e..0000000
--- a/docs/quickstart.html
+++ /dev/null
@@ -1,880 +0,0 @@
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
-<title>pugixml 1.6</title>
-<link rel="stylesheet" href="pugixml.css" type="text/css">
-<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
-<link rel="home" href="quickstart.html" title="pugixml 1.6">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="article">
-<div class="section">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="quickstart.main"></a><a class="link" href="quickstart.html#quickstart.main" title="pugixml 1.6 quick start guide"> pugixml 1.6 quick start guide</a>
-</h2></div></div></div>
-<div class="toc"><dl class="toc">
-<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>
- <a href="http://pugixml.org/" target="_top">pugixml</a> is a light-weight C++ XML
- processing library. It consists of a DOM-like interface with rich traversal/modification
- capabilities, an extremely fast XML parser which constructs the DOM tree
- from an XML file/buffer, and an XPath 1.0 implementation for complex data-driven
- tree queries. Full Unicode support is also available, with Unicode interface
- variants and conversions between different Unicode encodings (which happen
- automatically during parsing/saving). The library is extremely portable and
- easy to integrate and use. pugixml is developed and maintained since 2006
- and has many users. All code is distributed under the <a class="link" href="quickstart.html#quickstart.main.license" title="License">MIT
- license</a>, making it completely free to use in both open-source and
- proprietary applications.
- </p>
-<p>
- pugixml enables very fast, convenient and memory-efficient XML document processing.
- 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="https://github.com/zeux/pugixml/releases/download/v1.6/pugixml-1.6.zip" target="_top">https://github.com/zeux/pugixml/releases/download/v1.6/pugixml-1.6.zip</a>
-<a href="https://github.com/zeux/pugixml/releases/download/v1.6/pugixml-1.6.tar.gz" target="_top">https://github.com/zeux/pugixml/releases/download/v1.6/pugixml-1.6.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. The files have different line endings depending on the archive format
- - <code class="filename">.zip</code> archive has Windows line endings, <code class="filename">.tar.gz</code> archive has Unix line endings.
- Otherwise the files in both archives are identical.
- </p>
-<p>
- The complete pugixml source consists of three files - one source file, <code class="filename">pugixml.cpp</code>,
- and two header files, <code class="filename">pugixml.hpp</code> and <code class="filename">pugiconfig.hpp</code>. <code class="filename">pugixml.hpp</code> is the primary
- header which you need to include in order to use pugixml classes/functions.
- The rest of this guide assumes that <code class="filename">pugixml.hpp</code> is either in the current directory
- or in one of include directories of your projects, so that <code class="computeroutput"><span class="preprocessor">#include</span> <span class="string">"pugixml.hpp"</span></code>
- can find the header; however you can also use relative path (i.e. <code class="computeroutput"><span class="preprocessor">#include</span> <span class="string">"../libs/pugixml/src/pugixml.hpp"</span></code>)
- 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 the source file, <code class="filename">pugixml.cpp</code>,
- along with the existing library/executable. This process depends on the method
- of building your application; for example, if you're using Microsoft Visual
- Studio<a href="#ftn.trademarks" class="footnote" name="trademarks"><sup class="footnote">[1]</sup></a>,
- Apple Xcode, Code::Blocks or any other IDE, just add <code class="filename">pugixml.cpp</code> to one of
- your projects. There are other building methods available, including building
- pugixml as a standalone static/shared library; <a href="manual/install.html#manual.install.building" target="_top">read
- the manual</a> for further information.
- </p>
-</div>
-<div class="section">
-<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" style="list-style-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 <span class="bold"><strong>plain character
- data is not a part of the element node but instead has its own node</strong></span>;
- 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 entire interface
- of <code class="computeroutput"><span class="identifier">xml_node</span></code>, which allows
- for document inspection and/or modification. Note that while <code class="computeroutput"><span class="identifier">xml_document</span></code> is a sub-class of <code class="computeroutput"><span class="identifier">xml_node</span></code>, <code class="computeroutput"><span class="identifier">xml_node</span></code>
- is not a polymorphic type; the inheritance is present only to simplify usage.
- </p>
-<p>
- <code class="computeroutput"><span class="identifier">xml_node</span></code> is the handle to
- 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 and there is a special null
- attribute value, which propagates to function results.
- </p>
-<p>
- There are two choices of interface and internal representation when configuring
- 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. <a href="manual/dom.html#manual.dom.unicode" target="_top">Read
- the manual</a> for additional information on Unicode interface.
- </p>
-</div>
-<div class="section">
-<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_string</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" style="list-style-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> and <code class="computeroutput"><span class="identifier">text</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>
- If your C++ compiler supports range-based for-loop (this is a C++11 feature,
- at the time of writing it's supported by Microsoft Visual Studio 11 Beta,
- GCC 4.6 and Clang 3.0), you can use it to enumerate nodes/attributes. Additional
- helpers are provided to support this; note that they are also compatible
- with <a href="http://www.boost.org/libs/foreach/" target="_top">Boost Foreach</a>,
- and possibly other pre-C++11 foreach facilities.
- </p>
-<p>
- Here is an example of using C++11 range-based for loop for document traversal
- (<a href="samples/traverse_rangefor.cpp" target="_top">samples/traverse_rangefor.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">children</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">;</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">attributes</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">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">}</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">tool</span><span class="special">.</span><span class="identifier">children</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">", child "</span> <span class="special">&lt;&lt;</span> <span class="identifier">child</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">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:\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">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="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">&lt;&lt;</span> <span class="string">"\n"</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_node</span><span class="special">(</span><span class="string">"//Tool[contains(Description, 'build system')]"</span><span class="special">);</span>
-
-<span class="keyword">if</span> <span class="special">(</span><span class="identifier">build_tool</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">"Build 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 without a document tree, so you can't create
- them without adding them to some document. A node or attribute can be created
- at the end of node/attribute list or before/after some other node. All insertion
- functions return the handle to newly created object on success, and null
- handle on failure. Even if the operation fails (for example, if you're trying
- to add a child node to PCDATA node), the document remains in consistent state,
- but the requested node/attribute is not added.
- </p>
-<div class="caution"><table border="0" summary="Caution">
-<tr>
-<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="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="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="string">"param"</span><span class="special">,</span> <span class="identifier">descr</span><span class="special">);</span>
-
-<span class="comment">// add attributes to param node
-</span><span class="identifier">param</span><span class="special">.</span><span class="identifier">append_attribute</span><span class="special">(</span><span class="string">"name"</span><span class="special">)</span> <span class="special">=</span> <span class="string">"version"</span><span class="special">;</span>
-<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>
-<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>
- Before writing to the destination the node/attribute data is 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 well-formed output, make sure all node and attribute names are set to
- meaningful values.
- </p>
-<p>
- If you want to save the whole document to a file, you can use the <code class="computeroutput"><span class="identifier">save_file</span></code> function, which returns <code class="computeroutput"><span class="keyword">true</span></code> on success. This is a simple example
- 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>
- To enhance interoperability pugixml provides functions for saving document
- to any object which implements C++ <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span></code>
- interface. This allows you to save documents to any standard C++ stream (i.e.
- file stream) or any third-party compliant implementation (i.e. Boost Iostreams).
- Most notably, this allows for easy debug output, since you can use <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span></code>
- stream as saving target. There are two functions, one works with narrow character
- streams, another handles wide character ones.
- </p>
-<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">append</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 save the whole document to the destination,
- it is easy to save a single subtree. Instead of calling <code class="computeroutput"><span class="identifier">xml_document</span><span class="special">::</span><span class="identifier">save</span></code>,
- just call <code class="computeroutput"><span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">print</span></code> function on the target node. You
- can save node contents to C++ IOstream object or custom writer in this way.
- Saving a subtree slightly differs from saving the whole document; <a href="manual/saving.html#manual.saving.subtree" target="_top">read the manual</a> for
- more information.
- </p>
-</div>
-<div class="section">
-<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="https://github.com/zeux/pugixml/issues/new" 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-2014 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>
-<p>
- This means that you can freely use pugixml in your applications, both open-source
- and proprietary. If you use pugixml in a product, it is sufficient to add
- an acknowledgment like this to the product distribution:
- </p>
-<div class="blockquote"><blockquote class="blockquote"><p>
- This software is based on pugixml library (http://pugixml.org).<br>
-pugixml
- is Copyright (C) 2006-2014 Arseny Kapoulkine.
- </p></blockquote></div>
-</div>
-</div>
-<div class="footnotes">
-<br><hr style="width:100; text-align:left;margin-left: 0">
-<div id="ftn.trademarks" class="footnote"><p><a href="#trademarks" class="para"><sup class="para">[1] </sup></a>All trademarks used are properties of their respective owners.</p></div>
-</div>
-</div>
-<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left"><p><small>Last revised: March 20, 2015 at 07:16:25 GMT</small></p></td>
-<td align="right"><div class="copyright-footer"></div></td>
-</tr></table>
-</body>
-</html>