summaryrefslogtreecommitdiff
path: root/docs/manual/dom.html
diff options
context:
space:
mode:
authorArseny Kapoulkine <arseny.kapoulkine@gmail.com>2014-11-20 23:47:00 -0800
committerArseny Kapoulkine <arseny.kapoulkine@gmail.com>2014-11-20 23:47:16 -0800
commitdb8df4a5665cfb24c1c18be438d10b2e310a234e (patch)
tree16d251ba91d88fd99343e9628348f912e0170f1a /docs/manual/dom.html
parentcca23e636354dc73429a19e14e32cc9a5e632735 (diff)
parent125aa55061ccde4ae7351a9a6c7270a15c9e0204 (diff)
Merge branch 'master' into compact
Diffstat (limited to 'docs/manual/dom.html')
-rw-r--r--docs/manual/dom.html196
1 files changed, 100 insertions, 96 deletions
diff --git a/docs/manual/dom.html b/docs/manual/dom.html
index 57d3ea0..3d7cd29 100644
--- a/docs/manual/dom.html
+++ b/docs/manual/dom.html
@@ -4,15 +4,15 @@
<title>Document object model</title>
<link rel="stylesheet" href="../pugixml.css" type="text/css">
<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="home" href="../manual.html" title="pugixml 1.5">
+<link rel="up" href="../manual.html" title="pugixml 1.5">
<link rel="prev" href="install.html" title="Installation">
<link rel="next" href="loading.html" title="Loading document">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table width="100%"><tr>
<td>
-<a href="http://pugixml.org/">pugixml 1.4</a> manual |
+<a href="http://pugixml.org/">pugixml 1.5</a> manual |
<a href="../manual.html">Overview</a> |
<a href="install.html">Installation</a> |
Document:
@@ -28,20 +28,20 @@
<hr>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="manual.dom"></a><a class="link" href="dom.html" title="Document object model">Document object model</a>
+<a name="manual.dom"></a><a class="link" href="dom.html" title="Document object model"> Document object model</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
-<dt><span class="section"><a href="dom.html#manual.dom.tree">Tree structure</a></span></dt>
-<dt><span class="section"><a href="dom.html#manual.dom.cpp">C++ interface</a></span></dt>
-<dt><span class="section"><a href="dom.html#manual.dom.unicode">Unicode interface</a></span></dt>
-<dt><span class="section"><a href="dom.html#manual.dom.thread">Thread-safety guarantees</a></span></dt>
-<dt><span class="section"><a href="dom.html#manual.dom.exception">Exception guarantees</a></span></dt>
-<dt><span class="section"><a href="dom.html#manual.dom.memory">Memory management</a></span></dt>
+<dt><span class="section"><a href="dom.html#manual.dom.tree"> Tree structure</a></span></dt>
+<dt><span class="section"><a href="dom.html#manual.dom.cpp"> C++ interface</a></span></dt>
+<dt><span class="section"><a href="dom.html#manual.dom.unicode"> Unicode interface</a></span></dt>
+<dt><span class="section"><a href="dom.html#manual.dom.thread"> Thread-safety guarantees</a></span></dt>
+<dt><span class="section"><a href="dom.html#manual.dom.exception"> Exception guarantees</a></span></dt>
+<dt><span class="section"><a href="dom.html#manual.dom.memory"> Memory management</a></span></dt>
<dd><dl>
-<dt><span class="section"><a href="dom.html#manual.dom.memory.custom">Custom memory allocation/deallocation
+<dt><span class="section"><a href="dom.html#manual.dom.memory.custom"> Custom memory allocation/deallocation
functions</a></span></dt>
-<dt><span class="section"><a href="dom.html#manual.dom.memory.tuning">Memory consumption tuning</a></span></dt>
-<dt><span class="section"><a href="dom.html#manual.dom.memory.internals">Document memory management
+<dt><span class="section"><a href="dom.html#manual.dom.memory.tuning"> Memory consumption tuning</a></span></dt>
+<dt><span class="section"><a href="dom.html#manual.dom.memory.internals"> Document memory management
internals</a></span></dt>
</dl></dd>
</dl></div>
@@ -56,7 +56,7 @@
</p>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.dom.tree"></a><a class="link" href="dom.html#manual.dom.tree" title="Tree structure">Tree structure</a>
+<a name="manual.dom.tree"></a><a class="link" href="dom.html#manual.dom.tree" title="Tree structure"> Tree structure</a>
</h3></div></div></div>
<p>
The XML document is represented with a tree data structure. The root of the
@@ -66,9 +66,9 @@
which correspond to C++ type <a class="link" href="dom.html#xml_attribute">xml_attribute</a>,
and some additional data (i.e. name).
</p>
-<p>
- <a name="xml_node_type"></a>The tree nodes can be of one of the following
- types (which together form the enumeration <code class="computeroutput"><span class="identifier">xml_node_type</span></code>):
+<a name="xml_node_type"></a><p>
+ The tree nodes can be of one of the following types (which together form
+ the enumeration <code class="computeroutput"><span class="identifier">xml_node_type</span></code>):
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
@@ -81,6 +81,7 @@
several ways, which are covered below. There can be only one document
node in the tree; document node does not have any XML representation.
<br><br>
+
</li>
<li class="listitem">
Element/tag node (<a name="node_element"></a><code class="literal">node_element</code>) - this
@@ -188,7 +189,7 @@
(its parent should be the document). The example XML representation of
a document type declaration node is as follows:
</li></ul></div>
-<pre class="programlisting"><span class="special">&lt;!</span><span class="identifier">DOCTYPE</span> <span class="identifier">greeting</span> <span class="special">[</span> <span class="special">&lt;!</span><span class="identifier">ELEMENT</span> <span class="identifier">greeting</span> <span class="special">(#</span><span class="identifier">PCDATA</span><span class="special">)&gt;</span> <span class="special">]&gt;</span>
+<pre class="programlisting"><span class="special">&lt;!</span><span class="identifier">DOCTYPE</span> <span class="identifier">greeting</span> <span class="special">[</span> <span class="special">&lt;!</span><span class="identifier">ELEMENT</span> <span class="identifier">greeting</span> <span class="special">(</span><span class="preprocessor">#PCDATA</span><span class="special">)&gt;</span> <span class="special">]&gt;</span>
</pre>
<div class="blockquote"><blockquote class="blockquote"><p>
Here the node has value <code class="computeroutput"><span class="string">"greeting [ &lt;!ELEMENT
@@ -208,6 +209,7 @@
<tbody><tr>
<td>
<p>
+
</p>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&lt;?</span><span class="identifier">xml</span> <span class="identifier">version</span><span class="special">=</span><span class="string">"1.0"</span><span class="special">?&gt;</span>
<span class="special">&lt;</span><span class="identifier">mesh</span> <span class="identifier">name</span><span class="special">=</span><span class="string">"mesh_root"</span><span class="special">&gt;</span>
@@ -235,7 +237,7 @@
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.dom.cpp"></a><a class="link" href="dom.html#manual.dom.cpp" title="C++ interface">C++ interface</a>
+<a name="manual.dom.cpp"></a><a class="link" href="dom.html#manual.dom.cpp" title="C++ interface"> C++ interface</a>
</h3></div></div></div>
<div class="note"><table border="0" summary="Note">
<tr>
@@ -259,18 +261,21 @@
some operations on <code class="computeroutput"><span class="identifier">xml_node</span></code>
are only valid for certain node types. The classes are described below.
</p>
-<p>
- <a name="xml_document"></a><a name="xml_document::document_element"></a><code class="computeroutput"><span class="identifier">xml_document</span></code> is the owner of the entire
- document structure; it is a non-copyable class. The interface of <code class="computeroutput"><span class="identifier">xml_document</span></code> consists of loading functions
- (see <a class="xref" href="loading.html" title="Loading document">Loading document</a>), saving functions (see <a class="xref" href="saving.html" title="Saving document">Saving document</a>) and the 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.
- Alternatively you can use the <code class="computeroutput"><span class="identifier">document_element</span></code>
- function to get the element node that's the immediate child of the document.
+<a name="xml_document"></a><a name="xml_document::document_element"></a><p>
+ <code class="computeroutput"><span class="identifier">xml_document</span></code> is the owner
+ of the entire document structure; it is a non-copyable class. The interface
+ of <code class="computeroutput"><span class="identifier">xml_document</span></code> consists
+ of loading functions (see <a class="xref" href="loading.html" title="Loading document"> Loading document</a>), saving functions (see <a class="xref" href="saving.html" title="Saving document"> Saving document</a>)
+ and the 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. Alternatively you can use
+ the <code class="computeroutput"><span class="identifier">document_element</span></code> function
+ to get the element node that's the immediate child of the document.
</p>
-<p>
- <a name="xml_document::ctor"></a><a name="xml_document::dtor"></a><a name="xml_document::reset"></a>Default constructor of <code class="computeroutput"><span class="identifier">xml_document</span></code>
+<a name="xml_document::ctor"></a><a name="xml_document::dtor"></a><a name="xml_document::reset"></a><p>
+ Default constructor of <code class="computeroutput"><span class="identifier">xml_document</span></code>
initializes the document to the tree with only a root node (document node).
You can then populate it with data using either tree modification functions
or loading functions; all loading functions destroy the previous tree with
@@ -295,12 +300,12 @@
are destroyed.
</p></td></tr>
</table></div>
-<p>
- <a name="xml_node"></a><a name="xml_node::type"></a><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 the document node itself. There is a common interface for nodes
- of all types; the actual <a class="link" href="dom.html#xml_node_type">node type</a> can
- be queried via the <code class="computeroutput"><span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">type</span><span class="special">()</span></code> method. Note that <code class="computeroutput"><span class="identifier">xml_node</span></code>
+<a name="xml_node"></a><a name="xml_node::type"></a><p>
+ <code class="computeroutput"><span class="identifier">xml_node</span></code> is the handle to
+ document node; it can point to any node in the document, including the document
+ node itself. There is a common interface for nodes of all types; the actual
+ <a class="link" href="dom.html#xml_node_type">node type</a> can be queried via the <code class="computeroutput"><span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">type</span><span class="special">()</span></code>
+ method. Note that <code class="computeroutput"><span class="identifier">xml_node</span></code>
is only a handle to the actual node, not the node itself - you can have several
<code class="computeroutput"><span class="identifier">xml_node</span></code> handles pointing
to the same underlying object. Destroying <code class="computeroutput"><span class="identifier">xml_node</span></code>
@@ -310,8 +315,8 @@
a pointer; you can safely pass or return <code class="computeroutput"><span class="identifier">xml_node</span></code>
objects by value without additional overhead.
</p>
-<p>
- <a name="node_null"></a>There is a special value of <code class="computeroutput"><span class="identifier">xml_node</span></code>
+<a name="node_null"></a><p>
+ There is a special value of <code class="computeroutput"><span class="identifier">xml_node</span></code>
type, known as null node or empty node (such nodes have type <code class="computeroutput"><span class="identifier">node_null</span></code>). It does not correspond to any
node in any document, and thus resembles null pointer. However, all operations
are defined on empty nodes; generally the operations don't do anything and
@@ -321,40 +326,37 @@
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, which makes error handling easier.
</p>
-<p>
- <a name="xml_attribute"></a><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.
+<a name="xml_attribute"></a><p>
+ <code class="computeroutput"><span class="identifier">xml_attribute</span></code> is the handle
+ to an XML attribute; it has the same semantics as <code class="computeroutput"><span class="identifier">xml_node</span></code>,
+ i.e. there can be several <code class="computeroutput"><span class="identifier">xml_attribute</span></code>
+ handles pointing to the same underlying object and there is a special null
+ attribute value, which propagates to function results.
</p>
-<p>
- <a name="xml_attribute::ctor"></a><a name="xml_node::ctor"></a>Both <code class="computeroutput"><span class="identifier">xml_node</span></code> and <code class="computeroutput"><span class="identifier">xml_attribute</span></code>
- have the default constructor which initializes them to null objects.
+<a name="xml_attribute::ctor"></a><a name="xml_node::ctor"></a><p>
+ Both <code class="computeroutput"><span class="identifier">xml_node</span></code> and <code class="computeroutput"><span class="identifier">xml_attribute</span></code> have the default constructor
+ which initializes them to null objects.
</p>
-<p>
- <a name="xml_attribute::comparison"></a><a name="xml_node::comparison"></a><code class="computeroutput"><span class="identifier">xml_node</span></code> and <code class="computeroutput"><span class="identifier">xml_attribute</span></code>
- try to behave like pointers, that is, they can be compared with other objects
- of the same type, making it possible to use them as keys in associative containers.
- All handles to the same underlying object are equal, and any two handles
- to different underlying objects are not equal. Null handles only compare
- as equal to themselves. The result of relational comparison can not be reliably
- determined from the order of nodes in file or in any other way. Do not use
- relational comparison operators except for search optimization (i.e. associative
- container keys).
+<a name="xml_attribute::comparison"></a><a name="xml_node::comparison"></a><p>
+ <code class="computeroutput"><span class="identifier">xml_node</span></code> and <code class="computeroutput"><span class="identifier">xml_attribute</span></code> try to behave like pointers,
+ that is, they can be compared with other objects of the same type, making
+ it possible to use them as keys in associative containers. All handles to
+ the same underlying object are equal, and any two handles to different underlying
+ objects are not equal. Null handles only compare as equal to themselves.
+ The result of relational comparison can not be reliably determined from the
+ order of nodes in file or in any other way. Do not use relational comparison
+ operators except for search optimization (i.e. associative container keys).
</p>
-<p>
- <a name="xml_attribute::hash_value"></a><a name="xml_node::hash_value"></a>If
- you want to use <code class="computeroutput"><span class="identifier">xml_node</span></code>
+<a name="xml_attribute::hash_value"></a><a name="xml_node::hash_value"></a><p>
+ If you want to use <code class="computeroutput"><span class="identifier">xml_node</span></code>
or <code class="computeroutput"><span class="identifier">xml_attribute</span></code> objects
as keys in hash-based associative containers, you can use the <code class="computeroutput"><span class="identifier">hash_value</span></code> member functions. They return
the hash values that are guaranteed to be the same for all handles to the
same underlying object. The hash value for null handles is 0.
</p>
-<p>
- <a name="xml_attribute::unspecified_bool_type"></a><a name="xml_node::unspecified_bool_type"></a><a name="xml_attribute::empty"></a><a name="xml_node::empty"></a>Finally handles
- can be implicitly cast to boolean-like objects, so that you can test if the
- node/attribute is empty with the following code: <code class="computeroutput"><span class="keyword">if</span>
- <span class="special">(</span><span class="identifier">node</span><span class="special">)</span> <span class="special">{</span> <span class="special">...</span>
+<a name="xml_attribute::unspecified_bool_type"></a><a name="xml_node::unspecified_bool_type"></a><a name="xml_attribute::empty"></a><a name="xml_node::empty"></a><p>
+ Finally handles can be implicitly cast to boolean-like objects, so that you
+ can test if the node/attribute is empty with the following code: <code class="computeroutput"><span class="keyword">if</span> <span class="special">(</span><span class="identifier">node</span><span class="special">)</span> <span class="special">{</span> <span class="special">...</span>
<span class="special">}</span></code> or <code class="computeroutput"><span class="keyword">if</span>
<span class="special">(!</span><span class="identifier">node</span><span class="special">)</span> <span class="special">{</span> <span class="special">...</span>
<span class="special">}</span> <span class="keyword">else</span> <span class="special">{</span> <span class="special">...</span> <span class="special">}</span></code>.
@@ -377,14 +379,14 @@
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.dom.unicode"></a><a class="link" href="dom.html#manual.dom.unicode" title="Unicode interface">Unicode interface</a>
+<a name="manual.dom.unicode"></a><a class="link" href="dom.html#manual.dom.unicode" title="Unicode interface"> Unicode interface</a>
</h3></div></div></div>
<p>
There are two choices of interface and internal representation when configuring
pugixml: you can either choose the UTF-8 (also called char) interface or
UTF-16/32 (also called wchar_t) one. The choice is controlled via <a class="link" href="install.html#PUGIXML_WCHAR_MODE">PUGIXML_WCHAR_MODE</a>
define; you can set it via <code class="filename">pugiconfig.hpp</code> or via preprocessor options, as
- discussed in <a class="xref" href="install.html#manual.install.building.config" title="Additional configuration options">Additional configuration
+ discussed in <a class="xref" href="install.html#manual.install.building.config" title="Additional configuration options"> Additional configuration
options</a>. If this define is set, the wchar_t
interface is used; otherwise (by default) the char interface is used. The
exact wide character encoding is assumed to be either UTF-16 or UTF-32 and
@@ -416,13 +418,13 @@
<pre class="programlisting"><span class="keyword">const</span> <span class="keyword">wchar_t</span><span class="special">*</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">name</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="keyword">bool</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">set_name</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">wchar_t</span><span class="special">*</span> <span class="identifier">value</span><span class="special">);</span>
</pre>
-<p>
- <a name="char_t"></a><a name="string_t"></a>There is a special type, <code class="computeroutput"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">char_t</span></code>, that is defined as the character
- type and depends on the library configuration; it will be also used in the
- documentation hereafter. There is also a type <code class="computeroutput"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">string_t</span></code>,
- which is defined as the STL string of the character type; it corresponds
- to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code> in char mode and to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wstring</span></code>
- in wchar_t mode.
+<a name="char_t"></a><a name="string_t"></a><p>
+ There is a special type, <code class="computeroutput"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">char_t</span></code>,
+ that is defined as the character type and depends on the library configuration;
+ it will be also used in the documentation hereafter. There is also a type
+ <code class="computeroutput"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">string_t</span></code>, which is defined as the STL string
+ of the character type; it corresponds to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code>
+ in char mode and to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wstring</span></code> in wchar_t mode.
</p>
<p>
In addition to the interface, the internal implementation changes to store
@@ -434,10 +436,9 @@
inconvenient to process and most of your XML data is non-ASCII, wchar_t mode
is probably a better choice.
</p>
-<p>
- <a name="as_utf8"></a><a name="as_wide"></a>There are cases when you'll have
- to convert string data between UTF-8 and wchar_t encodings; the following
- helper functions are provided for such purposes:
+<a name="as_utf8"></a><a name="as_wide"></a><p>
+ There are cases when you'll have to convert string data between UTF-8 and
+ wchar_t encodings; the following helper functions are provided for such purposes:
</p>
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">as_utf8</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">wchar_t</span><span class="special">*</span> <span class="identifier">str</span><span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">wstring</span> <span class="identifier">as_wide</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">str</span><span class="special">);</span>
@@ -484,7 +485,7 @@
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.dom.thread"></a><a class="link" href="dom.html#manual.dom.thread" title="Thread-safety guarantees">Thread-safety guarantees</a>
+<a name="manual.dom.thread"></a><a class="link" href="dom.html#manual.dom.thread" title="Thread-safety guarantees"> Thread-safety guarantees</a>
</h3></div></div></div>
<p>
Almost all functions in pugixml have the following thread-safety guarantees:
@@ -510,13 +511,13 @@
<p>
The only exception is <a class="link" href="dom.html#set_memory_management_functions">set_memory_management_functions</a>;
it modifies global variables and as such is not thread-safe. Its usage policy
- has more restrictions, see <a class="xref" href="dom.html#manual.dom.memory.custom" title="Custom memory allocation/deallocation functions">Custom memory allocation/deallocation
+ has more restrictions, see <a class="xref" href="dom.html#manual.dom.memory.custom" title="Custom memory allocation/deallocation functions"> Custom memory allocation/deallocation
functions</a>.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.dom.exception"></a><a class="link" href="dom.html#manual.dom.exception" title="Exception guarantees">Exception guarantees</a>
+<a name="manual.dom.exception"></a><a class="link" href="dom.html#manual.dom.exception" title="Exception guarantees"> Exception guarantees</a>
</h3></div></div></div>
<p>
With the exception of XPath, pugixml itself does not throw any exceptions.
@@ -540,7 +541,7 @@
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
-<a name="manual.dom.memory"></a><a class="link" href="dom.html#manual.dom.memory" title="Memory management">Memory management</a>
+<a name="manual.dom.memory"></a><a class="link" href="dom.html#manual.dom.memory" title="Memory management"> Memory management</a>
</h3></div></div></div>
<p>
pugixml requests the memory needed for document storage in big chunks, and
@@ -549,22 +550,21 @@
</p>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
-<a name="manual.dom.memory.custom"></a><a class="link" href="dom.html#manual.dom.memory.custom" title="Custom memory allocation/deallocation functions">Custom memory allocation/deallocation
+<a name="manual.dom.memory.custom"></a><a class="link" href="dom.html#manual.dom.memory.custom" title="Custom memory allocation/deallocation functions"> Custom memory allocation/deallocation
functions</a>
</h4></div></div></div>
-<p>
- <a name="allocation_function"></a><a name="deallocation_function"></a>All
- memory for tree structure, tree data and XPath objects is allocated via
- globally specified functions, which default to malloc/free. You can set
- your own allocation functions with set_memory_management function. The
- function interfaces are the same as that of malloc/free:
+<a name="allocation_function"></a><a name="deallocation_function"></a><p>
+ All memory for tree structure, tree data and XPath objects is allocated
+ via globally specified functions, which default to malloc/free. You can
+ set your own allocation functions with set_memory_management function.
+ The function interfaces are the same as that of malloc/free:
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="keyword">void</span><span class="special">*</span> <span class="special">(*</span><span class="identifier">allocation_function</span><span class="special">)(</span><span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">);</span>
<span class="keyword">typedef</span> <span class="keyword">void</span> <span class="special">(*</span><span class="identifier">deallocation_function</span><span class="special">)(</span><span class="keyword">void</span><span class="special">*</span> <span class="identifier">ptr</span><span class="special">);</span>
</pre>
-<p>
- <a name="set_memory_management_functions"></a><a name="get_memory_allocation_function"></a><a name="get_memory_deallocation_function"></a>You can use the following accessor
- functions to change or get current memory management functions:
+<a name="set_memory_management_functions"></a><a name="get_memory_allocation_function"></a><a name="get_memory_deallocation_function"></a><p>
+ You can use the following accessor functions to change or get current memory
+ management functions:
</p>
<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">set_memory_management_functions</span><span class="special">(</span><span class="identifier">allocation_function</span> <span class="identifier">allocate</span><span class="special">,</span> <span class="identifier">deallocation_function</span> <span class="identifier">deallocate</span><span class="special">);</span>
<span class="identifier">allocation_function</span> <span class="identifier">get_memory_allocation_function</span><span class="special">();</span>
@@ -589,6 +589,7 @@
This is a simple example of custom memory management (<a href="../samples/custom_memory_management.cpp" target="_top">samples/custom_memory_management.cpp</a>):
</p>
<p>
+
</p>
<pre class="programlisting"><span class="keyword">void</span><span class="special">*</span> <span class="identifier">custom_allocate</span><span class="special">(</span><span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">)</span>
<span class="special">{</span>
@@ -603,6 +604,7 @@
<p>
</p>
<p>
+
</p>
<pre class="programlisting"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">set_memory_management_functions</span><span class="special">(</span><span class="identifier">custom_allocate</span><span class="special">,</span> <span class="identifier">custom_deallocate</span><span class="special">);</span>
</pre>
@@ -617,7 +619,7 @@
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
-<a name="manual.dom.memory.tuning"></a><a class="link" href="dom.html#manual.dom.memory.tuning" title="Memory consumption tuning">Memory consumption tuning</a>
+<a name="manual.dom.memory.tuning"></a><a class="link" href="dom.html#manual.dom.memory.tuning" title="Memory consumption tuning"> Memory consumption tuning</a>
</h4></div></div></div>
<p>
There are several important buffering optimizations in pugixml that rely
@@ -629,7 +631,7 @@
</p>
<p>
These constants can be tuned via configuration defines, as discussed in
- <a class="xref" href="install.html#manual.install.building.config" title="Additional configuration options">Additional configuration
+ <a class="xref" href="install.html#manual.install.building.config" title="Additional configuration options"> Additional configuration
options</a>; it is recommended to set them in <code class="filename">pugiconfig.hpp</code>.
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
@@ -640,6 +642,7 @@
is 32 Kb; for some applications the size is too large (i.e. embedded
systems with little heap space or applications that keep lots of XML
documents in memory). A minimum size of 1 Kb is recommended. <br><br>
+
</li>
<li class="listitem">
<code class="computeroutput"><span class="identifier">PUGIXML_MEMORY_OUTPUT_STACK</span></code>
@@ -649,6 +652,7 @@
using node output from threads with little stack space, decreasing
this value can prevent stack overflows. A minimum size of 1 Kb is recommended.
<br><br>
+
</li>
<li class="listitem">
<code class="computeroutput"><span class="identifier">PUGIXML_MEMORY_XPATH_PAGE_SIZE</span></code>
@@ -663,7 +667,7 @@
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
-<a name="manual.dom.memory.internals"></a><a class="link" href="dom.html#manual.dom.memory.internals" title="Document memory management internals">Document memory management
+<a name="manual.dom.memory.internals"></a><a class="link" href="dom.html#manual.dom.memory.internals" title="Document memory management internals"> Document memory management
internals</a>
</h4></div></div></div>
<p>
@@ -673,7 +677,7 @@
</p>
<p>
When the document is loaded from file/buffer, unless an inplace loading
- function is used (see <a class="xref" href="loading.html#manual.loading.memory" title="Loading document from memory">Loading document from memory</a>), a complete copy of character
+ function is used (see <a class="xref" href="loading.html#manual.loading.memory" title="Loading document from memory"> Loading document from memory</a>), a complete copy of character
stream is made; all names/values of nodes and attributes are allocated
in this buffer. This buffer is allocated via a single large allocation
and is only freed when document memory is reclaimed (i.e. if the <a class="link" href="dom.html#xml_document">xml_document</a> object is destroyed or if another
@@ -711,7 +715,7 @@
<hr>
<table width="100%"><tr>
<td>
-<a href="http://pugixml.org/">pugixml 1.4</a> manual |
+<a href="http://pugixml.org/">pugixml 1.5</a> manual |
<a href="../manual.html">Overview</a> |
<a href="install.html">Installation</a> |
Document: