diff options
Diffstat (limited to 'docs/manual/access.html')
| -rw-r--r-- | docs/manual/access.html | 102 |
1 files changed, 52 insertions, 50 deletions
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: |