From 186e491d1e7f7bddc04d5169084b224a648aa457 Mon Sep 17 00:00:00 2001
From: "arseny.kapoulkine"
<arseny.kapoulkine@99668b35-9821-0410-8761-19e4c4f06640>
Date: Sun, 31 Oct 2010 07:45:27 +0000
Subject: docs: Regenerated HTML documentation
git-svn-id: http://pugixml.googlecode.com/svn/trunk@790 99668b35-9821-0410-8761-19e4c4f06640
---
docs/manual/access.html | 102 ++++++++++++++++++++++++------------------------
1 file changed, 52 insertions(+), 50 deletions(-)
(limited to 'docs/manual/access.html')
diff --git a/docs/manual/access.html b/docs/manual/access.html
index 4581583..d4b38c2 100644
--- a/docs/manual/access.html
+++ b/docs/manual/access.html
@@ -4,14 +4,15 @@
<title>Accessing document data</title>
<link rel="stylesheet" href="../pugixml.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
-<link rel="home" href="../manual.html" title="pugixml 0.9">
-<link rel="up" href="../manual.html" title="pugixml 0.9">
+<link rel="home" href="../manual.html" title="pugixml 1.0">
+<link rel="up" href="../manual.html" title="pugixml 1.0">
<link rel="prev" href="loading.html" title="Loading document">
<link rel="next" href="modify.html" title="Modifying document data">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table width="100%"><tr>
-<td>pugixml 0.9 manual |
+<td>
+<a href="http://pugixml.org/">pugixml 1.0</a> manual |
<a href="../manual.html">Overview</a> |
<a href="install.html">Installation</a> |
Document:
@@ -79,10 +80,11 @@
</pre>
<p>
<code class="computeroutput"><span class="identifier">parent</span></code> function returns the
- node's parent; all nodes except the document have non-null parent. <code class="computeroutput"><span class="identifier">first_child</span></code> and <code class="computeroutput"><span class="identifier">last_child</span></code>
- return the first and last child of the node, respectively; note that only
- document nodes and element nodes can have non-empty child node list. If node
- has no children, both functions return null nodes. <code class="computeroutput"><span class="identifier">next_sibling</span></code>
+ node's parent; all non-null nodes except the document have non-null parent.
+ <code class="computeroutput"><span class="identifier">first_child</span></code> and <code class="computeroutput"><span class="identifier">last_child</span></code> return the first and last child
+ of the node, respectively; note that only document nodes and element nodes
+ can have non-empty child node list. If node has no children, both functions
+ return null nodes. <code class="computeroutput"><span class="identifier">next_sibling</span></code>
and <code class="computeroutput"><span class="identifier">previous_sibling</span></code> return
the node that's immediately to the right/left of this node in the children
list, respectively - for example, in <code class="computeroutput"><span class="special"><</span><span class="identifier">a</span><span class="special">/><</span><span class="identifier">b</span><span class="special">/><</span><span class="identifier">c</span><span class="special">/></span></code>,
@@ -93,9 +95,9 @@
results in handle pointing to <code class="computeroutput"><span class="special"><</span><span class="identifier">a</span><span class="special">/></span></code>.
If node does not have next/previous sibling (this happens if it is the last/first
node in the list, respectively), the functions return null nodes. <code class="computeroutput"><span class="identifier">first_attribute</span></code>, <code class="computeroutput"><span class="identifier">last_attribute</span></code>,
- <code class="computeroutput"><span class="identifier">next_attribute</span></code> and <code class="computeroutput"><span class="identifier">previous_attribute</span></code> functions behave the
- same way as corresponding child node functions and allow to iterate through
- attribute list in the same way.
+ <code class="computeroutput"><span class="identifier">next_attribute</span></code> and <code class="computeroutput"><span class="identifier">previous_attribute</span></code> functions behave similarly
+ to the corresponding child node functions and allow to iterate through attribute
+ list in the same way.
</p>
<div class="note"><table border="0" summary="Note">
<tr>
@@ -111,7 +113,8 @@
Calling any of the functions above on the null handle results in a null handle
- i.e. <code class="computeroutput"><span class="identifier">node</span><span class="special">.</span><span class="identifier">first_child</span><span class="special">().</span><span class="identifier">next_sibling</span><span class="special">()</span></code>
returns the second child of <code class="computeroutput"><span class="identifier">node</span></code>,
- and null handle if there is no children at all or if there is only one.
+ and null handle if <code class="computeroutput"><span class="identifier">node</span></code> is
+ null, has no children at all or if it has only one child node.
</p>
<p>
With these functions, you can iterate through all child nodes and display
@@ -142,12 +145,13 @@
<a name="xml_node::name"></a><a name="xml_node::value"></a><p>
Apart from structural information (parent, child nodes, attributes), nodes
can have name and value, both of which are strings. Depending on node type,
- name or value may be absent. <code class="computeroutput"><span class="identifier">node_document</span></code>
- nodes do not have name or value, <code class="computeroutput"><span class="identifier">node_element</span></code>
- and <code class="computeroutput"><span class="identifier">node_declaration</span></code> nodes
- always have a name but never have a value, <code class="computeroutput"><span class="identifier">node_pcdata</span></code>,
- <code class="computeroutput"><span class="identifier">node_cdata</span></code> and <code class="computeroutput"><span class="identifier">node_comment</span></code> nodes never have a name but
- always have a value (it may be empty though), <code class="computeroutput"><span class="identifier">node_pi</span></code>
+ 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>,
+ <a class="link" href="dom.html#node_cdata">node_cdata</a>, <a class="link" href="dom.html#node_comment">node_comment</a>
+ and <a class="link" href="dom.html#node_doctype">node_doctype</a> nodes never have a name
+ but always have a value (it may be empty though), <a class="link" href="dom.html#node_pi">node_pi</a>
nodes always have a name and a value (again, value may be empty). In order
to get node's name or value, you can use the following functions:
</p>
@@ -161,18 +165,18 @@
<a name="xml_node::child_value"></a><p>
It is common to store data as text contents of some node - i.e. <code class="computeroutput"><span class="special"><</span><span class="identifier">node</span><span class="special">><</span><span class="identifier">description</span><span class="special">></span><span class="identifier">This</span> <span class="identifier">is</span> <span class="identifier">a</span> <span class="identifier">node</span><span class="special"></</span><span class="identifier">description</span><span class="special">></</span><span class="identifier">node</span><span class="special">></span></code>.
In this case, <code class="computeroutput"><span class="special"><</span><span class="identifier">description</span><span class="special">></span></code> node does not have a value, but instead
- has a child of type <code class="computeroutput"><span class="identifier">node_pcdata</span></code>
- with value <code class="computeroutput"><span class="string">"This is a node"</span></code>.
- pugixml provides two helper functions to parse such data:
+ has a child of type <a class="link" href="dom.html#node_pcdata">node_pcdata</a> with value
+ <code class="computeroutput"><span class="string">"This is a node"</span></code>. pugixml
+ provides two helper functions to parse such data:
</p>
<pre class="programlisting"><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">child_value</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">child_value</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">name</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
<code class="computeroutput"><span class="identifier">child_value</span><span class="special">()</span></code>
- returns the value of the first child with type <code class="computeroutput"><span class="identifier">node_pcdata</span></code>
- or <code class="computeroutput"><span class="identifier">node_cdata</span></code>; <code class="computeroutput"><span class="identifier">child_value</span><span class="special">(</span><span class="identifier">name</span><span class="special">)</span></code> is
- a simple wrapper for <code class="computeroutput"><span class="identifier">child</span><span class="special">(</span><span class="identifier">name</span><span class="special">).</span><span class="identifier">child_value</span><span class="special">()</span></code>.
+ returns the value of the first child with type <a class="link" href="dom.html#node_pcdata">node_pcdata</a>
+ or <a class="link" href="dom.html#node_cdata">node_cdata</a>; <code class="computeroutput"><span class="identifier">child_value</span><span class="special">(</span><span class="identifier">name</span><span class="special">)</span></code>
+ is a simple wrapper for <code class="computeroutput"><span class="identifier">child</span><span class="special">(</span><span class="identifier">name</span><span class="special">).</span><span class="identifier">child_value</span><span class="special">()</span></code>.
For the above example, calling <code class="computeroutput"><span class="identifier">node</span><span class="special">.</span><span class="identifier">child_value</span><span class="special">(</span><span class="string">"description"</span><span class="special">)</span></code> and <code class="computeroutput"><span class="identifier">description</span><span class="special">.</span><span class="identifier">child_value</span><span class="special">()</span></code> will both produce string <code class="computeroutput"><span class="string">"This is a node"</span></code>. If there is no
child with relevant type, or if the handle is null, <code class="computeroutput"><span class="identifier">child_value</span></code>
functions return empty string.
@@ -194,15 +198,14 @@
<span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">value</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
- In case attribute handle is null, both functions return empty strings - they
- never return null pointers.
+ In case the attribute handle is null, both functions return empty strings
+ - they never return null pointers.
</p>
<a name="xml_attribute::as_int"></a><a name="xml_attribute::as_uint"></a><a name="xml_attribute::as_double"></a><a name="xml_attribute::as_float"></a><a name="xml_attribute::as_bool"></a><p>
In many cases attribute values have types that are not strings - i.e. an
attribute may always contain values that should be treated as integers, despite
the fact that they are represented as strings in XML. pugixml provides several
- accessors that convert attribute value to some other type. The accessors
- are as follows:
+ accessors that convert attribute value to some other type:
</p>
<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">as_int</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">xml_attribute</span><span class="special">::</span><span class="identifier">as_uint</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
@@ -241,7 +244,7 @@
value to boolean as follows: if attribute handle is null or attribute value
is empty, <code class="computeroutput"><span class="keyword">false</span></code> is returned.
Otherwise, <code class="computeroutput"><span class="keyword">true</span></code> is returned
- if first character is one of <code class="computeroutput"><span class="char">'1'</span><span class="special">,</span> <span class="char">'t'</span><span class="special">,</span>
+ if the first character is one of <code class="computeroutput"><span class="char">'1'</span><span class="special">,</span> <span class="char">'t'</span><span class="special">,</span>
<span class="char">'T'</span><span class="special">,</span> <span class="char">'y'</span><span class="special">,</span> <span class="char">'Y'</span></code>.
This means that strings like <code class="computeroutput"><span class="string">"true"</span></code>
and <code class="computeroutput"><span class="string">"yes"</span></code> are recognized
@@ -370,11 +373,11 @@
return past-the-end iterator for node/attribute list, respectively - this
iterator can't be dereferenced, but decrementing it results in an iterator
pointing to the last element in the list (except for empty lists, where decrementing
- past-the-end iterator is not defined). Past-the-end iterator is commonly
- used as a termination value for iteration loops (see sample below). If you
- want to get an iterator that points to an existing handle, you can construct
- the iterator with the handle as a single constructor argument, like so:
- <code class="computeroutput"><span class="identifier">xml_node_iterator</span><span class="special">(</span><span class="identifier">node</span><span class="special">)</span></code>.
+ past-the-end iterator results in undefined behavior). Past-the-end iterator
+ is commonly used as a termination value for iteration loops (see sample below).
+ If you want to get an iterator that points to an existing handle, you can
+ construct the iterator with the handle as a single constructor argument,
+ like so: <code class="computeroutput"><span class="identifier">xml_node_iterator</span><span class="special">(</span><span class="identifier">node</span><span class="special">)</span></code>.
For <code class="computeroutput"><span class="identifier">xml_attribute_iterator</span></code>,
you'll have to provide both an attribute and its parent node.
</p>
@@ -527,7 +530,7 @@
<a name="xml_node::find_attribute"></a><a name="xml_node::find_child"></a><a name="xml_node::find_node"></a><p>
While there are existing functions for getting a node/attribute with known
contents, they are often not sufficient for simple queries. As an alternative
- to iterating manually through nodes/attributes until the needed one is found,
+ for manual iteration through nodes/attributes until the needed one is found,
you can make a predicate and call one of <code class="computeroutput"><span class="identifier">find_</span></code>
functions:
</p>
@@ -546,24 +549,24 @@
<p>
<code class="computeroutput"><span class="identifier">find_attribute</span></code> function iterates
through all attributes of the specified node, and returns the first attribute
- for which predicate returned <code class="computeroutput"><span class="keyword">true</span></code>.
- If predicate returned <code class="computeroutput"><span class="keyword">false</span></code>
+ for which the predicate returned <code class="computeroutput"><span class="keyword">true</span></code>.
+ If the predicate returned <code class="computeroutput"><span class="keyword">false</span></code>
for all attributes or if there were no attributes (including the case where
the node is null), null attribute is returned.
</p>
<p>
<code class="computeroutput"><span class="identifier">find_child</span></code> function iterates
through all child nodes of the specified node, and returns the first node
- for which predicate returned <code class="computeroutput"><span class="keyword">true</span></code>.
- If predicate returned <code class="computeroutput"><span class="keyword">false</span></code>
+ for which the predicate returned <code class="computeroutput"><span class="keyword">true</span></code>.
+ If the predicate returned <code class="computeroutput"><span class="keyword">false</span></code>
for all nodes or if there were no child nodes (including the case where the
node is null), null node is returned.
</p>
<p>
<code class="computeroutput"><span class="identifier">find_node</span></code> function performs
a depth-first traversal through the subtree of the specified node (excluding
- the node itself), and returns the first node for which predicate returned
- <code class="computeroutput"><span class="keyword">true</span></code>. If predicate returned
+ the node itself), and returns the first node for which the predicate returned
+ <code class="computeroutput"><span class="keyword">true</span></code>. If the predicate returned
<code class="computeroutput"><span class="keyword">false</span></code> for all nodes or if subtree
was empty, null node is returned.
</p>
@@ -622,11 +625,9 @@
<pre class="programlisting"><span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">root</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
- This function returns the node with type <code class="computeroutput"><span class="identifier">node_document</span></code>,
+ This function returns the node with type <a class="link" href="dom.html#node_document">node_document</a>,
which is the root node of the document the node belongs to (unless the node
- is null, in which case null node is returned). Currently this function has
- logarithmic complexity, since it simply finds such ancestor of the given
- node which itself has no parent.
+ is null, in which case null node is returned).
</p>
<a name="xml_node::path"></a><a name="xml_node::first_element_by_path"></a><p>
While pugixml supports complex XPath expressions, sometimes a simple path
@@ -643,9 +644,9 @@
<code class="computeroutput"><span class="identifier">path</span></code> returns the path to
the node from the document root, <code class="computeroutput"><span class="identifier">first_element_by_path</span></code>
looks for a node represented by a given path; a path can be an absolute one
- (absolute paths start with delimiter), in which case the rest of the path
- is treated as document root relative, and relative to the given node. For
- example, in the following document: <code class="computeroutput"><span class="special"><</span><span class="identifier">a</span><span class="special">><</span><span class="identifier">b</span><span class="special">><</span><span class="identifier">c</span><span class="special">/></</span><span class="identifier">b</span><span class="special">></</span><span class="identifier">a</span><span class="special">></span></code>,
+ (absolute paths start with the delimiter), in which case the rest of the
+ path is treated as document root relative, and relative to the given node.
+ For example, in the following document: <code class="computeroutput"><span class="special"><</span><span class="identifier">a</span><span class="special">><</span><span class="identifier">b</span><span class="special">><</span><span class="identifier">c</span><span class="special">/></</span><span class="identifier">b</span><span class="special">></</span><span class="identifier">a</span><span class="special">></span></code>,
node <code class="computeroutput"><span class="special"><</span><span class="identifier">c</span><span class="special">/></span></code> has path <code class="computeroutput"><span class="string">"a/b/c"</span></code>;
calling <code class="computeroutput"><span class="identifier">first_element_by_path</span></code>
for document with path <code class="computeroutput"><span class="string">"a/b"</span></code>
@@ -672,7 +673,7 @@
</tr>
<tr><td align="left" valign="top"><p>
<code class="computeroutput"><span class="identifier">path</span></code> function returns the
- result as STL string, and thus is not available if <code class="computeroutput"><span class="identifier">PUGIXML_NO_STL</span></code>
+ result as STL string, and thus is not available if <a class="link" href="install.html#PUGIXML_NO_STL">PUGIXML_NO_STL</a>
is defined.
</p></td></tr>
</table></div>
@@ -689,7 +690,7 @@
If the offset is not available (this happens if the node is null, was not
originally parsed from a stream, or has changed in a significant way), the
function returns -1. Otherwise it returns the offset to node's data from
- the beginning of XML buffer in <code class="computeroutput"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">char_t</span></code>
+ the beginning of XML buffer in <a class="link" href="dom.html#char_t">pugi::char_t</a>
units. For more information on parsing offsets, see <a class="link" href="loading.html#xml_parse_result::offset">parsing
error handling documentation</a>.
</p>
@@ -704,7 +705,8 @@
</tr></table>
<hr>
<table width="100%"><tr>
-<td>pugixml 0.9 manual |
+<td>
+<a href="http://pugixml.org/">pugixml 1.0</a> manual |
<a href="../manual.html">Overview</a> |
<a href="install.html">Installation</a> |
Document:
--
cgit v1.2.3