summaryrefslogtreecommitdiff
path: root/docs/manual/modify.html
diff options
context:
space:
mode:
authorArseny Kapoulkine <arseny.kapoulkine@gmail.com>2014-02-28 06:01:16 +0000
committerArseny Kapoulkine <arseny.kapoulkine@gmail.com>2014-02-28 06:01:16 +0000
commit2094a4fd3da85c1972f215cb5977f6157590ff79 (patch)
tree30af367b434ca0f1dc8de193796e923d12f1c8aa /docs/manual/modify.html
parent6305ac11a88f4bd2ee9cbbabe8e71aaff075010e (diff)
docs: Regenerate HTML documentation
git-svn-id: https://pugixml.googlecode.com/svn/trunk@993 99668b35-9821-0410-8761-19e4c4f06640
Diffstat (limited to 'docs/manual/modify.html')
-rw-r--r--docs/manual/modify.html274
1 files changed, 173 insertions, 101 deletions
diff --git a/docs/manual/modify.html b/docs/manual/modify.html
index f2f7785..05b0fbe 100644
--- a/docs/manual/modify.html
+++ b/docs/manual/modify.html
@@ -3,16 +3,16 @@
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Modifying document data</title>
<link rel="stylesheet" href="../pugixml.css" type="text/css">
-<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
-<link rel="home" href="../manual.html" title="pugixml 1.2">
-<link rel="up" href="../manual.html" title="pugixml 1.2">
+<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
+<link rel="home" href="../manual.html" title="pugixml 1.4">
+<link rel="up" href="../manual.html" title="pugixml 1.4">
<link rel="prev" href="access.html" title="Accessing document data">
<link rel="next" href="saving.html" title="Saving document">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table width="100%"><tr>
<td>
-<a href="http://pugixml.org/">pugixml 1.2</a> manual |
+<a href="http://pugixml.org/">pugixml 1.4</a> manual |
<a href="../manual.html">Overview</a> |
<a href="install.html">Installation</a> |
Document:
@@ -28,15 +28,16 @@
<hr>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="manual.modify"></a><a class="link" href="modify.html" title="Modifying document data"> Modifying document data</a>
+<a name="manual.modify"></a><a class="link" href="modify.html" title="Modifying document data">Modifying document data</a>
</h2></div></div></div>
-<div class="toc"><dl>
-<dt><span class="section"><a href="modify.html#manual.modify.nodedata"> Setting node data</a></span></dt>
-<dt><span class="section"><a href="modify.html#manual.modify.attrdata"> Setting attribute data</a></span></dt>
-<dt><span class="section"><a href="modify.html#manual.modify.add"> Adding nodes/attributes</a></span></dt>
-<dt><span class="section"><a href="modify.html#manual.modify.remove"> Removing nodes/attributes</a></span></dt>
-<dt><span class="section"><a href="modify.html#manual.modify.text"> Working with text contents</a></span></dt>
-<dt><span class="section"><a href="modify.html#manual.modify.clone"> Cloning nodes/attributes</a></span></dt>
+<div class="toc"><dl class="toc">
+<dt><span class="section"><a href="modify.html#manual.modify.nodedata">Setting node data</a></span></dt>
+<dt><span class="section"><a href="modify.html#manual.modify.attrdata">Setting attribute data</a></span></dt>
+<dt><span class="section"><a href="modify.html#manual.modify.add">Adding nodes/attributes</a></span></dt>
+<dt><span class="section"><a href="modify.html#manual.modify.remove">Removing nodes/attributes</a></span></dt>
+<dt><span class="section"><a href="modify.html#manual.modify.text">Working with text contents</a></span></dt>
+<dt><span class="section"><a href="modify.html#manual.modify.clone">Cloning nodes/attributes</a></span></dt>
+<dt><span class="section"><a href="modify.html#manual.modify.fragments">Assembling document from fragments</a></span></dt>
</dl></div>
<p>
The document in pugixml is fully mutable: you can completely change the document
@@ -60,11 +61,12 @@
</p>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.modify.nodedata"></a><a class="link" href="modify.html#manual.modify.nodedata" title="Setting node data"> Setting node data</a>
+<a name="manual.modify.nodedata"></a><a class="link" href="modify.html#manual.modify.nodedata" title="Setting node data">Setting node data</a>
</h3></div></div></div>
-<a name="xml_node::set_name"></a><a name="xml_node::set_value"></a><p>
- As discussed before, nodes can have name and value, both of which are strings.
- Depending on node type, name or value may be absent. <a class="link" href="dom.html#node_document">node_document</a>
+<p>
+ <a name="xml_node::set_name"></a><a name="xml_node::set_value"></a>As discussed
+ before, nodes can have name and value, both of which are strings. Depending
+ on node type, name or value may be absent. <a class="link" href="dom.html#node_document">node_document</a>
nodes do not have a name or value, <a class="link" href="dom.html#node_element">node_element</a>
and <a class="link" href="dom.html#node_declaration">node_declaration</a> nodes always
have a name but never have a value, <a class="link" href="dom.html#node_pcdata">node_pcdata</a>,
@@ -96,31 +98,31 @@
This is an example of setting node name and value (<a href="../samples/modify_base.cpp" target="_top">samples/modify_base.cpp</a>):
</p>
<p>
-
</p>
<pre class="programlisting"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">node</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">child</span><span class="special">(</span><span class="string">"node"</span><span class="special">);</span>
-<span class="comment">// change node name
-</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&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="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="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>
+<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>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.modify.attrdata"></a><a class="link" href="modify.html#manual.modify.attrdata" title="Setting attribute data"> Setting attribute data</a>
+<a name="manual.modify.attrdata"></a><a class="link" href="modify.html#manual.modify.attrdata" title="Setting attribute data">Setting attribute data</a>
</h3></div></div></div>
-<a name="xml_attribute::set_name"></a><a name="xml_attribute::set_value"></a><p>
- All attributes have name and value, both of which are strings (value may
- be empty). You can set them with the following functions:
+<p>
+ <a name="xml_attribute::set_name"></a><a name="xml_attribute::set_value"></a>All
+ attributes have name and value, both of which are strings (value may be empty).
+ You can set them with the following functions:
</p>
<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">set_name</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">rhs</span><span class="special">);</span>
<span class="keyword">bool</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">set_value</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">rhs</span><span class="special">);</span>
@@ -142,6 +144,8 @@
<span class="keyword">bool</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">set_value</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">rhs</span><span class="special">);</span>
<span class="keyword">bool</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">set_value</span><span class="special">(</span><span class="keyword">double</span> <span class="identifier">rhs</span><span class="special">);</span>
<span class="keyword">bool</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">set_value</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">rhs</span><span class="special">);</span>
+<span class="keyword">bool</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">set_value</span><span class="special">(</span><span class="keyword">long</span> <span class="keyword">long</span> <span class="identifier">rhs</span><span class="special">);</span>
+<span class="keyword">bool</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">set_value</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="keyword">long</span> <span class="keyword">long</span> <span class="identifier">rhs</span><span class="special">);</span>
</pre>
<p>
The above functions convert the argument to string and then call the base
@@ -167,14 +171,14 @@
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
- There are no portable 64-bit types in C++, so there is no corresponding
- <code class="computeroutput"><span class="identifier">set_value</span></code> function. If
- your platform has a 64-bit integer, you can easily write such a function
- yourself.
+ <code class="computeroutput"><span class="identifier">set_value</span></code> overloads with
+ <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">long</span></code>
+ type are only available if your platform has reliable support for the type,
+ including string conversions.
</p></td></tr>
</table></div>
-<a name="xml_attribute::assign"></a><p>
- For convenience, all <code class="computeroutput"><span class="identifier">set_value</span></code>
+<p>
+ <a name="xml_attribute::assign"></a>For convenience, all <code class="computeroutput"><span class="identifier">set_value</span></code>
functions have the corresponding assignment operators:
</p>
<pre class="programlisting"><span class="identifier">xml_attribute</span><span class="special">&amp;</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="keyword">operator</span><span class="special">=(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">rhs</span><span class="special">);</span>
@@ -182,6 +186,8 @@
<span class="identifier">xml_attribute</span><span class="special">&amp;</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="keyword">operator</span><span class="special">=(</span><span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">rhs</span><span class="special">);</span>
<span class="identifier">xml_attribute</span><span class="special">&amp;</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="keyword">operator</span><span class="special">=(</span><span class="keyword">double</span> <span class="identifier">rhs</span><span class="special">);</span>
<span class="identifier">xml_attribute</span><span class="special">&amp;</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="keyword">operator</span><span class="special">=(</span><span class="keyword">bool</span> <span class="identifier">rhs</span><span class="special">);</span>
+<span class="identifier">xml_attribute</span><span class="special">&amp;</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="keyword">operator</span><span class="special">=(</span><span class="keyword">long</span> <span class="keyword">long</span> <span class="identifier">rhs</span><span class="special">);</span>
+<span class="identifier">xml_attribute</span><span class="special">&amp;</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="keyword">operator</span><span class="special">=(</span><span class="keyword">unsigned</span> <span class="keyword">long</span> <span class="keyword">long</span> <span class="identifier">rhs</span><span class="special">);</span>
</pre>
<p>
These operators simply call the right <code class="computeroutput"><span class="identifier">set_value</span></code>
@@ -193,20 +199,19 @@
This is an example of setting attribute name and value (<a href="../samples/modify_base.cpp" target="_top">samples/modify_base.cpp</a>):
</p>
<p>
-
</p>
<pre class="programlisting"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_attribute</span> <span class="identifier">attr</span> <span class="special">=</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">attribute</span><span class="special">(</span><span class="string">"id"</span><span class="special">);</span>
-<span class="comment">// change attribute name/value
-</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&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="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="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="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>
@@ -214,10 +219,11 @@
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.modify.add"></a><a class="link" href="modify.html#manual.modify.add" title="Adding nodes/attributes"> Adding nodes/attributes</a>
+<a name="manual.modify.add"></a><a class="link" href="modify.html#manual.modify.add" title="Adding nodes/attributes">Adding nodes/attributes</a>
</h3></div></div></div>
-<a name="xml_node::prepend_attribute"></a><a name="xml_node::append_attribute"></a><a name="xml_node::insert_attribute_after"></a><a name="xml_node::insert_attribute_before"></a><a name="xml_node::prepend_child"></a><a name="xml_node::append_child"></a><a name="xml_node::insert_child_after"></a><a name="xml_node::insert_child_before"></a><p>
- Nodes and attributes do not exist without a document tree, so you can't create
+<p>
+ <a name="xml_node::prepend_attribute"></a><a name="xml_node::append_attribute"></a><a name="xml_node::insert_attribute_after"></a><a name="xml_node::insert_attribute_before"></a><a name="xml_node::prepend_child"></a><a name="xml_node::append_child"></a><a name="xml_node::insert_child_after"></a><a name="xml_node::insert_child_before"></a>Nodes
+ and attributes do not exist without a document tree, so you can't create
them without adding them to some document. A node or attribute can be created
at the end of node/attribute list or before/after some other node:
</p>
@@ -260,7 +266,7 @@
All functions return the handle to the created object on success, and null
handle on failure. There are several reasons for failure:
</p>
-<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
Adding fails if the target node is null;
</li>
@@ -311,20 +317,19 @@
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>
+<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="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 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="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>
@@ -333,10 +338,11 @@
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.modify.remove"></a><a class="link" href="modify.html#manual.modify.remove" title="Removing nodes/attributes"> Removing nodes/attributes</a>
+<a name="manual.modify.remove"></a><a class="link" href="modify.html#manual.modify.remove" title="Removing nodes/attributes">Removing nodes/attributes</a>
</h3></div></div></div>
-<a name="xml_node::remove_attribute"></a><a name="xml_node::remove_child"></a><p>
- If you do not want your document to contain some node or attribute, you can
+<p>
+ <a name="xml_node::remove_attribute"></a><a name="xml_node::remove_child"></a>If
+ you do not want your document to contain some node or attribute, you can
remove it with one of the following functions:
</p>
<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">remove_attribute</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&amp;</span> <span class="identifier">a</span><span class="special">);</span>
@@ -350,7 +356,7 @@
attributes) from the document, and returns the operation result. Removing
fails if one of the following is true:
</p>
-<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
The node the function is called on is null;
</li>
@@ -388,18 +394,17 @@
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>
+<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="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="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>
@@ -407,7 +412,7 @@
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.modify.text"></a><a class="link" href="modify.html#manual.modify.text" title="Working with text contents"> Working with text contents</a>
+<a name="manual.modify.text"></a><a class="link" href="modify.html#manual.modify.text" title="Working with text contents">Working with text contents</a>
</h3></div></div></div>
<p>
pugixml provides a special class, <code class="computeroutput"><span class="identifier">xml_text</span></code>,
@@ -416,8 +421,8 @@
documentation for accessing document data</a>; this section describes
the modification interface of <code class="computeroutput"><span class="identifier">xml_text</span></code>.
</p>
-<a name="xml_text::set"></a><p>
- Once you have an <code class="computeroutput"><span class="identifier">xml_text</span></code>
+<p>
+ <a name="xml_text::set"></a>Once you have an <code class="computeroutput"><span class="identifier">xml_text</span></code>
object, you can set the text contents using the following function:
</p>
<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xml_text</span><span class="special">::</span><span class="identifier">set</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">rhs</span><span class="special">);</span>
@@ -434,14 +439,16 @@
an element node, this function creates the PCDATA child node if necessary
(i.e. if the element node does not have a PCDATA/CDATA child already).
</p>
-<a name="xml_text::set_value"></a><p>
- In addition to a string function, several functions are provided for handling
- text with numbers and booleans as contents:
+<p>
+ <a name="xml_text::set_value"></a>In addition to a string function, several
+ functions are provided for handling text with numbers and booleans as contents:
</p>
<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xml_text</span><span class="special">::</span><span class="identifier">set</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">rhs</span><span class="special">);</span>
<span class="keyword">bool</span> <span class="identifier">xml_text</span><span class="special">::</span><span class="identifier">set</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">rhs</span><span class="special">);</span>
<span class="keyword">bool</span> <span class="identifier">xml_text</span><span class="special">::</span><span class="identifier">set</span><span class="special">(</span><span class="keyword">double</span> <span class="identifier">rhs</span><span class="special">);</span>
<span class="keyword">bool</span> <span class="identifier">xml_text</span><span class="special">::</span><span class="identifier">set</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">rhs</span><span class="special">);</span>
+<span class="keyword">bool</span> <span class="identifier">xml_text</span><span class="special">::</span><span class="identifier">set</span><span class="special">(</span><span class="keyword">long</span> <span class="keyword">long</span> <span class="identifier">rhs</span><span class="special">);</span>
+<span class="keyword">bool</span> <span class="identifier">xml_text</span><span class="special">::</span><span class="identifier">set</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="keyword">long</span> <span class="keyword">long</span> <span class="identifier">rhs</span><span class="special">);</span>
</pre>
<p>
The above functions convert the argument to string and then call the base
@@ -450,8 +457,8 @@
functions. You can <a class="link" href="modify.html#xml_attribute::set_value">refer to documentation
for the attribute functions</a> for details.
</p>
-<a name="xml_text::assign"></a><p>
- For convenience, all <code class="computeroutput"><span class="identifier">set</span></code>
+<p>
+ <a name="xml_text::assign"></a>For convenience, all <code class="computeroutput"><span class="identifier">set</span></code>
functions have the corresponding assignment operators:
</p>
<pre class="programlisting"><span class="identifier">xml_text</span><span class="special">&amp;</span> <span class="identifier">xml_text</span><span class="special">::</span><span class="keyword">operator</span><span class="special">=(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">rhs</span><span class="special">);</span>
@@ -459,6 +466,8 @@
<span class="identifier">xml_text</span><span class="special">&amp;</span> <span class="identifier">xml_text</span><span class="special">::</span><span class="keyword">operator</span><span class="special">=(</span><span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">rhs</span><span class="special">);</span>
<span class="identifier">xml_text</span><span class="special">&amp;</span> <span class="identifier">xml_text</span><span class="special">::</span><span class="keyword">operator</span><span class="special">=(</span><span class="keyword">double</span> <span class="identifier">rhs</span><span class="special">);</span>
<span class="identifier">xml_text</span><span class="special">&amp;</span> <span class="identifier">xml_text</span><span class="special">::</span><span class="keyword">operator</span><span class="special">=(</span><span class="keyword">bool</span> <span class="identifier">rhs</span><span class="special">);</span>
+<span class="identifier">xml_text</span><span class="special">&amp;</span> <span class="identifier">xml_text</span><span class="special">::</span><span class="keyword">operator</span><span class="special">=(</span><span class="keyword">long</span> <span class="keyword">long</span> <span class="identifier">rhs</span><span class="special">);</span>
+<span class="identifier">xml_text</span><span class="special">&amp;</span> <span class="identifier">xml_text</span><span class="special">::</span><span class="keyword">operator</span><span class="special">=(</span><span class="keyword">unsigned</span> <span class="keyword">long</span> <span class="keyword">long</span> <span class="identifier">rhs</span><span class="special">);</span>
</pre>
<p>
These operators simply call the right <code class="computeroutput"><span class="identifier">set</span></code>
@@ -471,30 +480,29 @@
object to modify text contents (<a href="../samples/text.cpp" target="_top">samples/text.cpp</a>):
</p>
<p>
-
</p>
-<pre class="programlisting"><span class="comment">// change project version
-</span><span class="identifier">project</span><span class="special">.</span><span class="identifier">child</span><span class="special">(</span><span class="string">"version"</span><span class="special">).</span><span class="identifier">text</span><span class="special">()</span> <span class="special">=</span> <span class="number">1.2</span><span class="special">;</span>
+<pre class="programlisting"><span class="comment">// change project version</span>
+<span class="identifier">project</span><span class="special">.</span><span class="identifier">child</span><span class="special">(</span><span class="string">"version"</span><span class="special">).</span><span class="identifier">text</span><span class="special">()</span> <span class="special">=</span> <span class="number">1.2</span><span class="special">;</span>
-<span class="comment">// add description element and set the contents
-</span><span class="comment">// note that we do not have to explicitly add the node_pcdata child
-</span><span class="identifier">project</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">text</span><span class="special">().</span><span class="identifier">set</span><span class="special">(</span><span class="string">"a test project"</span><span class="special">);</span>
+<span class="comment">// add description element and set the contents</span>
+<span class="comment">// note that we do not have to explicitly add the node_pcdata child</span>
+<span class="identifier">project</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">text</span><span class="special">().</span><span class="identifier">set</span><span class="special">(</span><span class="string">"a test project"</span><span class="special">);</span>
</pre>
<p>
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.modify.clone"></a><a class="link" href="modify.html#manual.modify.clone" title="Cloning nodes/attributes"> Cloning nodes/attributes</a>
+<a name="manual.modify.clone"></a><a class="link" href="modify.html#manual.modify.clone" title="Cloning nodes/attributes">Cloning nodes/attributes</a>
</h3></div></div></div>
-<a name="xml_node::prepend_copy"></a><a name="xml_node::append_copy"></a><a name="xml_node::insert_copy_after"></a><a name="xml_node::insert_copy_before"></a><p>
- With the help of previously described functions, it is possible to create
- trees with any contents and structure, including cloning the existing data.
- However since this is an often needed operation, pugixml provides built-in
- node/attribute cloning facilities. Since nodes and attributes do not exist
- without a document tree, you can't create a standalone copy - you have to
- immediately insert it somewhere in the tree. For this, you can use one of
- the following functions:
+<p>
+ <a name="xml_node::prepend_copy"></a><a name="xml_node::append_copy"></a><a name="xml_node::insert_copy_after"></a><a name="xml_node::insert_copy_before"></a>With
+ the help of previously described functions, it is possible to create trees
+ with any contents and structure, including cloning the existing data. However
+ since this is an often needed operation, pugixml provides built-in node/attribute
+ cloning facilities. Since nodes and attributes do not exist without a document
+ tree, you can't create a standalone copy - you have to immediately insert
+ it somewhere in the tree. For this, you can use one of the following functions:
</p>
<pre class="programlisting"><span class="identifier">xml_attribute</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">append_copy</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&amp;</span> <span class="identifier">proto</span><span class="special">);</span>
<span class="identifier">xml_attribute</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">prepend_copy</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&amp;</span> <span class="identifier">proto</span><span class="special">);</span>
@@ -528,7 +536,7 @@
for more information</a>. There are additional caveats specific to cloning
functions:
</p>
-<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
Cloning null handles results in operation failure;
</li>
@@ -551,7 +559,6 @@
node cloning and usage of other document modification functions:
</p>
<p>
-
</p>
<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">load_preprocess</span><span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_document</span><span class="special">&amp;</span> <span class="identifier">doc</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">path</span><span class="special">);</span>
@@ -563,23 +570,23 @@
<span class="special">{</span>
<span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">include</span> <span class="special">=</span> <span class="identifier">child</span><span class="special">;</span>
- <span class="comment">// load new preprocessed document (note: ideally this should handle relative paths)
-</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">path</span> <span class="special">=</span> <span class="identifier">include</span><span class="special">.</span><span class="identifier">value</span><span class="special">();</span>
+ <span class="comment">// load new preprocessed document (note: ideally this should handle relative paths)</span>
+ <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">path</span> <span class="special">=</span> <span class="identifier">include</span><span class="special">.</span><span class="identifier">value</span><span class="special">();</span>
<span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_document</span> <span class="identifier">doc</span><span class="special">;</span>
<span class="keyword">if</span> <span class="special">(!</span><span class="identifier">load_preprocess</span><span class="special">(</span><span class="identifier">doc</span><span class="special">,</span> <span class="identifier">path</span><span class="special">))</span> <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span>
- <span class="comment">// insert the comment marker above include directive
-</span> <span class="identifier">node</span><span class="special">.</span><span class="identifier">insert_child_before</span><span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">node_comment</span><span class="special">,</span> <span class="identifier">include</span><span class="special">).</span><span class="identifier">set_value</span><span class="special">(</span><span class="identifier">path</span><span class="special">);</span>
+ <span class="comment">// insert the comment marker above include directive</span>
+ <span class="identifier">node</span><span class="special">.</span><span class="identifier">insert_child_before</span><span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">node_comment</span><span class="special">,</span> <span class="identifier">include</span><span class="special">).</span><span class="identifier">set_value</span><span class="special">(</span><span class="identifier">path</span><span class="special">);</span>
- <span class="comment">// copy the document above the include directive (this retains the original order!)
-</span> <span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">ic</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">first_child</span><span class="special">();</span> <span class="identifier">ic</span><span class="special">;</span> <span class="identifier">ic</span> <span class="special">=</span> <span class="identifier">ic</span><span class="special">.</span><span class="identifier">next_sibling</span><span class="special">())</span>
+ <span class="comment">// copy the document above the include directive (this retains the original order!)</span>
+ <span class="keyword">for</span> <span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">ic</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">first_child</span><span class="special">();</span> <span class="identifier">ic</span><span class="special">;</span> <span class="identifier">ic</span> <span class="special">=</span> <span class="identifier">ic</span><span class="special">.</span><span class="identifier">next_sibling</span><span class="special">())</span>
<span class="special">{</span>
<span class="identifier">node</span><span class="special">.</span><span class="identifier">insert_copy_before</span><span class="special">(</span><span class="identifier">ic</span><span class="special">,</span> <span class="identifier">include</span><span class="special">);</span>
<span class="special">}</span>
- <span class="comment">// remove the include node and move to the next child
-</span> <span class="identifier">child</span> <span class="special">=</span> <span class="identifier">child</span><span class="special">.</span><span class="identifier">next_sibling</span><span class="special">();</span>
+ <span class="comment">// remove the include node and move to the next child</span>
+ <span class="identifier">child</span> <span class="special">=</span> <span class="identifier">child</span><span class="special">.</span><span class="identifier">next_sibling</span><span class="special">();</span>
<span class="identifier">node</span><span class="special">.</span><span class="identifier">remove_child</span><span class="special">(</span><span class="identifier">include</span><span class="special">);</span>
<span class="special">}</span>
@@ -596,18 +603,83 @@
<span class="keyword">bool</span> <span class="identifier">load_preprocess</span><span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_document</span><span class="special">&amp;</span> <span class="identifier">doc</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">path</span><span class="special">)</span>
<span class="special">{</span>
- <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_parse_result</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">load_file</span><span class="special">(</span><span class="identifier">path</span><span class="special">,</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">parse_default</span> <span class="special">|</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">parse_pi</span><span class="special">);</span> <span class="comment">// for &lt;?include?&gt;
-</span>
+ <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_parse_result</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">load_file</span><span class="special">(</span><span class="identifier">path</span><span class="special">,</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">parse_default</span> <span class="special">|</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">parse_pi</span><span class="special">);</span> <span class="comment">// for &lt;?include?&gt;</span>
+
<span class="keyword">return</span> <span class="identifier">result</span> <span class="special">?</span> <span class="identifier">preprocess</span><span class="special">(</span><span class="identifier">doc</span><span class="special">)</span> <span class="special">:</span> <span class="keyword">false</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
</p>
</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="manual.modify.fragments"></a><a class="link" href="modify.html#manual.modify.fragments" title="Assembling document from fragments">Assembling document from fragments</a>
+</h3></div></div></div>
+<p>
+ <a name="xml_node::append_buffer"></a>pugixml provides several ways to assemble
+ an XML document from other XML documents. Assuming there is a set of document
+ fragments, represented as in-memory buffers, the implementation choices are
+ as follows:
+ </p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
+ Use a temporary document to parse the data from a string, then clone
+ the nodes to a destination node. For example:
+ </li></ul></div>
+<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">append_fragment</span><span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">target</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">buffer</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">pugi</span><span class="special">::</span><span class="identifier">xml_document</span> <span class="identifier">doc</span><span class="special">;</span>
+ <span class="keyword">if</span> <span class="special">(!</span><span class="identifier">doc</span><span class="special">.</span><span class="identifier">load_buffer</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="keyword">return</span> <span class="keyword">false</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">doc</span><span class="special">.</span><span class="identifier">first_child</span><span class="special">();</span> <span class="identifier">child</span><span class="special">;</span> <span class="identifier">child</span> <span class="special">=</span> <span class="identifier">child</span><span class="special">.</span><span class="identifier">next_sibling</span><span class="special">())</span>
+ <span class="identifier">target</span><span class="special">.</span><span class="identifier">append_copy</span><span class="special">(</span><span class="identifier">child</span><span class="special">);</span>
+<span class="special">}</span>
+</pre>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
+ Cache the parsing step - instead of keeping in-memory buffers, keep document
+ objects that already contain the parsed fragment:
+ </li></ul></div>
+<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">append_fragment</span><span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">target</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_document</span><span class="special">&amp;</span> <span class="identifier">cached_fragment</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">cached_fragment</span><span class="special">.</span><span class="identifier">first_child</span><span class="special">();</span> <span class="identifier">child</span><span class="special">;</span> <span class="identifier">child</span> <span class="special">=</span> <span class="identifier">child</span><span class="special">.</span><span class="identifier">next_sibling</span><span class="special">())</span>
+ <span class="identifier">target</span><span class="special">.</span><span class="identifier">append_copy</span><span class="special">(</span><span class="identifier">child</span><span class="special">);</span>
+<span class="special">}</span>
+</pre>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
+ Use xml_node::append_buffer directly:
+ </li></ul></div>
+<pre class="programlisting"><span class="identifier">xml_parse_result</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">append_buffer</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">void</span><span class="special">*</span> <span class="identifier">contents</span><span class="special">,</span> <span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">options</span> <span class="special">=</span> <span class="identifier">parse_default</span><span class="special">,</span> <span class="identifier">xml_encoding</span> <span class="identifier">encoding</span> <span class="special">=</span> <span class="identifier">encoding_auto</span><span class="special">);</span>
+</pre>
+<p>
+ The first method is more convenient, but slower than the other two. The relative
+ performance of <code class="computeroutput"><span class="identifier">append_copy</span></code>
+ and <code class="computeroutput"><span class="identifier">append_buffer</span></code> depends
+ on the buffer format - usually <code class="computeroutput"><span class="identifier">append_buffer</span></code>
+ is faster if the buffer is in native encoding (UTF-8 or wchar_t, depending
+ on <code class="computeroutput"><span class="identifier">PUGIXML_WCHAR_MODE</span></code>). At
+ the same time it might be less efficient in terms of memory usage - the implementation
+ makes a copy of the provided buffer, and the copy has the same lifetime as
+ the document - the memory used by that copy will be reclaimed after the document
+ is destroyed, but no sooner. Even deleting all nodes in the document, including
+ the appended ones, won't reclaim the memory.
+ </p>
+<p>
+ <code class="computeroutput"><span class="identifier">append_buffer</span></code> behaves in
+ the same way as <a class="link" href="loading.html#xml_document::load_buffer">xml_document::load_buffer</a>
+ - the input buffer is a byte buffer, with size in bytes; the buffer is not
+ modified and can be freed after the function returns.
+ </p>
+<p>
+ <a name="status_append_invalid_root"></a>Since <code class="computeroutput"><span class="identifier">append_buffer</span></code>
+ needs to append child nodes to the current node, it only works if the current
+ node is either document or element node. Calling <code class="computeroutput"><span class="identifier">append_buffer</span></code>
+ on a node with any other type results in an error with <code class="computeroutput"><span class="identifier">status_append_invalid_root</span></code>
+ status.
+ </p>
+</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
-<td align="right"><div class="copyright-footer">Copyright &#169; 2012 Arseny Kapoulkine<p>
+<td align="right"><div class="copyright-footer">Copyright &#169; 2014 Arseny Kapoulkine<p>
Distributed under the MIT License
</p>
</div></td>
@@ -615,7 +687,7 @@
<hr>
<table width="100%"><tr>
<td>
-<a href="http://pugixml.org/">pugixml 1.2</a> manual |
+<a href="http://pugixml.org/">pugixml 1.4</a> manual |
<a href="../manual.html">Overview</a> |
<a href="install.html">Installation</a> |
Document: