diff options
| -rw-r--r-- | docs/manual.html | 64 | ||||
| -rw-r--r-- | docs/manual/access.html | 102 | ||||
| -rw-r--r-- | docs/manual/apiref.html | 285 | ||||
| -rw-r--r-- | docs/manual/changes.html | 228 | ||||
| -rw-r--r-- | docs/manual/dom.html | 277 | ||||
| -rw-r--r-- | docs/manual/install.html | 128 | ||||
| -rw-r--r-- | docs/manual/loading.html | 183 | ||||
| -rw-r--r-- | docs/manual/modify.html | 128 | ||||
| -rw-r--r-- | docs/manual/saving.html | 111 | ||||
| -rw-r--r-- | docs/manual/toc.html | 10 | ||||
| -rw-r--r-- | docs/manual/xpath.html | 368 | ||||
| -rw-r--r-- | docs/quickstart.html | 140 |
12 files changed, 1400 insertions, 624 deletions
diff --git a/docs/manual.html b/docs/manual.html index d895a66..579afba 100644 --- a/docs/manual.html +++ b/docs/manual.html @@ -1,15 +1,16 @@ <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> -<title>pugixml 0.9</title> +<title>pugixml 1.0</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="home" href="manual.html" title="pugixml 1.0"> <link rel="next" href="manual/install.html" title="Installation"> </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 | <b>Overview</b> | <a href="manual/install.html">Installation</a> | Document: @@ -36,22 +37,24 @@ <a name="manual.overview.introduction"></a><a class="link" href="manual.html#manual.overview.introduction" title="Introduction"> Introduction</a> </h3></div></div></div> <p> - pugixml is a light-weight C++ XML processing library. It consists of a DOM-like - interface with rich traversal/modification capabilities, an extremely fast - XML parser which constructs the DOM tree from an XML file/buffer, and an - XPath 1.0 implementation for complex data-driven tree queries. Full Unicode - support is also available, with <a class="link" href="manual/dom.html#manual.dom.unicode" title="Unicode interface">two Unicode - interface variants</a> and conversions between different Unicode encodings - (which happen automatically during parsing/saving). The library is <a class="link" href="manual/install.html#manual.install.portability" title="Portability">extremely portable</a> and easy to - integrate and use. pugixml is developed and maintained since 2006 and has - many users. All code is distributed under the MIT license, making it completely - free to use in both open-source and proprietary applications. + <a href="http://pugixml.org/" target="_top">pugixml</a> is a light-weight C++ XML + processing library. It consists of a DOM-like interface with rich traversal/modification + capabilities, an extremely fast XML parser which constructs the DOM tree + from an XML file/buffer, and an <a class="link" href="manual/xpath.html" title="XPath">XPath 1.0 implementation</a> + for complex data-driven tree queries. Full Unicode support is also available, + with <a class="link" href="manual/dom.html#manual.dom.unicode" title="Unicode interface">two Unicode interface variants</a> + and conversions between different Unicode encodings (which happen automatically + during parsing/saving). The library is <a class="link" href="manual/install.html#manual.install.portability" title="Portability">extremely + portable</a> and easy to integrate and use. pugixml is developed and maintained + since 2006 and has many users. All code is distributed under the <a class="link" href="manual.html#manual.overview.license" title="License">MIT + license</a>, making it completely free to use in both open-source and + proprietary applications. </p> <p> pugixml enables very fast, convenient and memory-efficient XML document processing. However, since pugixml has a DOM parser, it can't process XML documents that do not fit in memory; also the parser is a non-validating one, so if you - need DTD/Schema validation, the library is not for you. + need DTD or XML Schema validation, the library is not for you. </p> <p> This is the complete manual for pugixml, which describes all features of @@ -90,19 +93,19 @@ <p> Feature requests can be reported the same way as bugs, so if you're missing some functionality in pugixml or if the API is rough in some places and you - can suggest an improvement, file an issue. However please note that there - are many factors when considering API changes (compatibility with previous - versions, API redundancy, etc.), so generally features that can be implemented - via a small function without pugixml modification are not accepted. However, - all rules have exceptions. + can suggest an improvement, <a href="http://code.google.com/p/pugixml/issues/entry?template=Feature%20request" target="_top">file + an issue</a>. However please note that there are many factors when considering + API changes (compatibility with previous versions, API redundancy, etc.), + so generally features that can be implemented via a small function without + pugixml modification are not accepted. However, all rules have exceptions. </p> <p> If you have a contribution to pugixml, such as build script for some build system/IDE, or a well-designed set of helper functions, or a binding to some - language other than C++, please file an issue. You can include the relevant - patches as issue attachments. Your contribution has to be distributed under - the terms of a license that's compatible with pugixml license; i.e. GPL/LGPL - licensed code is not accepted. + language other than C++, please <a href="http://code.google.com/p/pugixml/issues/entry?template=Feature%20request" target="_top">file + an issue</a>. You can include the relevant patches as issue attachments. + Your contribution has to be distributed under the terms of a license that's + compatible with pugixml license; i.e. GPL/LGPL licensed code is not accepted. </p> <a name="email"></a><p> If filing an issue is not possible due to privacy or other concerns, you @@ -168,15 +171,26 @@ IN THE SOFTWARE. </p> </blockquote></div> +<p> + This means that you can freely use pugixml in your applications, both open-source + and proprietary. If you use pugixml in a product, it is sufficient to add + an acknowledgment like this to the product distribution: + </p> +<div class="blockquote"><blockquote class="blockquote"><p> + This software is based on pugixml library (http://pugixml.org).<br> +pugixml + is Copyright (C) 2006-2010 Arseny Kapoulkine. + </p></blockquote></div> </div> </div></div> <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> -<td align="left"><p><small>Last revised: July 15, 2010 at 17:02:03 GMT</small></p></td> +<td align="left"><p><small>Last revised: October 31, 2010 at 07:44:52 GMT</small></p></td> <td align="right"><div class="copyright-footer"></div></td> </tr></table> <hr> <table width="100%"><tr> -<td>pugixml 0.9 manual | +<td> +<a href="http://pugixml.org/">pugixml 1.0</a> manual | <b>Overview</b> | <a href="manual/install.html">Installation</a> | Document: 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: diff --git a/docs/manual/apiref.html b/docs/manual/apiref.html index 24120ad..5737c51 100644 --- a/docs/manual/apiref.html +++ b/docs/manual/apiref.html @@ -4,14 +4,15 @@ <title>API Reference</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="changes.html" title="Changelog"> <link rel="next" href="toc.html" title="Table of Contents"> </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: @@ -110,7 +111,10 @@ <a class="link" href="dom.html#node_pi">node_pi</a> </li> <li class="listitem"> - <a class="link" href="dom.html#node_declaration">node_declaration</a> <br><br> + <a class="link" href="dom.html#node_declaration">node_declaration</a> + </li> +<li class="listitem"> + <a class="link" href="dom.html#node_doctype">node_doctype</a> <br><br> </li> </ul></div> @@ -262,12 +266,18 @@ <a class="link" href="loading.html#parse_default">parse_default</a> </li> <li class="listitem"> + <a class="link" href="loading.html#parse_doctype">parse_doctype</a> + </li> +<li class="listitem"> <a class="link" href="loading.html#parse_eol">parse_eol</a> </li> <li class="listitem"> <a class="link" href="loading.html#parse_escapes">parse_escapes</a> </li> <li class="listitem"> + <a class="link" href="loading.html#parse_full">parse_full</a> + </li> +<li class="listitem"> <a class="link" href="loading.html#parse_minimal">parse_minimal</a> </li> <li class="listitem"> @@ -336,6 +346,10 @@ </li> <li class="listitem"> + <code class="computeroutput"><span class="identifier">size_t</span> </code><a class="link" href="dom.html#xml_attribute::hash_value">hash_value</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code> <br><br> + + </li> +<li class="listitem"> <code class="computeroutput"><span class="identifier">xml_attribute</span> </code><a class="link" href="access.html#xml_attribute::next_attribute">next_attribute</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code> </li> <li class="listitem"> @@ -465,6 +479,10 @@ </li> <li class="listitem"> + <code class="computeroutput"><span class="identifier">size_t</span> </code><a class="link" href="dom.html#xml_node::hash_value">hash_value</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code> <br><br> + + </li> +<li class="listitem"> <code class="computeroutput"><span class="identifier">xml_node_type</span> </code><a class="link" href="dom.html#xml_node::type">type</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code> <br><br> @@ -622,6 +640,10 @@ <span class="identifier">name</span><span class="special">);</span></code> </li> <li class="listitem"> + <code class="computeroutput"><span class="identifier">xml_attribute</span> </code><a class="link" href="modify.html#xml_node::prepend_attribute">prepend_attribute</a><code class="computeroutput"><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></code> + </li> +<li class="listitem"> <code class="computeroutput"><span class="identifier">xml_attribute</span> </code><a class="link" href="modify.html#xml_node::insert_attribute_after">insert_attribute_after</a><code class="computeroutput"><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="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">attr</span><span class="special">);</span></code> @@ -638,6 +660,11 @@ <span class="identifier">node_element</span><span class="special">);</span></code> </li> <li class="listitem"> + <code class="computeroutput"><span class="identifier">xml_node</span> </code><a class="link" href="modify.html#xml_node::prepend_child">prepend_child</a><code class="computeroutput"><span class="special">(</span><span class="identifier">xml_node_type</span> + <span class="identifier">type</span> <span class="special">=</span> + <span class="identifier">node_element</span><span class="special">);</span></code> + </li> +<li class="listitem"> <code class="computeroutput"><span class="identifier">xml_node</span> </code><a class="link" href="modify.html#xml_node::insert_child_after">insert_child_after</a><code class="computeroutput"><span class="special">(</span><span class="identifier">xml_node_type</span> <span class="identifier">type</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">node</span><span class="special">);</span></code> @@ -649,9 +676,32 @@ </li> <li class="listitem"> + <code class="computeroutput"><span class="identifier">xml_node</span> </code><a class="link" href="modify.html#xml_node::append_child">append_child</a><code class="computeroutput"><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></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">xml_node</span> </code><a class="link" href="modify.html#xml_node::prepend_child">prepend_child</a><code class="computeroutput"><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></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">xml_node</span> </code><a class="link" href="modify.html#xml_node::insert_child_after">insert_child_after</a><code class="computeroutput"><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="identifier">xml_node</span><span class="special">&</span> <span class="identifier">node</span><span class="special">);</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">xml_node</span> </code><a class="link" href="modify.html#xml_node::insert_child_before">insert_child_before</a><code class="computeroutput"><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="identifier">xml_node</span><span class="special">&</span> <span class="identifier">node</span><span class="special">);</span></code> <br><br> + + </li> +<li class="listitem"> <code class="computeroutput"><span class="identifier">xml_attribute</span> </code><a class="link" href="modify.html#xml_node::append_copy">append_copy</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">proto</span><span class="special">);</span></code> </li> <li class="listitem"> + <code class="computeroutput"><span class="identifier">xml_attribute</span> </code><a class="link" href="modify.html#xml_node::prepend_copy">prepend_copy</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&</span> + <span class="identifier">proto</span><span class="special">);</span></code> + </li> +<li class="listitem"> <code class="computeroutput"><span class="identifier">xml_attribute</span> </code><a class="link" href="modify.html#xml_node::insert_copy_after">insert_copy_after</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">proto</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">attr</span><span class="special">);</span></code> @@ -667,6 +717,10 @@ <span class="identifier">proto</span><span class="special">);</span></code> </li> <li class="listitem"> + <code class="computeroutput"><span class="identifier">xml_node</span> </code><a class="link" href="modify.html#xml_node::prepend_copy">prepend_copy</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> + <span class="identifier">proto</span><span class="special">);</span></code> + </li> +<li class="listitem"> <code class="computeroutput"><span class="identifier">xml_node</span> </code><a class="link" href="modify.html#xml_node::insert_copy_after">insert_copy_after</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">proto</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">node</span><span class="special">);</span></code> @@ -738,7 +792,10 @@ </li> <li class="listitem"> <code class="computeroutput"><span class="identifier">xpath_node</span> </code><a class="link" href="xpath.html#xml_node::select_single_node">select_single_node</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> - <span class="identifier">query</span><span class="special">)</span> + <span class="identifier">query</span><span class="special">,</span> + <span class="identifier">xpath_variable_set</span><span class="special">*</span> + <span class="identifier">variables</span> <span class="special">=</span> + <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span></code> </li> <li class="listitem"> @@ -748,7 +805,10 @@ </li> <li class="listitem"> <code class="computeroutput"><span class="identifier">xpath_node_set</span> </code><a class="link" href="xpath.html#xml_node::select_nodes">select_nodes</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> - <span class="identifier">query</span><span class="special">)</span> + <span class="identifier">query</span><span class="special">,</span> + <span class="identifier">xpath_variable_set</span><span class="special">*</span> + <span class="identifier">variables</span> <span class="special">=</span> + <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span></code> </li> <li class="listitem"> @@ -771,6 +831,15 @@ </li> <li class="listitem"> + <code class="computeroutput"><span class="keyword">void</span> </code><a class="link" href="dom.html#xml_document::reset">reset</a><code class="computeroutput"><span class="special">();</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">void</span> </code><a class="link" href="dom.html#xml_document::reset">reset</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_document</span><span class="special">&</span> + <span class="identifier">proto</span><span class="special">);</span></code> + <br><br> + + </li> +<li class="listitem"> <code class="computeroutput"><span class="identifier">xml_parse_result</span> </code><a class="link" href="loading.html#xml_document::load_stream">load</a><code class="computeroutput"><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">istream</span><span class="special">&</span> <span class="identifier">stream</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="keyword">int</span> @@ -800,7 +869,15 @@ <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></code> - <br><br> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">xml_parse_result</span> </code><a class="link" href="loading.html#xml_document::load_file_wide">load_file</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="keyword">wchar_t</span><span class="special">*</span> + <span class="identifier">path</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></code> <br><br> </li> <li class="listitem"> @@ -839,6 +916,17 @@ <span class="identifier">encoding</span> <span class="special">=</span> <span class="identifier">encoding_auto</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="saving.html#xml_document::save_file_wide">save_file</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="keyword">wchar_t</span><span class="special">*</span> + <span class="identifier">path</span><span class="special">,</span> + <span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">indent</span> + <span class="special">=</span> <span class="string">"\t"</span><span class="special">,</span> <span class="keyword">unsigned</span> + <span class="keyword">int</span> <span class="identifier">flags</span> + <span class="special">=</span> <span class="identifier">format_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> + <span class="keyword">const</span><span class="special">;</span></code> <br><br> </li> @@ -877,6 +965,10 @@ <span class="special">=</span> <span class="identifier">encoding_auto</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span></code> <br><br> </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">xml_node</span> </code><a class="link" href="dom.html#xml_document::document_element">document_element</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code> <br><br> + + </li> </ul></div> </li> <li class="listitem"> @@ -961,31 +1053,57 @@ </ul></div> </li> <li class="listitem"> + <code class="computeroutput"><span class="keyword">struct</span> </code><a class="link" href="xpath.html#xpath_parse_result">xpath_parse_result</a> + <div class="itemizedlist"><ul class="itemizedlist" type="circle"> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> </code><a class="link" href="xpath.html#xpath_parse_result::error">error</a><code class="computeroutput"><span class="special">;</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">ptrdiff_t</span> </code><a class="link" href="xpath.html#xpath_parse_result::offset">offset</a><code class="computeroutput"><span class="special">;</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">operator</span> </code><a class="link" href="xpath.html#xpath_parse_result::bool">bool</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> </code><a class="link" href="xpath.html#xpath_parse_result::description">description</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code> <br><br> + + </li> +</ul></div> + </li> +<li class="listitem"> <code class="computeroutput"><span class="keyword">class</span> </code><a class="link" href="xpath.html#xpath_query">xpath_query</a> <div class="itemizedlist"><ul class="itemizedlist" type="circle"> <li class="listitem"> <code class="computeroutput"><span class="keyword">explicit</span> </code><a class="link" href="xpath.html#xpath_query::ctor">xpath_query</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> - <span class="identifier">query</span><span class="special">);</span></code> + <span class="identifier">query</span><span class="special">,</span> + <span class="identifier">xpath_variable_set</span><span class="special">*</span> + <span class="identifier">variables</span> <span class="special">=</span> + <span class="number">0</span><span class="special">);</span></code> <br><br> </li> <li class="listitem"> - <code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="xpath.html#xpath_query::evaluate_boolean">evaluate_boolean</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> + <code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="xpath.html#xpath_query::evaluate_boolean">evaluate_boolean</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span></code> </li> <li class="listitem"> - <code class="computeroutput"><span class="keyword">double</span> </code><a class="link" href="xpath.html#xpath_query::evaluate_number">evaluate_number</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> + <code class="computeroutput"><span class="keyword">double</span> </code><a class="link" href="xpath.html#xpath_query::evaluate_number">evaluate_number</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span></code> </li> <li class="listitem"> - <code class="computeroutput"><span class="identifier">string_t</span> </code><a class="link" href="xpath.html#xpath_query::evaluate_string">evaluate_string</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> + <code class="computeroutput"><span class="identifier">string_t</span> </code><a class="link" href="xpath.html#xpath_query::evaluate_string">evaluate_string</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span></code> </li> <li class="listitem"> - <code class="computeroutput"><span class="identifier">xpath_node_set</span> </code><a class="link" href="xpath.html#xpath_query::evaluate_node_set">evaluate_node_set</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> + <code class="computeroutput"><span class="identifier">size_t</span> </code><a class="link" href="xpath.html#xpath_query::evaluate_string_buffer">evaluate_string</a><code class="computeroutput"><span class="special">(</span><span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">size_t</span> + <span class="identifier">capacity</span><span class="special">,</span> + <span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">xpath_node_set</span> </code><a class="link" href="xpath.html#xpath_query::evaluate_node_set">evaluate_node_set</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span></code> <br><br> @@ -995,18 +1113,31 @@ <code class="computeroutput"><span class="identifier">xpath_value_type</span> </code><a class="link" href="xpath.html#xpath_query::return_type">return_type</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code> <br><br> </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">const</span> <span class="identifier">xpath_parse_result</span><span class="special">&</span> </code><a class="link" href="xpath.html#xpath_query::result">result</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">operator</span> </code><a class="link" href="xpath.html#xpath_query::unspecified_bool_type">unspecified_bool_type</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code> <br><br> + + </li> </ul></div> </li> <li class="listitem"> <code class="computeroutput"><span class="keyword">class</span> </code><a class="link" href="xpath.html#xpath_exception">xpath_exception</a><code class="computeroutput"><span class="special">:</span> <span class="keyword">public</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span></code> - <div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"> + <div class="itemizedlist"><ul class="itemizedlist" type="circle"> +<li class="listitem"> <code class="computeroutput"><span class="keyword">virtual</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> </code><a class="link" href="xpath.html#xpath_exception::what">what</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span> <span class="keyword">throw</span><span class="special">();</span></code> <br><br> - </li></ul></div> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">const</span> <span class="identifier">xpath_parse_result</span><span class="special">&</span> </code><a class="link" href="xpath.html#xpath_exception::result">result</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code> <br><br> + + </li> +</ul></div> </li> <li class="listitem"> <code class="computeroutput"><span class="keyword">class</span> </code><a class="link" href="xpath.html#xpath_node">xpath_node</a> @@ -1056,6 +1187,18 @@ <code class="computeroutput"><span class="keyword">class</span> </code><a class="link" href="xpath.html#xpath_node_set">xpath_node_set</a> <div class="itemizedlist"><ul class="itemizedlist" type="circle"> <li class="listitem"> + <a class="link" href="xpath.html#xpath_node_set::ctor">xpath_node_set</a><code class="computeroutput"><span class="special">();</span></code> + </li> +<li class="listitem"> + <a class="link" href="xpath.html#xpath_node_set::ctor">xpath_node_set</a><code class="computeroutput"><span class="special">(</span><span class="identifier">const_iterator</span> + <span class="identifier">begin</span><span class="special">,</span> + <span class="identifier">const_iterator</span> <span class="identifier">end</span><span class="special">,</span> <span class="identifier">type_t</span> + <span class="identifier">type</span> <span class="special">=</span> + <span class="identifier">type_unsorted</span><span class="special">);</span></code> + <br><br> + + </li> +<li class="listitem"> <code class="computeroutput"><span class="keyword">typedef</span> <span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">*</span> </code><a class="link" href="xpath.html#xpath_node_set::const_iterator">const_iterator</a><code class="computeroutput"><span class="special">;</span></code> @@ -1100,6 +1243,97 @@ <li class="listitem"> <code class="computeroutput"><span class="keyword">void</span> </code><a class="link" href="xpath.html#xpath_node_set::sort">sort</a><code class="computeroutput"><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">reverse</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">);</span></code> + <br><br> + + </li> +</ul></div> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">class</span> </code><a class="link" href="xpath.html#xpath_variable">xpath_variable</a> + <div class="itemizedlist"><ul class="itemizedlist" type="circle"> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> </code><a class="link" href="xpath.html#xpath_variable::name">name</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">xpath_value_type</span> </code><a class="link" href="xpath.html#xpath_variable::type">type</a><code class="computeroutput"><span class="special">()</span> + <span class="keyword">const</span><span class="special">;</span></code> + <br><br> + + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="xpath.html#xpath_variable::get_boolean">get_boolean</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">double</span> </code><a class="link" href="xpath.html#xpath_variable::get_number">get_number</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> </code><a class="link" href="xpath.html#xpath_variable::get_string">get_string</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">const</span> <span class="identifier">xpath_node_set</span><span class="special">&</span> </code><a class="link" href="xpath.html#xpath_variable::get_node_set">get_node_set</a><code class="computeroutput"><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></code> <br><br> + + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="xpath.html#xpath_variable::set">set</a><code class="computeroutput"><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">value</span><span class="special">);</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="xpath.html#xpath_variable::set">set</a><code class="computeroutput"><span class="special">(</span><span class="keyword">double</span> + <span class="identifier">value</span><span class="special">);</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="xpath.html#xpath_variable::set">set</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> + <span class="identifier">value</span><span class="special">);</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="xpath.html#xpath_variable::set">set</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node_set</span><span class="special">&</span> + <span class="identifier">value</span><span class="special">);</span></code> + <br><br> + + </li> +</ul></div> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">class</span> </code><a class="link" href="xpath.html#xpath_variable_set">xpath_variable_set</a> + <div class="itemizedlist"><ul class="itemizedlist" type="circle"> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">xpath_variable</span><span class="special">*</span> + </code><a class="link" href="xpath.html#xpath_variable_set::add">add</a><code class="computeroutput"><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="identifier">xpath_value_type</span> <span class="identifier">type</span><span class="special">);</span></code> <br><br> + + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="xpath.html#xpath_variable_set::set">set</a><code class="computeroutput"><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">bool</span> <span class="identifier">value</span><span class="special">);</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="xpath.html#xpath_variable_set::set">set</a><code class="computeroutput"><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">double</span> <span class="identifier">value</span><span class="special">);</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="xpath.html#xpath_variable_set::set">set</a><code class="computeroutput"><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="identifier">char_t</span><span class="special">*</span> <span class="identifier">value</span><span class="special">);</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">bool</span> </code><a class="link" href="xpath.html#xpath_variable_set::set">set</a><code class="computeroutput"><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="identifier">xpath_node_set</span><span class="special">&</span> <span class="identifier">value</span><span class="special">);</span></code> <br><br> + + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">xpath_variable</span><span class="special">*</span> + </code><a class="link" href="xpath.html#xpath_variable_set::get">get</a><code class="computeroutput"><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></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="keyword">const</span> <span class="identifier">xpath_variable</span><span class="special">*</span> </code><a class="link" href="xpath.html#xpath_variable_set::get">get</a><code class="computeroutput"><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></code> + <br><br> + </li> </ul></div> </li> @@ -1109,19 +1343,29 @@ </p> <div class="itemizedlist"><ul class="itemizedlist" type="disc"> <li class="listitem"> - <a class="link" href="dom.html#as_utf8">as_utf8</a> + <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> </code><a class="link" href="dom.html#as_utf8">as_utf8</a><code class="computeroutput"><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></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> </code><a class="link" href="dom.html#as_utf8">as_utf8</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">wstring</span><span class="special">&</span> + <span class="identifier">str</span><span class="special">);</span></code> + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wstring</span> </code><a class="link" href="dom.html#as_wide">as_wide</a><code class="computeroutput"><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></code> </li> <li class="listitem"> - <a class="link" href="dom.html#as_wide">as_wide</a> + <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wstring</span> </code><a class="link" href="dom.html#as_wide">as_wide</a><code class="computeroutput"><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&</span> + <span class="identifier">str</span><span class="special">);</span></code> </li> <li class="listitem"> - <a class="link" href="dom.html#get_memory_allocation_function">get_memory_allocation_function</a> + <code class="computeroutput"><span class="keyword">void</span> </code><a class="link" href="dom.html#set_memory_management_functions">set_memory_management_functions</a><code class="computeroutput"><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></code> </li> <li class="listitem"> - <a class="link" href="dom.html#get_memory_deallocation_function">get_memory_deallocation_function</a> + <code class="computeroutput"><span class="identifier">allocation_function</span> </code><a class="link" href="dom.html#get_memory_allocation_function">get_memory_allocation_function</a><code class="computeroutput"><span class="special">();</span></code> </li> <li class="listitem"> - <a class="link" href="dom.html#set_memory_management_functions">set_memory_management_functions</a> + <code class="computeroutput"><span class="identifier">deallocation_function</span> </code><a class="link" href="dom.html#get_memory_deallocation_function">get_memory_deallocation_function</a><code class="computeroutput"><span class="special">();</span></code> </li> </ul></div> </div> @@ -1134,7 +1378,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: diff --git a/docs/manual/changes.html b/docs/manual/changes.html index 38e0cda..78cde23 100644 --- a/docs/manual/changes.html +++ b/docs/manual/changes.html @@ -4,14 +4,15 @@ <title>Changelog</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="xpath.html" title="XPath"> <link rel="next" href="apiref.html" title="API Reference"> </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: @@ -29,6 +30,224 @@ <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="manual.changes"></a><a class="link" href="changes.html" title="Changelog"> Changelog</a> </h2></div></div></div> +<a name="manual.changes.1_11_2010___version_1_0"></a><h6> + <a class="link" href="changes.html#manual.changes.1_11_2010___version_1_0">1.11.2010 - version + 1.0</a> + </h6> +<p> + Major release, featuring many XPath enhancements, wide character filename support, + miscellaneous performance improvements, bug fixes and more. + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + XPath: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + XPath implementation is moved to pugixml.cpp (which is the only source + file now); use PUGIXML_NO_XPATH if you want to disable XPath to reduce + code size + </li> +<li class="listitem"> + XPath is now supported without exceptions (PUGIXML_NO_EXCEPTIONS); + the error handling mechanism depends on the presence of exception + support + </li> +<li class="listitem"> + XPath is now supported without STL (PUGIXML_NO_STL) + </li> +<li class="listitem"> + Introduced variable support + </li> +<li class="listitem"> + Introduced new xpath_query::evaluate_string, which works without + STL + </li> +<li class="listitem"> + Introduced new xpath_node_set constructor (from an iterator range) + </li> +<li class="listitem"> + Evaluation function now accept attribute context nodes + </li> +<li class="listitem"> + All internal allocations use custom allocation functions + </li> +<li class="listitem"> + Improved error reporting; now a last parsed offset is returned together + with the parsing error + </li> +</ol></div> + </li> +<li class="listitem"> + Bug fixes: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + Fixed memory leak for loading from streams with stream exceptions + turned on + </li> +<li class="listitem"> + Fixed custom deallocation function calling with null pointer in one + case + </li> +<li class="listitem"> + Fixed missing attributes for iterator category functions; all functions/classes + can now be DLL-exported + </li> +<li class="listitem"> + Worked around Digital Mars compiler bug, which lead to minor read + overfetches in several functions + </li> +<li class="listitem"> + load_file now works with 2+ Gb files in MSVC/MinGW + </li> +<li class="listitem"> + XPath: fixed memory leaks for incorrect queries + </li> +<li class="listitem"> + XPath: fixed xpath_node() attribute constructor with empty attribute + argument + </li> +<li class="listitem"> + XPath: fixed lang() function for non-ASCII arguments + </li> +</ol></div> + </li> +<li class="listitem"> + Specification changes: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + CDATA nodes containing ]]> are printed as several nodes; while + this changes the internal structure, this is the only way to escape + CDATA contents + </li> +<li class="listitem"> + Memory allocation errors during parsing now preserve last parsed + offset (to give an idea about parsing progress) + </li> +<li class="listitem"> + If an element node has the only child, and it is of CDATA type, then + the extra indentation is omitted (previously this behavior only held + for PCDATA children) + </li> +</ol></div> + </li> +<li class="listitem"> + Additional functionality: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + Added xml_parse_result default constructor + </li> +<li class="listitem"> + Added xml_document::load_file and xml_document::save_file with wide + character paths + </li> +<li class="listitem"> + Added as_utf8 and as_wide overloads for std::wstring/std::string + arguments + </li> +<li class="listitem"> + Added DOCTYPE node type (node_doctype) and a special parse flag, + parse_doctype, to add such nodes to the document during parsing + </li> +<li class="listitem"> + Added parse_full parse flag mask, which extends parse_default with + all node type parsing flags except parse_ws_pcdata + </li> +<li class="listitem"> + Added xml_node::hash_value() and xml_attribute::hash_value() functions + for use in hash-based containers + </li> +<li class="listitem"> + Added internal_object() and additional constructor for both xml_node + and xml_attribute for easier marshalling (useful for language bindings) + </li> +<li class="listitem"> + Added xml_document::document_element() function + </li> +<li class="listitem"> + Added xml_node::prepend_attribute, xml_node::prepend_child and xml_node::prepend_copy + functions + </li> +<li class="listitem"> + Added xml_node::append_child, xml_node::prepend_child, xml_node::insert_child_before + and xml_node::insert_child_after overloads for element nodes (with + name instead of type) + </li> +<li class="listitem"> + Added xml_document::reset() function + </li> +</ol></div> + </li> +<li class="listitem"> + Performance improvements: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + xml_node::root() and xml_node::offset_debug() are now O(1) instead + of O(logN) + </li> +<li class="listitem"> + Minor parsing optimizations + </li> +<li class="listitem"> + Minor memory optimization for strings in DOM tree (set_name/set_value) + </li> +<li class="listitem"> + Memory optimization for string memory reclaiming in DOM tree (set_name/set_value + now reallocate the buffer if memory waste is too big) + </li> +<li class="listitem"> + XPath: optimized document order sorting + </li> +<li class="listitem"> + XPath: optimized child/attribute axis step + </li> +<li class="listitem"> + XPath: optimized number-to-string conversions in MSVC + </li> +<li class="listitem"> + XPath: optimized concat for many arguments + </li> +<li class="listitem"> + XPath: optimized evaluation allocation mechanism: constant and document + strings are not heap-allocated + </li> +<li class="listitem"> + XPath: optimized evaluation allocation mechanism: all temporaries' + allocations use fast stack-like allocator + </li> +</ol></div> + </li> +<li class="listitem"> + Compatibility: + <div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + Removed wildcard functions (xml_node::child_w, xml_node::attribute_w, + etc.) + </li> +<li class="listitem"> + Removed xml_node::all_elements_by_name + </li> +<li class="listitem"> + Removed xpath_type_t enumeration; use xpath_value_type instead + </li> +<li class="listitem"> + Removed format_write_bom_utf8 enumeration; use format_write_bom instead + </li> +<li class="listitem"> + Removed xml_document::precompute_document_order, xml_attribute::document_order + and xml_node::document_order functions; document order sort optimization + is now automatic + </li> +<li class="listitem"> + Removed xml_document::parse functions and transfer_ownership struct; + use xml_document::load_buffer_inplace and xml_document::load_buffer_inplace_own + instead + </li> +<li class="listitem"> + Removed as_utf16 function; use as_wide instead + </li> +</ol></div> + </li> +</ul></div> <a name="manual.changes.1_07_2010___version_0_9"></a><h6> <a class="link" href="changes.html#manual.changes.1_07_2010___version_0_9">1.07.2010 - version 0.9</a> @@ -548,7 +767,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: diff --git a/docs/manual/dom.html b/docs/manual/dom.html index 2d65070..22509a9 100644 --- a/docs/manual/dom.html +++ b/docs/manual/dom.html @@ -4,14 +4,15 @@ <title>Document object model</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="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>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: @@ -46,10 +47,10 @@ <p> pugixml stores XML data in DOM-like way: the entire XML document (both document structure and element data) is stored in memory as a tree. The tree can be - loaded from character stream (file, string, C++ I/O stream), then traversed - via special API or XPath expressions. The whole tree is mutable: both node - structure and node/attribute data can be changed at any time. Finally, the - result of document transformations can be saved to a character stream (file, + loaded from a character stream (file, string, C++ I/O stream), then traversed + with the special API or XPath expressions. The whole tree is mutable: both + node structure and node/attribute data can be changed at any time. Finally, + the result of document transformations can be saved to a character stream (file, C++ I/O stream or custom transport). </p> <div class="section"> @@ -58,12 +59,11 @@ </h3></div></div></div> <p> The XML document is represented with a tree data structure. The root of the - tree is the document itself, which corresponds to C++ type <code class="computeroutput"><span class="identifier">xml_document</span></code>. Document has one or more - child nodes, which correspond to C++ type <code class="computeroutput"><span class="identifier">xml_node</span></code>. - Nodes have different types; depending on a type, a node can have a collection - of child nodes, a collection of attributes, which correspond to C++ type - <code class="computeroutput"><span class="identifier">xml_attribute</span></code>, and some additional - data (i.e. name). + tree is the document itself, which corresponds to C++ type <a class="link" href="dom.html#xml_document">xml_document</a>. + Document has one or more child nodes, which correspond to C++ type <a class="link" href="dom.html#xml_node">xml_node</a>. Nodes have different types; depending + on a type, a node can have a collection of child nodes, a collection of attributes, + which correspond to C++ type <a class="link" href="dom.html#xml_attribute">xml_attribute</a>, + and some additional data (i.e. name). </p> <a name="xml_node_type"></a><p> The tree nodes can be of one of the following types (which together form @@ -73,13 +73,13 @@ <li class="listitem"> Document node (<a name="node_document"></a><code class="literal">node_document</code>) - this is the root of the tree, which consists of several child nodes. This - node corresponds to <code class="computeroutput"><span class="identifier">xml_document</span></code> - class; note that <code class="computeroutput"><span class="identifier">xml_document</span></code> - is a sub-class of <code class="computeroutput"><span class="identifier">xml_node</span></code>, - so the entire node interface is also available. However, document node - is special in several ways, which will be covered below. There can be - only one document node in the tree; document node does not have any XML - representation. <br><br> + node corresponds to <a class="link" href="dom.html#xml_document">xml_document</a> + class; note that <a class="link" href="dom.html#xml_document">xml_document</a> is + a sub-class of <a class="link" href="dom.html#xml_node">xml_node</a>, so the entire + node interface is also available. However, document node is special in + 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"> @@ -87,13 +87,13 @@ is the most common type of node, which represents XML elements. Element nodes have a name, a collection of attributes and a collection of child nodes (both of which may be empty). The attribute is a simple name/value - pair. The example XML representation of element node is as follows: + pair. The example XML representation of element nodes is as follows: </li> </ul></div> <pre class="programlisting"><span class="special"><</span><span class="identifier">node</span> <span class="identifier">attr</span><span class="special">=</span><span class="string">"value"</span><span class="special">><</span><span class="identifier">child</span><span class="special">/></</span><span class="identifier">node</span><span class="special">></span> </pre> <div class="blockquote"><blockquote class="blockquote"><p> - There are two element nodes here; one has name <code class="computeroutput"><span class="string">"node"</span></code>, + There are two element nodes here: one has name <code class="computeroutput"><span class="string">"node"</span></code>, single attribute <code class="computeroutput"><span class="string">"attr"</span></code> and single child <code class="computeroutput"><span class="string">"child"</span></code>, another has name <code class="computeroutput"><span class="string">"child"</span></code> @@ -102,10 +102,10 @@ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> Plain character data nodes (<a name="node_pcdata"></a><code class="literal">node_pcdata</code>) represent plain text in XML. PCDATA nodes have a value, but do not have - name or children/attributes. Note that plain character data is not a - part of the element node but instead has its own node; for example, an - element node can have several child PCDATA nodes. The example XML representation - of text node is as follows: + a name or children/attributes. Note that plain character data is not + a part of the element node but instead has its own node; for example, + an element node can have several child PCDATA nodes. The example XML + representation of text nodes is as follows: </li></ul></div> <pre class="programlisting"><span class="special"><</span><span class="identifier">node</span><span class="special">></span> <span class="identifier">text1</span> <span class="special"><</span><span class="identifier">child</span><span class="special">/></span> <span class="identifier">text2</span> <span class="special"></</span><span class="identifier">node</span><span class="special">></span> </pre> @@ -128,9 +128,9 @@ </p></blockquote></div> <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> Comment nodes (<a name="node_comment"></a><code class="literal">node_comment</code>) represent - comments in XML. Comment nodes have a value, but do not have name or - children/attributes. The example XML representation of comment node is - as follows: + comments in XML. Comment nodes have a value, but do not have a name or + children/attributes. The example XML representation of a comment node + is as follows: </li></ul></div> <pre class="programlisting"><span class="special"><!--</span> <span class="identifier">comment</span> <span class="identifier">text</span> <span class="special">--></span> </pre> @@ -138,14 +138,14 @@ Here the comment node has value <code class="computeroutput"><span class="string">"comment text"</span></code>. By default comment nodes are treated as non-essential part of XML markup and are not loaded during XML parsing. You can override - this behavior by adding <code class="computeroutput"><span class="identifier">parse_comments</span></code> + this behavior with <a class="link" href="loading.html#parse_comments">parse_comments</a> flag. </p></blockquote></div> <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> Processing instruction node (<a name="node_pi"></a><code class="literal">node_pi</code>) represent processing instructions (PI) in XML. PI nodes have a name and an optional value, but do not have children/attributes. The example XML representation - of PI node is as follows: + of a PI node is as follows: </li></ul></div> <pre class="programlisting"><span class="special"><?</span><span class="identifier">name</span> <span class="identifier">value</span><span class="special">?></span> </pre> @@ -153,17 +153,17 @@ Here the name (also called PI target) is <code class="computeroutput"><span class="string">"name"</span></code>, and the value is <code class="computeroutput"><span class="string">"value"</span></code>. By default PI nodes are treated as non-essential part of XML markup and - are not loaded during XML parsing. You can override this behavior by adding - <code class="computeroutput"><span class="identifier">parse_pi</span></code> flag. + are not loaded during XML parsing. You can override this behavior with + <a class="link" href="loading.html#parse_pi">parse_pi</a> flag. </p></blockquote></div> <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> Declaration node (<a name="node_declaration"></a><code class="literal">node_declaration</code>) represents document declarations in XML. Declaration nodes have a name (<code class="computeroutput"><span class="string">"xml"</span></code>) and an - optional collection of attributes, but does not have value or children. + optional collection of attributes, but do not have value or children. There can be only one declaration node in a document; moreover, it should be the topmost node (its parent should be the document). The example - XML representation of declaration node is as follows: + XML representation of a declaration node is as follows: </li></ul></div> <pre class="programlisting"><span class="special"><?</span><span class="identifier">xml</span> <span class="identifier">version</span><span class="special">=</span><span class="string">"1.0"</span><span class="special">?></span> </pre> @@ -172,12 +172,28 @@ and a single attribute with name <code class="computeroutput"><span class="string">"version"</span></code> and value <code class="computeroutput"><span class="string">"1.0"</span></code>. By default declaration nodes are treated as non-essential part of XML markup - and are not loaded during XML parsing. You can override this behavior by - adding <code class="computeroutput"><span class="identifier">parse_declaration</span></code> - flag. Also, by default a dummy declaration is output when XML document - is saved unless there is already a declaration in the document; you can - disable this by adding <code class="computeroutput"><span class="identifier">format_no_declaration</span></code> - flag. + and are not loaded during XML parsing. You can override this behavior with + <a class="link" href="loading.html#parse_declaration">parse_declaration</a> flag. Also, + by default a dummy declaration is output when XML document is saved unless + there is already a declaration in the document; you can disable this with + <a class="link" href="saving.html#format_no_declaration">format_no_declaration</a> flag. + </p></blockquote></div> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + Document type declaration node (<a name="node_doctype"></a><code class="literal">node_doctype</code>) + represents document type declarations in XML. Document type declaration + nodes have a value, which corresponds to the entire document type contents; + no additional nodes are created for inner elements like <code class="computeroutput"><span class="special"><!</span><span class="identifier">ENTITY</span><span class="special">></span></code>. There can be only one document type + declaration node in a document; moreover, it should be the topmost node + (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"><!</span><span class="identifier">DOCTYPE</span> <span class="identifier">greeting</span> <span class="special">[</span> <span class="special"><!</span><span class="identifier">ELEMENT</span> <span class="identifier">greeting</span> <span class="special">(</span><span class="preprocessor">#PCDATA</span><span class="special">)></span> <span class="special">]></span> +</pre> +<div class="blockquote"><blockquote class="blockquote"><p> + Here the node has value <code class="computeroutput"><span class="string">"greeting [ <!ELEMENT + greeting (#PCDATA)> ]"</span></code>. By default document type + declaration nodes are treated as non-essential part of XML markup and are + not loaded during XML parsing. You can override this behavior with <a class="link" href="loading.html#parse_doctype">parse_doctype</a> flag. </p></blockquote></div> <p> Finally, here is a complete example of XML document and the corresponding @@ -227,40 +243,45 @@ <th align="left">Note</th> </tr> <tr><td align="left" valign="top"><p> - All pugixml classes and functions are located in <code class="computeroutput"><span class="identifier">pugi</span></code> + All pugixml classes and functions are located in the <code class="computeroutput"><span class="identifier">pugi</span></code> namespace; you have to either use explicit name qualification (i.e. <code class="computeroutput"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span></code>), or to gain access to relevant symbols via <code class="computeroutput"><span class="keyword">using</span></code> directive (i.e. <code class="computeroutput"><span class="keyword">using</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span><span class="special">;</span></code> or <code class="computeroutput"><span class="keyword">using</span> - <span class="keyword">namespace</span> <span class="identifier">pugi</span><span class="special">;</span></code>). The namespace will be omitted from declarations - in this documentation hereafter; all code examples will use fully-qualified - names. + <span class="keyword">namespace</span> <span class="identifier">pugi</span><span class="special">;</span></code>). The namespace will be omitted from all + declarations in this documentation hereafter; all code examples will use + fully qualified names. </p></td></tr> </table></div> <p> Despite the fact that there are several node types, there are only three - C++ types representing the tree (<code class="computeroutput"><span class="identifier">xml_document</span></code>, + C++ classes representing the tree (<code class="computeroutput"><span class="identifier">xml_document</span></code>, <code class="computeroutput"><span class="identifier">xml_node</span></code>, <code class="computeroutput"><span class="identifier">xml_attribute</span></code>); some operations on <code class="computeroutput"><span class="identifier">xml_node</span></code> - are only valid for certain node types. They are described below. + are only valid for certain node types. The classes are described below. </p> -<a name="xml_document"></a><p> +<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 interface of <code class="computeroutput"><span class="identifier">xml_node</span></code>, + 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 only used to simplify usage. + 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> -<a name="xml_document::ctor"></a><a name="xml_document::dtor"></a><p> +<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 - all occupied memory, which puts existing nodes/attributes from this document - to invalid state. Destructor of <code class="computeroutput"><span class="identifier">xml_document</span></code> + all occupied memory, which puts existing node/attribute handles for this + document to invalid state. If you want to destroy the previous tree, you + can use the <code class="computeroutput"><span class="identifier">xml_document</span><span class="special">::</span><span class="identifier">reset</span></code> + function; it destroys the tree and replaces it with either an empty one or + a copy of the specified document. Destructor of <code class="computeroutput"><span class="identifier">xml_document</span></code> also destroys the tree, thus the lifetime of the document object should exceed the lifetimes of any node/attribute handles that point to the tree. </p> @@ -271,7 +292,7 @@ </tr> <tr><td align="left" valign="top"><p> While technically node/attribute handles can be alive when the tree they're - referring to is destroyed, calling any member function of these handles + referring to is destroyed, calling any member function for these handles results in undefined behavior. Thus it is recommended to make sure that the document is destroyed only after all references to its nodes/attributes are destroyed. @@ -279,16 +300,17 @@ </table></div> <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 document - itself. There is a common interface for nodes of all types; the actual node - type can be queried via <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> + 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> handle does not destroy the node and does not remove it from the tree. The size of <code class="computeroutput"><span class="identifier">xml_node</span></code> is equal to that of a pointer, so it is nothing more than a lightweight wrapper around - pointer; you can safely pass or return <code class="computeroutput"><span class="identifier">xml_node</span></code> + 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> <a name="node_null"></a><p> @@ -300,14 +322,14 @@ for specific functions for more detailed information). This is useful for chaining calls; i.e. you can get the grandparent of a node like so: <code class="computeroutput"><span class="identifier">node</span><span class="special">.</span><span class="identifier">parent</span><span class="special">().</span><span class="identifier">parent</span><span class="special">()</span></code>; if a node is a null node or it does not have a parent, the first <code class="computeroutput"><span class="identifier">parent</span><span class="special">()</span></code> call returns null node; the second <code class="computeroutput"><span class="identifier">parent</span><span class="special">()</span></code> - call then also returns null node, so you don't have to check for errors twice. + call then also returns null node, which makes error handling easier. </p> <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, there is a special null attribute - value, which propagates to function results. + handles pointing to the same underlying object and there is a special null + attribute value, which propagates to function results. </p> <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 @@ -316,16 +338,23 @@ <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 of associative containers. All handles to + 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 other ways. Do not use relational comparison operators - except for search optimization (i.e. associative container keys). + 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> +<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> <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> - Additionally handles they can be implicitly cast to boolean-like objects, - so that you can test if the node/attribute is empty by just doing <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> + 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>. @@ -336,13 +365,14 @@ <span class="keyword">bool</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">empty</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> </pre> <p> - Nodes and attributes do not exist outside of document tree, so you can't - create them without adding them to some document. Once underlying node/attribute + Nodes and attributes do not exist without a document tree, so you can't create + them without adding them to some document. Once underlying node/attribute objects are destroyed, the handles to those objects become invalid. While this means that destruction of the entire tree invalidates all node/attribute - handles, it also means that destroying a subtree (by calling <code class="computeroutput"><span class="identifier">remove_child</span></code>) or removing an attribute - invalidates the corresponding handles. There is no way to check handle validity; - you have to ensure correctness through external mechanisms. + handles, it also means that destroying a subtree (by calling <a class="link" href="modify.html#xml_node::remove_child">xml_node::remove_child</a>) + or removing an attribute invalidates the corresponding handles. There is + no way to check handle validity; you have to ensure correctness through external + mechanisms. </p> </div> <div class="section"> @@ -352,12 +382,14 @@ <p> There are two choices of interface and internal representation when configuring pugixml: you can either choose the UTF-8 (also called char) interface or - UTF-16/32 (also called wchar_t) one. The choice is controlled via <code class="computeroutput"><span class="identifier">PUGIXML_WCHAR_MODE</span></code> define; you can set - it via <code class="filename">pugiconfig.hpp</code> or via preprocessor options, as 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 is determined based on size of <code class="computeroutput"><span class="keyword">wchar_t</span></code> type. + 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 + 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 + is determined based on the size of <code class="computeroutput"><span class="keyword">wchar_t</span></code> + type. </p> <div class="note"><table border="0" summary="Note"> <tr> @@ -365,9 +397,9 @@ <th align="left">Note</th> </tr> <tr><td align="left" valign="top"><p> - If size of <code class="computeroutput"><span class="keyword">wchar_t</span></code> is 2, pugixml - assumes UTF-16 encoding instead of UCS-2, which means that some characters - are represented as two code points. + If the size of <code class="computeroutput"><span class="keyword">wchar_t</span></code> is + 2, pugixml assumes UTF-16 encoding instead of UCS-2, which means that some + characters are represented as two code points. </p></td></tr> </table></div> <p> @@ -399,7 +431,7 @@ <code class="computeroutput"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">char_t</span></code> upon document saving happen automatically, which also carries minor performance penalty. The general advice however is to select the character mode based on usage scenario, i.e. if UTF-8 is - inconvenient to process and most of your XML data is localized, wchar_t mode + inconvenient to process and most of your XML data is non-ASCII, wchar_t mode is probably a better choice. </p> <a name="as_utf8"></a><a name="as_wide"></a><p> @@ -410,13 +442,18 @@ <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> </pre> <p> - Both functions accept null-terminated string as an argument <code class="computeroutput"><span class="identifier">str</span></code>, and return the converted string. + Both functions accept a null-terminated string as an argument <code class="computeroutput"><span class="identifier">str</span></code>, and return the converted string. <code class="computeroutput"><span class="identifier">as_utf8</span></code> performs conversion from UTF-16/32 to UTF-8; <code class="computeroutput"><span class="identifier">as_wide</span></code> performs conversion from UTF-8 to UTF-16/32. Invalid UTF sequences are silently discarded upon conversion. <code class="computeroutput"><span class="identifier">str</span></code> has to be a valid string; passing null pointer results in undefined behavior. + There are also two overloads with the same semantics which accept a string + as an argument: </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="identifier">std</span><span class="special">::</span><span class="identifier">wstring</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="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&</span> <span class="identifier">str</span><span class="special">);</span> +</pre> <div class="note"><table border="0" summary="Note"> <tr> <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td> @@ -425,8 +462,8 @@ <tr><td align="left" valign="top"> <p> Most examples in this documentation assume char interface and therefore - will not compile with <code class="computeroutput"><span class="identifier">PUGIXML_WCHAR_MODE</span></code>. - This is to simplify the documentation; usually the only changes you'll + will not compile with <a class="link" href="install.html#PUGIXML_WCHAR_MODE">PUGIXML_WCHAR_MODE</a>. + This is done to simplify the documentation; usually the only changes you'll have to make is to pass <code class="computeroutput"><span class="keyword">wchar_t</span></code> string literals, i.e. instead of </p> @@ -453,7 +490,7 @@ </p> <div class="itemizedlist"><ul class="itemizedlist" type="disc"> <li class="listitem"> - it is safe to call free functions from multiple threads + it is safe to call free (non-member) functions from multiple threads </li> <li class="listitem"> it is safe to perform concurrent read-only accesses to the same tree @@ -470,7 +507,7 @@ structure and altering individual node/attribute data, i.e. changing names/values. </p> <p> - The only exception is <code class="computeroutput"><span class="identifier">set_memory_management_functions</span></code>; + 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 functions</a>. @@ -488,15 +525,16 @@ This is not applicable to functions that operate on STL strings or IOstreams; such functions have either strong guarantee (functions that operate on strings) or basic guarantee (functions that operate on streams). Also functions that - call user-defined callbacks (i.e. <code class="computeroutput"><span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">traverse</span></code> - or <code class="computeroutput"><span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">find_node</span></code>) do not provide any exception - guarantees beyond the ones provided by callback. + call user-defined callbacks (i.e. <a class="link" href="access.html#xml_node::traverse">xml_node::traverse</a> + or <a class="link" href="access.html#xml_node::find_node">xml_node::find_node</a>) do not + provide any exception guarantees beyond the ones provided by the callback. </p> <p> - XPath functions may throw <code class="computeroutput"><span class="identifier">xpath_exception</span></code> - on parsing error; also, XPath implementation uses STL, and thus may throw - i.e. <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bad_alloc</span></code> in low memory conditions. Still, - XPath functions provide strong exception guarantee. + If exception handling is not disabled with <a class="link" href="install.html#PUGIXML_NO_EXCEPTIONS">PUGIXML_NO_EXCEPTIONS</a> + define, XPath functions may throw <a class="link" href="xpath.html#xpath_exception">xpath_exception</a> + on parsing errors; also, XPath functions may throw <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bad_alloc</span></code> + in low memory conditions. Still, XPath functions provide strong exception + guarantee. </p> </div> <div class="section"> @@ -514,10 +552,10 @@ functions</a> </h4></div></div></div> <a name="allocation_function"></a><a name="deallocation_function"></a><p> - All memory for tree structure/data is allocated via globally specified - functions, which default to malloc/free. You can set your own allocation - functions with set_memory_management functions. The function interfaces - are the same as that of malloc/free: + 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> @@ -532,14 +570,18 @@ </pre> <p> Allocation function is called with the size (in bytes) as an argument and - should return a pointer to memory block with alignment that is suitable - for pointer storage and size that is greater or equal to the requested - one. If the allocation fails, the function has to return null pointer (throwing - an exception from allocation function results in undefined behavior). Deallocation - function is called with the pointer that was returned by the previous call - or with a null pointer; null pointer deallocation should be handled as - a no-op. If memory management functions are not thread-safe, library thread - safety is not guaranteed. + should return a pointer to a memory block with alignment that is suitable + for storage of primitive types (usually a maximum of <code class="computeroutput"><span class="keyword">void</span><span class="special">*</span></code> and <code class="computeroutput"><span class="keyword">double</span></code> + types alignment is sufficient) and size that is greater than or equal to + the requested one. If the allocation fails, the function has to return + null pointer (throwing an exception from allocation function results in + undefined behavior). + </p> +<p> + Deallocation function is called with the pointer that was returned by some + call to allocation function; it is never called with a null pointer. If + memory management functions are not thread-safe, library thread safety + is not guaranteed. </p> <p> This is a simple example of custom memory management (<a href="../samples/custom_memory_management.cpp" target="_top">samples/custom_memory_management.cpp</a>): @@ -572,16 +614,6 @@ are destroyed, the new deallocation function will be called with the memory obtained by the old allocation function, resulting in undefined behavior. </p> -<div class="note"><table border="0" summary="Note"> -<tr> -<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td> -<th align="left">Note</th> -</tr> -<tr><td align="left" valign="top"><p> - Currently memory for XPath objects is allocated using default operators - new/delete; this will change in the next version. - </p></td></tr> -</table></div> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> @@ -590,7 +622,7 @@ </h4></div></div></div> <p> Constructing a document object using the default constructor does not result - in any allocations; document node is stored inside the <code class="computeroutput"><span class="identifier">xml_document</span></code> + in any allocations; document node is stored inside the <a class="link" href="dom.html#xml_document">xml_document</a> object. </p> <p> @@ -598,11 +630,11 @@ 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 <code class="computeroutput"><span class="identifier">xml_document</span></code> object is destroyed or if - another document is loaded in the same object). Also when loading from - file or stream, an additional large allocation may be performed if encoding - conversion is required; a temporary buffer is allocated, and it is freed - before load function returns. + 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 + document is loaded in the same object). Also when loading from file or + stream, an additional large allocation may be performed if encoding conversion + is required; a temporary buffer is allocated, and it is freed before load + function returns. </p> <p> All additional memory, such as memory for document structure (node/attribute @@ -632,7 +664,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: diff --git a/docs/manual/install.html b/docs/manual/install.html index d6d0327..9809a39 100644 --- a/docs/manual/install.html +++ b/docs/manual/install.html @@ -4,14 +4,15 @@ <title>Installation</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="prev" 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="../manual.html" title="pugixml 1.0"> <link rel="next" href="dom.html" title="Document object model"> </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> | <b>Installation</b> | Document: @@ -64,14 +65,16 @@ You can download the latest source distribution via one of the following links: </p> -<pre class="programlisting"><a href="http://pugixml.googlecode.com/files/pugixml-0.9.zip" target="_top">http://pugixml.googlecode.com/files/pugixml-0.9.zip</a> -<a href="http://pugixml.googlecode.com/files/pugixml-0.9.tar.gz" target="_top">http://pugixml.googlecode.com/files/pugixml-0.9.tar.gz</a> +<pre class="programlisting"><a href="http://pugixml.googlecode.com/files/pugixml-1.0.zip" target="_top">http://pugixml.googlecode.com/files/pugixml-1.0.zip</a> +<a href="http://pugixml.googlecode.com/files/pugixml-1.0.tar.gz" target="_top">http://pugixml.googlecode.com/files/pugixml-1.0.tar.gz</a> </pre> <p> The distribution contains library source, documentation (the manual you're reading now and the quick start guide) and some code examples. After downloading the distribution, install pugixml by extracting all files from the compressed - archive. + archive. The files have different line endings depending on the archive + format - <code class="filename">.zip</code> archive has Windows line endings, <code class="filename">.tar.gz</code> archive has Unix + line endings. Otherwise the files in both archives are identical. </p> <p> If you need an older version, you can download it from the <a href="http://code.google.com/p/pugixml/downloads/list" target="_top">version @@ -91,7 +94,7 @@ <p> For example, to checkout the current version, you can use this command: </p> -<pre class="programlisting">svn checkout http://pugixml.googlecode.com/svn/tags/release-0.9 pugixml</pre> +<pre class="programlisting">svn checkout http://pugixml.googlecode.com/svn/tags/release-1.0 pugixml</pre> <p> To checkout the latest version, you can use this command: </p> @@ -120,9 +123,9 @@ have to build them yourself. </p> <p> - The complete pugixml source consists of four files - two source files, <code class="filename">pugixml.cpp</code> and - <code class="filename">pugixpath.cpp</code>, and two header files, <code class="filename">pugixml.hpp</code> and <code class="filename">pugiconfig.hpp</code>. <code class="filename">pugixml.hpp</code> is - the primary header which you need to include in order to use pugixml classes/functions; + The complete pugixml source consists of three files - one source file, <code class="filename">pugixml.cpp</code>, + and two header files, <code class="filename">pugixml.hpp</code> and <code class="filename">pugiconfig.hpp</code>. <code class="filename">pugixml.hpp</code> is the primary + header which you need to include in order to use pugixml classes/functions; <code class="filename">pugiconfig.hpp</code> is a supplementary configuration file (see <a class="xref" href="install.html#manual.install.building.config" title="Additional configuration options"> Additional configuration options</a>). The rest of this guide assumes that <code class="filename">pugixml.hpp</code> is either in the current directory @@ -131,40 +134,31 @@ or include directory-relative path (i.e. <code class="computeroutput"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">xml</span><span class="special">/</span><span class="identifier">thirdparty</span><span class="special">/</span><span class="identifier">pugixml</span><span class="special">/</span><span class="identifier">src</span><span class="special">/</span><span class="identifier">pugixml</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>). </p> -<div class="note"><table border="0" summary="Note"> -<tr> -<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td> -<th align="left">Note</th> -</tr> -<tr><td align="left" valign="top"><p> - You don't need to compile <code class="filename">pugixpath.cpp</code> unless you use XPath. - </p></td></tr> -</table></div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="manual.install.building.embed"></a><a class="link" href="install.html#manual.install.building.embed" title="Building pugixml as a part of another static library/executable"> Building pugixml as a part of another static library/executable</a> </h4></div></div></div> <p> - The easiest way to build pugixml is to compile two source files, <code class="filename">pugixml.cpp</code> and - <code class="filename">pugixpath.cpp</code>, along with the existing library/executable. This process - depends on the method of building your application; for example, if you're - using Microsoft Visual Studio<sup>[<a name="trademarks" href="#ftn.trademarks" class="footnote">1</a>]</sup>, Apple Xcode, Code::Blocks or any other IDE, - just add <code class="filename">pugixml.cpp</code> and <code class="filename">pugixpath.cpp</code> to one of your projects. + The easiest way to build pugixml is to compile the source file, <code class="filename">pugixml.cpp</code>, + along with the existing library/executable. This process depends on the + method of building your application; for example, if you're using Microsoft + Visual Studio<sup>[<a name="trademarks" href="#ftn.trademarks" class="footnote">1</a>]</sup>, Apple Xcode, Code::Blocks or any other IDE, just add <code class="filename">pugixml.cpp</code> to + one of your projects. </p> <p> If you're using Microsoft Visual Studio and the project has precompiled headers turned on, you'll see the following error messages: </p> -<pre class="programlisting">pugixpath.cpp(3477) : fatal error C1010: unexpected end of file while looking for precompiled header. Did you forget to add '#include "stdafx.h"' to your source?</pre> +<pre class="programlisting">pugixml.cpp(3477) : fatal error C1010: unexpected end of file while looking for precompiled header. Did you forget to add '#include "stdafx.h"' to your source?</pre> <p> - The correct way to resolve this is to disable precompiled headers for <code class="filename">pugixml.cpp</code> and - <code class="filename">pugixpath.cpp</code>; you have to set "Create/Use Precompiled Header" - option (Properties dialog -> C/C++ -> Precompiled Headers -> Create/Use - Precompiled Header) to "Not Using Precompiled Headers". You'll - have to do it for both <code class="filename">pugixml.cpp</code> and <code class="filename">pugixpath.cpp</code>, for all project configurations/platforms - (you can select Configuration "All Configurations" and Platform - "All Platforms" before editing the option): + The correct way to resolve this is to disable precompiled headers for <code class="filename">pugixml.cpp</code>; + you have to set "Create/Use Precompiled Header" option (Properties + dialog -> C/C++ -> Precompiled Headers -> Create/Use Precompiled + Header) to "Not Using Precompiled Headers". You'll have to do + it for all project configurations/platforms (you can select Configuration + "All Configurations" and Platform "All Platforms" before + editing the option): </p> <div class="informaltable"><table class="table"> <colgroup><col></colgroup> @@ -251,7 +245,7 @@ process does not differ from building any other library as DLL (adding -shared to compilation flags should suffice); if you're using MSVC-based toolchain, you'll have to explicitly mark exported symbols with a declspec - attribute. You can do it by defining <code class="computeroutput"><span class="identifier">PUGIXML_API</span></code> + attribute. You can do it by defining <a class="link" href="install.html#PUGIXML_API">PUGIXML_API</a> macro, i.e. via <code class="filename">pugiconfig.hpp</code>: </p> <pre class="programlisting"><span class="preprocessor">#ifdef</span> <span class="identifier">_DLL</span> @@ -260,6 +254,20 @@ <span class="preprocessor">#define</span> <span class="identifier">PUGIXML_API</span> <span class="identifier">__declspec</span><span class="special">(</span><span class="identifier">dllimport</span><span class="special">)</span> <span class="preprocessor">#endif</span> </pre> +<div class="caution"><table border="0" summary="Caution"> +<tr> +<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../images/caution.png"></td> +<th align="left">Caution</th> +</tr> +<tr><td align="left" valign="top"><p> + If you're using STL-related functions, you should use the shared runtime + library to ensure that a single heap is used for STL allocations in your + application and in pugixml; in MSVC, this means selecting the 'Multithreaded + DLL' or 'Multithreaded Debug DLL' to 'Runtime library' property (/MD + or /MDd linker switch). You should also make sure that your runtime library + choice is consistent between different projects. + </p></td></tr> +</table></div> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> @@ -270,13 +278,13 @@ pugixml uses several defines to control the compilation process. There are two ways to define them: either put the needed definitions to <code class="filename">pugiconfig.hpp</code> (it has some examples that are commented out) or provide them via compiler - command-line. Define consistency is important, i.e. the definitions should - match in all source files that include <code class="filename">pugixml.hpp</code> (including pugixml sources) - throughout the application. Adding defines to <code class="filename">pugiconfig.hpp</code> lets you guarantee - this, unless your macro definition is wrapped in preprocessor <code class="computeroutput"><span class="preprocessor">#if</span></code>/<code class="computeroutput"><span class="preprocessor">#ifdef</span></code> - directive and this directive is not consistent. <code class="filename">pugiconfig.hpp</code> will never - contain anything but comments, which means that when upgrading to new version, - you can safely leave your modified version intact. + command-line. Consistency is important: the definitions should match in + all source files that include <code class="filename">pugixml.hpp</code> (including pugixml sources) throughout + the application. Adding defines to <code class="filename">pugiconfig.hpp</code> lets you guarantee this, + unless your macro definition is wrapped in preprocessor <code class="computeroutput"><span class="preprocessor">#if</span></code>/<code class="computeroutput"><span class="preprocessor">#ifdef</span></code> directive and this directive + is not consistent. <code class="filename">pugiconfig.hpp</code> will never contain anything but comments, + which means that when upgrading to a new version, you can safely leave + your modified version intact. </p> <p> <a name="PUGIXML_WCHAR_MODE"></a><code class="literal">PUGIXML_WCHAR_MODE</code> define toggles @@ -289,10 +297,9 @@ </p> <p> <a name="PUGIXML_NO_XPATH"></a><code class="literal">PUGIXML_NO_XPATH</code> define disables XPath. - Both XPath interfaces and XPath implementation are excluded from compilation; - you can still compile the file <code class="filename">pugixpath.cpp</code> (it will result in an empty - translation unit). This option is provided in case you do not need XPath - functionality and need to save code space. + Both XPath interfaces and XPath implementation are excluded from compilation. + This option is provided in case you do not need XPath functionality and + need to save code space. </p> <p> <a name="PUGIXML_NO_STL"></a><code class="literal">PUGIXML_NO_STL</code> define disables use of @@ -301,33 +308,11 @@ provided in case your target platform does not have a standard-compliant STL implementation. </p> -<div class="note"><table border="0" summary="Note"> -<tr> -<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td> -<th align="left">Note</th> -</tr> -<tr><td align="left" valign="top"><p> - As of version 0.9, STL is used in XPath implementation; therefore, XPath - is also disabled if this macro is defined. This will change in version - 1.0. - </p></td></tr> -</table></div> <p> <a name="PUGIXML_NO_EXCEPTIONS"></a><code class="literal">PUGIXML_NO_EXCEPTIONS</code> define disables use of exceptions in pugixml. This option is provided in case your target - platform does not have exception handling capabilities + platform does not have exception handling capabilities. </p> -<div class="note"><table border="0" summary="Note"> -<tr> -<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td> -<th align="left">Note</th> -</tr> -<tr><td align="left" valign="top"><p> - As of version 0.9, exceptions are <span class="bold"><strong>only</strong></span> - used in XPath implementation; therefore, XPath is also disabled if this - macro is defined. This will change in version 1.0. - </p></td></tr> -</table></div> <p> <a name="PUGIXML_API"></a><code class="literal">PUGIXML_API</code>, <a name="PUGIXML_CLASS"></a><code class="literal">PUGIXML_CLASS</code> and <a name="PUGIXML_FUNCTION"></a><code class="literal">PUGIXML_FUNCTION</code> defines let you @@ -414,8 +399,8 @@ </div> <div class="footnotes"> <br><hr width="100" align="left"> -<div class="footnote"><p><sup>[<a name="ftn.trademarks" href="#trademarks" class="para">1</a>] </sup>All trademarks used are properties - of their respective owners.</p></div> +<div class="footnote"><p><sup>[<a name="ftn.trademarks" href="#trademarks" class="para">1</a>] </sup>All trademarks used are properties of their respective + owners.</p></div> </div> </div> <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> @@ -427,7 +412,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> | <b>Installation</b> | Document: diff --git a/docs/manual/loading.html b/docs/manual/loading.html index a3c1515..5b5576b 100644 --- a/docs/manual/loading.html +++ b/docs/manual/loading.html @@ -4,14 +4,15 @@ <title>Loading document</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="dom.html" title="Document object model"> <link rel="next" href="access.html" title="Accessing 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: @@ -44,11 +45,11 @@ non-validating parser. This parser is not fully W3C conformant - it can load any valid XML document, but does not perform some well-formedness checks. While considerable effort is made to reject invalid XML documents, some validation - is not performed because of performance reasons. Also some XML transformations - (i.e. EOL handling or attribute value normalization) can impact parsing speed - and thus can be disabled. However for vast majority of XML documents there - is no performance difference between different parsing options. Parsing options - also control whether certain XML nodes are parsed; see <a class="xref" href="loading.html#manual.loading.options" title="Parsing options"> Parsing options</a> for + is not performed for performance reasons. Also some XML transformations (i.e. + EOL handling or attribute value normalization) can impact parsing speed and + thus can be disabled. However for vast majority of XML documents there is no + performance difference between different parsing options. Parsing options also + control whether certain XML nodes are parsed; see <a class="xref" href="loading.html#manual.loading.options" title="Parsing options"> Parsing options</a> for more information. </p> <p> @@ -65,43 +66,36 @@ <div class="titlepage"><div><div><h3 class="title"> <a name="manual.loading.file"></a><a class="link" href="loading.html#manual.loading.file" title="Loading document from file"> Loading document from file</a> </h3></div></div></div> -<a name="xml_document::load_file"></a><p> - The most common source of XML data is files; pugixml provides a separate - function for loading XML document from file: +<a name="xml_document::load_file"></a><a name="xml_document::load_file_wide"></a><p> + The most common source of XML data is files; pugixml provides dedicated functions + for loading an XML document from file: </p> <pre class="programlisting"><span class="identifier">xml_parse_result</span> <span class="identifier">xml_document</span><span class="special">::</span><span class="identifier">load_file</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="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> +<span class="identifier">xml_parse_result</span> <span class="identifier">xml_document</span><span class="special">::</span><span class="identifier">load_file</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">wchar_t</span><span class="special">*</span> <span class="identifier">path</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> - This function accepts file path as its first argument, and also two optional - arguments, which specify parsing options (see <a class="xref" href="loading.html#manual.loading.options" title="Parsing options"> Parsing options</a>) and - input data encoding (see <a class="xref" href="loading.html#manual.loading.encoding" title="Encodings"> Encodings</a>). The path has the target + These functions accept the file path as its first argument, and also two + optional arguments, which specify parsing options (see <a class="xref" href="loading.html#manual.loading.options" title="Parsing options"> Parsing options</a>) + and input data encoding (see <a class="xref" href="loading.html#manual.loading.encoding" title="Encodings"> Encodings</a>). The path has the target operating system format, so it can be a relative or absolute one, it should - have the delimiters of target system, it should have the exact case if target - file system is case-sensitive, etc. File path is passed to system file opening - function as is. + have the delimiters of the target system, it should have the exact case if + the target file system is case-sensitive, etc. + </p> +<p> + File path is passed to the system file opening function as is in case of + the first function (which accepts <code class="computeroutput"><span class="keyword">const</span> + <span class="keyword">char</span><span class="special">*</span> <span class="identifier">path</span></code>); the second function either uses + a special file opening function if it is provided by the runtime library + or converts the path to UTF-8 and uses the system file opening function. </p> <p> <code class="computeroutput"><span class="identifier">load_file</span></code> destroys the existing document tree and then tries to load the new tree from the specified file. - The result of the operation is returned in an <code class="computeroutput"><span class="identifier">xml_parse_result</span></code> - object; this object contains the operation status, and the related information + The result of the operation is returned in an <a class="link" href="loading.html#xml_parse_result">xml_parse_result</a> + object; this object contains the operation status and the related information (i.e. last successfully parsed position in the input file, if parsing fails). See <a class="xref" href="loading.html#manual.loading.errors" title="Handling parsing errors"> Handling parsing errors</a> for error handling details. </p> -<div class="note"><table border="0" summary="Note"> -<tr> -<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td> -<th align="left">Note</th> -</tr> -<tr><td align="left" valign="top"><p> - As of version 0.9, there is no function for loading XML document from wide - character path. Unfortunately, there is no portable way to do this; the - version 1.0 will provide such function only for platforms with the corresponding - functionality. You can use stream-loading functions as a workaround if - your STL implementation can open file streams via <code class="computeroutput"><span class="keyword">wchar_t</span></code> - paths. - </p></td></tr> -</table></div> <p> This is an example of loading XML document from file (<a href="../samples/load_file.cpp" target="_top">samples/load_file.cpp</a>): </p> @@ -122,7 +116,7 @@ <a name="manual.loading.memory"></a><a class="link" href="loading.html#manual.loading.memory" title="Loading document from memory"> Loading document from memory</a> </h3></div></div></div> <a name="xml_document::load_buffer"></a><a name="xml_document::load_buffer_inplace"></a><a name="xml_document::load_buffer_inplace_own"></a><p> - Sometimes XML data should be loaded from some other source than file, i.e. + Sometimes XML data should be loaded from some other source than a file, i.e. HTTP URL; also you may want to load XML data from file using non-standard functions, i.e. to use your virtual file system facilities or to load XML from gzip-compressed files. All these scenarios require loading document @@ -177,12 +171,12 @@ </pre> <p> It is equivalent to calling <code class="computeroutput"><span class="identifier">load_buffer</span></code> - with <code class="computeroutput"><span class="identifier">size</span> <span class="special">=</span> - <span class="identifier">strlen</span><span class="special">(</span><span class="identifier">contents</span><span class="special">)</span></code>. - This function assumes native encoding for input data, so it does not do any - encoding conversion. In general, this function is fine for loading small - documents from string literals, but has more overhead and less functionality - than buffer loading functions. + with <code class="computeroutput"><span class="identifier">size</span></code> being either <code class="computeroutput"><span class="identifier">strlen</span><span class="special">(</span><span class="identifier">contents</span><span class="special">)</span></code> + or <code class="computeroutput"><span class="identifier">wcslen</span><span class="special">(</span><span class="identifier">contents</span><span class="special">)</span> <span class="special">*</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="keyword">wchar_t</span><span class="special">)</span></code>, + depending on the character type. This function assumes native encoding for + input data, so it does not do any encoding conversion. In general, this function + is fine for loading small documents from string literals, but has more overhead + and less functionality than the buffer loading functions. </p> <p> This is an example of loading XML document from memory using different functions @@ -246,7 +240,7 @@ <a name="manual.loading.stream"></a><a class="link" href="loading.html#manual.loading.stream" title="Loading document from C++ IOstreams"> Loading document from C++ IOstreams</a> </h3></div></div></div> <a name="xml_document::load_stream"></a><p> - For additional interoperability pugixml provides functions for loading document + To enhance interoperability, pugixml provides functions for loading document from any object which implements C++ <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">istream</span></code> interface. This allows you to load documents from any standard C++ stream (i.e. file stream) or any third-party compliant implementation (i.e. Boost @@ -267,10 +261,10 @@ <p> <code class="computeroutput"><span class="identifier">load</span></code> with <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wstream</span></code> argument treats the stream contents as a wide character stream (encoding - is always <code class="computeroutput"><span class="identifier">encoding_wchar</span></code>). - Because of this, using <code class="computeroutput"><span class="identifier">load</span></code> - with wide character streams requires careful (usually platform-specific) - stream setup (i.e. using the <code class="computeroutput"><span class="identifier">imbue</span></code> + is always <a class="link" href="loading.html#encoding_wchar">encoding_wchar</a>). Because + of this, using <code class="computeroutput"><span class="identifier">load</span></code> with + wide character streams requires careful (usually platform-specific) stream + setup (i.e. using the <code class="computeroutput"><span class="identifier">imbue</span></code> function). Generally use of wide streams is discouraged, however it provides you the ability to load documents from non-Unicode encodings, i.e. you can load Shift-JIS encoded data if you set the correct locale. @@ -330,7 +324,7 @@ </li> <li class="listitem"> <a name="status_io_error"></a><code class="literal">status_io_error</code> is returned by <code class="computeroutput"><span class="identifier">load_file</span></code> function and by <code class="computeroutput"><span class="identifier">load</span></code> functions with <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">istream</span></code>/<code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wstream</span></code> arguments; it means that some - I/O error has occured during reading the file/stream. + I/O error has occurred during reading the file/stream. </li> <li class="listitem"> <a name="status_out_of_memory"></a><code class="literal">status_out_of_memory</code> means that @@ -407,11 +401,11 @@ member, which contains the offset of last successfully parsed character if parsing failed because of an error in source data; otherwise <code class="computeroutput"><span class="identifier">offset</span></code> is 0. For parsing efficiency reasons, pugixml does not track the current line during parsing; this offset is in - units of <code class="computeroutput"><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">char_t</span></code> (bytes for character mode, wide - characters for wide character mode). Many text editors support 'Go To Position' - feature - you can use it to locate the exact error position. Alternatively, - if you're loading the document from memory, you can display the error chunk - along with the error description (see the example code below). + units of <a class="link" href="dom.html#char_t">pugi::char_t</a> (bytes for character + mode, wide characters for wide character mode). Many text editors support + 'Go To Position' feature - you can use it to locate the exact error position. + Alternatively, if you're loading the document from memory, you can display + the error chunk along with the error description (see the example code below). </p> <div class="caution"><table border="0" summary="Caution"> <tr> @@ -490,9 +484,15 @@ <li class="listitem"> <a name="parse_declaration"></a><code class="literal">parse_declaration</code> determines if XML document declaration (node with type <a class="link" href="dom.html#node_declaration">node_declaration</a>) - are to be put in DOM tree. If this flag is off, it is not put in the - tree, but is still parsed and checked for correctness. This flag is - <span class="bold"><strong>off</strong></span> by default. <br><br> + is to be put in DOM tree. If this flag is off, it is not put in the tree, + but is still parsed and checked for correctness. This flag is <span class="bold"><strong>off</strong></span> by default. <br><br> + + </li> +<li class="listitem"> + <a name="parse_doctype"></a><code class="literal">parse_doctype</code> determines if XML document + type declaration (node with type <a class="link" href="dom.html#node_doctype">node_doctype</a>) + is to be put in DOM tree. If this flag is off, it is not put in the tree, + but is still parsed and checked for correctness. This flag is <span class="bold"><strong>off</strong></span> by default. <br><br> </li> <li class="listitem"> @@ -525,13 +525,13 @@ the cost of allocating and storing such nodes (both memory and speed-wise) can be significant. For example, after parsing XML string <code class="computeroutput"><span class="special"><</span><span class="identifier">node</span><span class="special">></span> <span class="special"><</span><span class="identifier">a</span><span class="special">/></span> <span class="special"></</span><span class="identifier">node</span><span class="special">></span></code>, <code class="computeroutput"><span class="special"><</span><span class="identifier">node</span><span class="special">></span></code> element will have three children when <code class="computeroutput"><span class="identifier">parse_ws_pcdata</span></code> - is set (child with type <code class="computeroutput"><span class="identifier">node_pcdata</span></code> + is set (child with type <a class="link" href="dom.html#node_pcdata">node_pcdata</a> and value <code class="computeroutput"><span class="string">" "</span></code>, - child with type <code class="computeroutput"><span class="identifier">node_element</span></code> - and name <code class="computeroutput"><span class="string">"a"</span></code>, and - another child with type <code class="computeroutput"><span class="identifier">node_pcdata</span></code> - and value <code class="computeroutput"><span class="string">" "</span></code>), - and only one child when <code class="computeroutput"><span class="identifier">parse_ws_pcdata</span></code> + child with type <a class="link" href="dom.html#node_element">node_element</a> and + name <code class="computeroutput"><span class="string">"a"</span></code>, and another + child with type <a class="link" href="dom.html#node_pcdata">node_pcdata</a> and value + <code class="computeroutput"><span class="string">" "</span></code>), and only + one child when <code class="computeroutput"><span class="identifier">parse_ws_pcdata</span></code> is not set. This flag is <span class="bold"><strong>off</strong></span> by default. </li> </ul></div> @@ -551,7 +551,7 @@ that as pugixml does not handle DTD, the only allowed entities are predefined ones). If character/entity reference can not be expanded, it is left as is, so you can do additional processing later. Reference expansion - is performed in attribute values and PCDATA content. This flag is <span class="bold"><strong>on</strong></span> by default. <br><br> + is performed on attribute values and PCDATA content. This flag is <span class="bold"><strong>on</strong></span> by default. <br><br> </li> <li class="listitem"> @@ -569,9 +569,9 @@ if attribute value normalization should be performed for all attributes. This means, that whitespace characters (new line, tab and space) are replaced with space (<code class="computeroutput"><span class="char">' '</span></code>). - New line characters are always treated as if <code class="computeroutput"><span class="identifier">parse_eol</span></code> + New line characters are always treated as if <a class="link" href="loading.html#parse_eol">parse_eol</a> is set, i.e. <code class="computeroutput"><span class="special">\</span><span class="identifier">r</span><span class="special">\</span><span class="identifier">n</span></code> - is converted to single space. This flag is <span class="bold"><strong>on</strong></span> + is converted to a single space. This flag is <span class="bold"><strong>on</strong></span> by default. <br><br> </li> @@ -579,10 +579,10 @@ <a name="parse_wnorm_attribute"></a><code class="literal">parse_wnorm_attribute</code> determines if extended attribute value normalization should be performed for all attributes. This means, that after attribute values are normalized as - if <code class="computeroutput"><span class="identifier">parse_wconv_attribute</span></code> + if <a class="link" href="loading.html#parse_wconv_attribute">parse_wconv_attribute</a> was set, leading and trailing space characters are removed, and all sequences of space characters are replaced by a single space character. The value - of <code class="computeroutput"><span class="identifier">parse_wconv_attribute</span></code> + of <a class="link" href="loading.html#parse_wconv_attribute">parse_wconv_attribute</a> has no effect if this flag is on. This flag is <span class="bold"><strong>off</strong></span> by default. </li> @@ -595,24 +595,25 @@ <tr><td align="left" valign="top"><p> <code class="computeroutput"><span class="identifier">parse_wconv_attribute</span></code> option performs transformations that are required by W3C specification for attributes - that are declared as <code class="literal">CDATA</code>; <code class="computeroutput"><span class="identifier">parse_wnorm_attribute</span></code> + that are declared as <code class="literal">CDATA</code>; <a class="link" href="loading.html#parse_wnorm_attribute">parse_wnorm_attribute</a> performs transformations required for <code class="literal">NMTOKENS</code> attributes. - In the absence of document type declaration all attributes behave as if - they are declared as <code class="literal">CDATA</code>, thus <code class="computeroutput"><span class="identifier">parse_wconv_attribute</span></code> + In the absence of document type declaration all attributes should behave + as if they are declared as <code class="literal">CDATA</code>, thus <a class="link" href="loading.html#parse_wconv_attribute">parse_wconv_attribute</a> is the default option. </p></td></tr> </table></div> <p> - Additionally there are two predefined option masks: + Additionally there are three predefined option masks: </p> <div class="itemizedlist"><ul class="itemizedlist" type="disc"> <li class="listitem"> <a name="parse_minimal"></a><code class="literal">parse_minimal</code> has all options turned off. This option mask means that pugixml does not add declaration nodes, - PI nodes, CDATA sections and comments to the resulting tree and does - not perform any conversion for input data, so theoretically it is the - fastest mode. However, as discussed above, in practice <code class="computeroutput"><span class="identifier">parse_default</span></code> is usually equally fast. - <br><br> + document type declaration nodes, PI nodes, CDATA sections and comments + to the resulting tree and does not perform any conversion for input data, + so theoretically it is the fastest mode. However, as mentioned above, + in practice <a class="link" href="loading.html#parse_default">parse_default</a> is usually + equally fast. <br><br> </li> <li class="listitem"> @@ -622,7 +623,18 @@ entity reference expansion, replacing whitespace characters with spaces in attribute values and performing EOL handling. Note, that PCDATA sections consisting only of whitespace characters are not parsed (by default) - for performance reasons. + for performance reasons. <br><br> + + </li> +<li class="listitem"> + <a name="parse_full"></a><code class="literal">parse_full</code> is the set of flags which adds + nodes of all types to the resulting tree and performs default conversions + for input data. It includes parsing CDATA sections, comments, PI nodes, + document declaration node and document type declaration node, performing + character and entity reference expansion, replacing whitespace characters + with spaces in attribute values and performing EOL handling. Note, that + PCDATA sections consisting only of whitespace characters are not parsed + in this mode. </li> </ul></div> <p> @@ -705,36 +717,36 @@ </li> <li class="listitem"> <a name="encoding_utf8"></a><code class="literal">encoding_utf8</code> corresponds to UTF-8 encoding - as defined in Unicode standard; UTF-8 sequences with length equal to - 5 or 6 are not standard and are rejected. + as defined in the Unicode standard; UTF-8 sequences with length equal + to 5 or 6 are not standard and are rejected. </li> <li class="listitem"> <a name="encoding_utf16_le"></a><code class="literal">encoding_utf16_le</code> corresponds to - little-endian UTF-16 encoding as defined in Unicode standard; surrogate + little-endian UTF-16 encoding as defined in the Unicode standard; surrogate pairs are supported. </li> <li class="listitem"> <a name="encoding_utf16_be"></a><code class="literal">encoding_utf16_be</code> corresponds to - big-endian UTF-16 encoding as defined in Unicode standard; surrogate + big-endian UTF-16 encoding as defined in the Unicode standard; surrogate pairs are supported. </li> <li class="listitem"> <a name="encoding_utf16"></a><code class="literal">encoding_utf16</code> corresponds to UTF-16 - encoding as defined in Unicode standard; the endianness is assumed to - be that of target platform. + encoding as defined in the Unicode standard; the endianness is assumed + to be that of the target platform. </li> <li class="listitem"> <a name="encoding_utf32_le"></a><code class="literal">encoding_utf32_le</code> corresponds to - little-endian UTF-32 encoding as defined in Unicode standard. + little-endian UTF-32 encoding as defined in the Unicode standard. </li> <li class="listitem"> <a name="encoding_utf32_be"></a><code class="literal">encoding_utf32_be</code> corresponds to - big-endian UTF-32 encoding as defined in Unicode standard. + big-endian UTF-32 encoding as defined in the Unicode standard. </li> <li class="listitem"> <a name="encoding_utf32"></a><code class="literal">encoding_utf32</code> corresponds to UTF-32 - encoding as defined in Unicode standard; the endianness is assumed to - be that of target platform. + encoding as defined in the Unicode standard; the endianness is assumed + to be that of the target platform. </li> <li class="listitem"> <a name="encoding_wchar"></a><code class="literal">encoding_wchar</code> corresponds to the encoding @@ -823,7 +835,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: diff --git a/docs/manual/modify.html b/docs/manual/modify.html index f00e657..3db02e1 100644 --- a/docs/manual/modify.html +++ b/docs/manual/modify.html @@ -4,14 +4,15 @@ <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 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="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>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: @@ -62,12 +63,13 @@ </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. <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> + 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>, + <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 set node's name or value, you can use the following functions: </p> @@ -78,16 +80,15 @@ Both functions try to set the name/value to the specified string, and return the operation result. The operation fails if the node can not have name or value (for instance, when trying to call <code class="computeroutput"><span class="identifier">set_name</span></code> - on a <code class="computeroutput"><span class="identifier">node_pcdata</span></code> node), if - the node handle is null, or if there is insufficient memory to handle the - request. The provided string is copied into document managed memory and can - be destroyed after the function returns (for example, you can safely pass - stack-allocated buffers to these functions). The name/value content is not - verified, so take care to use only valid XML names, or the document may become - malformed. + on a <a class="link" href="dom.html#node_pcdata">node_pcdata</a> node), if the node handle + is null, or if there is insufficient memory to handle the request. The provided + string is copied into document managed memory and can be destroyed after + the function returns (for example, you can safely pass stack-allocated buffers + to these functions). The name/value content is not verified, so take care + to use only valid XML names, or the document may become malformed. </p> <p> - There is no equivalent of <code class="computeroutput"><span class="identifier">child_value</span></code> + There is no equivalent of <a class="link" href="access.html#xml_node::child_value">child_value</a> function for modifying text children of the node. </p> <p> @@ -185,7 +186,7 @@ These operators simply call the right <code class="computeroutput"><span class="identifier">set_value</span></code> function and return the attribute they're called on; the return value of <code class="computeroutput"><span class="identifier">set_value</span></code> is ignored, so - errors are not detected. + errors are ignored. </p> <p> This is an example of setting attribute name and value (<a href="../samples/modify_base.cpp" target="_top">samples/modify_base.cpp</a>): @@ -214,36 +215,48 @@ <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> </h3></div></div></div> -<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::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 outside of 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: +<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 + 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> <pre class="programlisting"><span class="identifier">xml_attribute</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">append_attribute</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="identifier">xml_attribute</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">prepend_attribute</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="identifier">xml_attribute</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">insert_attribute_after</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="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">attr</span><span class="special">);</span> <span class="identifier">xml_attribute</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">insert_attribute_before</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="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">attr</span><span class="special">);</span> <span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">append_child</span><span class="special">(</span><span class="identifier">xml_node_type</span> <span class="identifier">type</span> <span class="special">=</span> <span class="identifier">node_element</span><span class="special">);</span> +<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">prepend_child</span><span class="special">(</span><span class="identifier">xml_node_type</span> <span class="identifier">type</span> <span class="special">=</span> <span class="identifier">node_element</span><span class="special">);</span> <span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">insert_child_after</span><span class="special">(</span><span class="identifier">xml_node_type</span> <span class="identifier">type</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">node</span><span class="special">);</span> <span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">insert_child_before</span><span class="special">(</span><span class="identifier">xml_node_type</span> <span class="identifier">type</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">node</span><span class="special">);</span> + +<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">append_child</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="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">prepend_child</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="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">insert_child_after</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="identifier">xml_node</span><span class="special">&</span> <span class="identifier">node</span><span class="special">);</span> +<span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">insert_child_before</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="identifier">xml_node</span><span class="special">&</span> <span class="identifier">node</span><span class="special">);</span> </pre> <p> <code class="computeroutput"><span class="identifier">append_attribute</span></code> and <code class="computeroutput"><span class="identifier">append_child</span></code> create a new node/attribute at the end of the corresponding list of the node the method is called on; - <code class="computeroutput"><span class="identifier">insert_attribute_after</span></code>, + <code class="computeroutput"><span class="identifier">prepend_attribute</span></code> and <code class="computeroutput"><span class="identifier">prepend_child</span></code> create a new node/attribute + at the beginning of the list; <code class="computeroutput"><span class="identifier">insert_attribute_after</span></code>, <code class="computeroutput"><span class="identifier">insert_attribute_before</span></code>, <code class="computeroutput"><span class="identifier">insert_child_after</span></code> and <code class="computeroutput"><span class="identifier">insert_attribute_before</span></code> add the node/attribute - before or after specified node/attribute. + before or after the specified node/attribute. </p> <p> Attribute functions create an attribute with the specified name; you can specify the empty name and change the name later if you want to. Node functions - create the node with the specified type; since node type can't be changed, - you have to know the desired type beforehand. Also note that not all types - can be added as children; see below for clarification. + with the <code class="computeroutput"><span class="identifier">type</span></code> argument create + the node with the specified type; since node type can't be changed, you have + to know the desired type beforehand. Also note that not all types can be + added as children; see below for clarification. Node functions with the + <code class="computeroutput"><span class="identifier">name</span></code> argument create the + element node (<a class="link" href="dom.html#node_element">node_element</a>) with the + specified name. </p> <p> - All functions return the handle to newly created object on success, and null + 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"> @@ -251,32 +264,30 @@ Adding fails if the target node is null; </li> <li class="listitem"> - Only <code class="computeroutput"><span class="identifier">node_element</span></code> nodes - can contain attributes, so attribute adding fails if node is not an element; + Only <a class="link" href="dom.html#node_element">node_element</a> nodes can contain + attributes, so attribute adding fails if node is not an element; </li> <li class="listitem"> - Only <code class="computeroutput"><span class="identifier">node_document</span></code> and - <code class="computeroutput"><span class="identifier">node_element</span></code> nodes can - contain children, so child node adding fails if target node is not an - element or a document; + Only <a class="link" href="dom.html#node_document">node_document</a> and <a class="link" href="dom.html#node_element">node_element</a> + nodes can contain children, so child node adding fails if the target + node is not an element or a document; </li> <li class="listitem"> - <code class="computeroutput"><span class="identifier">node_document</span></code> and <code class="computeroutput"><span class="identifier">node_null</span></code> nodes can not be inserted - as children, so passing <code class="computeroutput"><span class="identifier">node_document</span></code> - or <code class="computeroutput"><span class="identifier">node_null</span></code> value as - type results in operation failure; + <a class="link" href="dom.html#node_document">node_document</a> and <a class="link" href="dom.html#node_null">node_null</a> + nodes can not be inserted as children, so passing <a class="link" href="dom.html#node_document">node_document</a> + or <a class="link" href="dom.html#node_null">node_null</a> value as <code class="computeroutput"><span class="identifier">type</span></code> results in operation failure; </li> <li class="listitem"> - <code class="computeroutput"><span class="identifier">node_declaration</span></code> nodes - can only be added as children of the document node; attempt to insert - declaration node as a child of an element node fails; + <a class="link" href="dom.html#node_declaration">node_declaration</a> nodes can only + be added as children of the document node; attempt to insert declaration + node as a child of an element node fails; </li> <li class="listitem"> Adding node/attribute results in memory allocation, which may fail; </li> <li class="listitem"> - Insertion functions fail if the specified node or attribute is not in - the target node's children/attribute list. + Insertion functions fail if the specified node or attribute is null or + is not in the target node's children/attribute list. </li> </ul></div> <p> @@ -302,17 +313,14 @@ </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="identifier">node</span><span class="special">.</span><span class="identifier">set_name</span><span class="special">(</span><span class="string">"node"</span><span class="special">);</span> +</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="identifier">descr</span><span class="special">.</span><span class="identifier">set_name</span><span class="special">(</span><span class="string">"description"</span><span class="special">);</span> +</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="identifier">pugi</span><span class="special">::</span><span class="identifier">node_element</span><span class="special">,</span> <span class="identifier">descr</span><span class="special">);</span> -<span class="identifier">param</span><span class="special">.</span><span class="identifier">set_name</span><span class="special">(</span><span class="string">"param"</span><span class="special">);</span> +</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> @@ -400,29 +408,32 @@ <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> </h3></div></div></div> -<a name="xml_node::append_copy"></a><a name="xml_node::insert_copy_after"></a><a name="xml_node::insert_copy_before"></a><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><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 - outside of document tree, you can't create a standalone copy - you have to + 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">&</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">&</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">insert_copy_after</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">proto</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">attr</span><span class="special">);</span> <span class="identifier">xml_attribute</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">insert_copy_before</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">proto</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">xml_attribute</span><span class="special">&</span> <span class="identifier">attr</span><span class="special">);</span> + <span class="identifier">xml_node</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_node</span><span class="special">&</span> <span class="identifier">proto</span><span class="special">);</span> +<span class="identifier">xml_node</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_node</span><span class="special">&</span> <span class="identifier">proto</span><span class="special">);</span> <span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">insert_copy_after</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">proto</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">node</span><span class="special">);</span> <span class="identifier">xml_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">insert_copy_before</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">proto</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">node</span><span class="special">);</span> </pre> <p> These functions mirror the structure of <code class="computeroutput"><span class="identifier">append_child</span></code>, - <code class="computeroutput"><span class="identifier">insert_child_before</span></code> and related - functions - they take the handle to the prototype object, which is to be - cloned, insert a new attribute/node at the appropriate place, and then copy - the attribute data or the whole node subtree to the new object. The functions - return the handle to the resulting duplicate object, or null handle on failure. + <code class="computeroutput"><span class="identifier">prepend_child</span></code>, <code class="computeroutput"><span class="identifier">insert_child_before</span></code> and related functions + - they take the handle to the prototype object, which is to be cloned, insert + a new attribute/node at the appropriate place, and then copy the attribute + data or the whole node subtree to the new object. The functions return the + handle to the resulting duplicate object, or null handle on failure. </p> <p> The attribute is copied along with the name and value; the node is copied @@ -445,7 +456,7 @@ <li class="listitem"> Node cloning starts with insertion of the node of the same type as that of the prototype; for this reason, cloning functions can not be directly - used to clone entire documents, since <code class="computeroutput"><span class="identifier">node_document</span></code> + used to clone entire documents, since <a class="link" href="dom.html#node_document">node_document</a> is not a valid insertion type. The example below provides a workaround. </li> <li class="listitem"> @@ -524,7 +535,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: diff --git a/docs/manual/saving.html b/docs/manual/saving.html index e12b31d..2cbf06e 100644 --- a/docs/manual/saving.html +++ b/docs/manual/saving.html @@ -4,14 +4,15 @@ <title>Saving document</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="modify.html" title="Modifying document data"> <link rel="next" href="xpath.html" title="XPath"> </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: @@ -49,42 +50,45 @@ the relevant functionality. </p> <p> - The node/attribute data is written to the destination properly formatted according - to the node type; all special XML symbols, such as < and &, are properly - escaped. In order to guard against forgotten node/attribute names, empty node/attribute - names are printed as <code class="computeroutput"><span class="string">":anonymous"</span></code>. - For proper output, make sure all node and attribute names are set to meaningful + Before writing to the destination the node/attribute data is properly formatted + according to the node type; all special XML symbols, such as < and &, + are properly escaped. In order to guard against forgotten node/attribute names, + empty node/attribute names are printed as <code class="computeroutput"><span class="string">":anonymous"</span></code>. + For well-formed output, make sure all node and attribute names are set to meaningful values. </p> -<div class="caution"><table border="0" summary="Caution"> -<tr> -<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../images/caution.png"></td> -<th align="left">Caution</th> -</tr> -<tr><td align="left" valign="top"><p> - Currently the content of CDATA sections is not escaped, so CDATA sections - with values that contain <code class="computeroutput"><span class="string">"]]>"</span></code> - will result in malformed document. This will be fixed in version 1.0. - </p></td></tr> -</table></div> +<p> + CDATA sections with values that contain <code class="computeroutput"><span class="string">"]]>"</span></code> + are split into several sections as follows: section with value <code class="computeroutput"><span class="string">"pre]]>post"</span></code> is written as <code class="computeroutput"><span class="special"><![</span><span class="identifier">CDATA</span><span class="special">[</span><span class="identifier">pre</span><span class="special">]]]]><![</span><span class="identifier">CDATA</span><span class="special">[></span><span class="identifier">post</span><span class="special">]]></span></code>. + While this alters the structure of the document (if you load the document after + saving it, there will be two CDATA sections instead of one), this is the only + way to escape CDATA contents. + </p> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="manual.saving.file"></a><a class="link" href="saving.html#manual.saving.file" title="Saving document to a file"> Saving document to a file</a> </h3></div></div></div> -<a name="xml_document::save_file"></a><p> - If you want to save the whole document to a file, you can use the following - function: +<a name="xml_document::save_file"></a><a name="xml_document::save_file_wide"></a><p> + If you want to save the whole document to a file, you can use one of the + following functions: </p> <pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xml_document</span><span class="special">::</span><span class="identifier">save_file</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="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">indent</span> <span class="special">=</span> <span class="string">"\t"</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">flags</span> <span class="special">=</span> <span class="identifier">format_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> <span class="keyword">const</span><span class="special">;</span> +<span class="keyword">bool</span> <span class="identifier">xml_document</span><span class="special">::</span><span class="identifier">save_file</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">wchar_t</span><span class="special">*</span> <span class="identifier">path</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">indent</span> <span class="special">=</span> <span class="string">"\t"</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">flags</span> <span class="special">=</span> <span class="identifier">format_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> <span class="keyword">const</span><span class="special">;</span> </pre> <p> - This function accepts file path as its first argument, and also three optional + These functions accept file path as its first argument, and also three optional arguments, which specify indentation and other output options (see <a class="xref" href="saving.html#manual.saving.options" title="Output options"> Output options</a>) and output data encoding (see <a class="xref" href="saving.html#manual.saving.encoding" title="Encodings"> Encodings</a>). The path has the target operating system format, so it can be a relative or absolute one, it should - have the delimiters of target system, it should have the exact case if target - file system is case-sensitive, etc. File path is passed to system file opening - function as is. + have the delimiters of the target system, it should have the exact case if + the target file system is case-sensitive, etc. + </p> +<p> + File path is passed to the system file opening function as is in case of + the first function (which accepts <code class="computeroutput"><span class="keyword">const</span> + <span class="keyword">char</span><span class="special">*</span> <span class="identifier">path</span></code>); the second function either uses + a special file opening function if it is provided by the runtime library + or converts the path to UTF-8 and uses the system file opening function. </p> <a name="xml_writer_file"></a><p> <code class="computeroutput"><span class="identifier">save_file</span></code> opens the target @@ -96,19 +100,6 @@ handle as the only constructor argument and then calling <code class="computeroutput"><span class="identifier">save</span></code>; see <a class="xref" href="saving.html#manual.saving.writer" title="Saving document via writer interface"> Saving document via writer interface</a> for writer interface details. </p> -<div class="note"><table border="0" summary="Note"> -<tr> -<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td> -<th align="left">Note</th> -</tr> -<tr><td align="left" valign="top"><p> - As of version 0.9, there is no function for saving XML document to wide - character paths. Unfortunately, there is no portable way to do this; the - version 1.0 will provide such function only for platforms with the corresponding - functionality. You can use stream-saving functions as a workaround if your - STL implementation can open file streams via wchar_t paths. - </p></td></tr> -</table></div> <p> This is a simple example of saving XML document to file (<a href="../samples/save_file.cpp" target="_top">samples/save_file.cpp</a>): </p> @@ -126,11 +117,11 @@ <a name="manual.saving.stream"></a><a class="link" href="saving.html#manual.saving.stream" title="Saving document to C++ IOstreams"> Saving document to C++ IOstreams</a> </h3></div></div></div> <a name="xml_document::save_stream"></a><p> - For additional interoperability pugixml provides functions for saving document - to any object which implements C++ std::ostream interface. This allows you - to save documents to any standard C++ stream (i.e. file stream) or any third-party - compliant implementation (i.e. Boost Iostreams). Most notably, this allows - for easy debug output, since you can use <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span></code> + To enhance interoperability pugixml provides functions for saving document + to any object which implements C++ <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span></code> + interface. This allows you to save documents to any standard C++ stream (i.e. + file stream) or any third-party compliant implementation (i.e. Boost Iostreams). + Most notably, this allows for easy debug output, since you can use <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span></code> stream as saving target. There are two functions, one works with narrow character streams, another handles wide character ones: </p> @@ -142,7 +133,7 @@ argument saves the document to the stream in the same way as <code class="computeroutput"><span class="identifier">save_file</span></code> (i.e. with requested header and with encoding conversions). On the other hand, <code class="computeroutput"><span class="identifier">save</span></code> with <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wstream</span></code> argument saves the document to - the wide stream with <code class="computeroutput"><span class="identifier">encoding_wchar</span></code> + the wide stream with <a class="link" href="loading.html#encoding_wchar">encoding_wchar</a> encoding. Because of this, using <code class="computeroutput"><span class="identifier">save</span></code> with wide character streams requires careful (usually platform-specific) stream setup (i.e. using the <code class="computeroutput"><span class="identifier">imbue</span></code> @@ -201,7 +192,7 @@ <p> <code class="computeroutput"><span class="identifier">write</span></code> function is called with relatively large blocks (size is usually several kilobytes, except for - the first block with BOM, which is output only if <code class="computeroutput"><span class="identifier">format_write_bom</span></code> + the first block with BOM, which is output only if <a class="link" href="saving.html#format_write_bom">format_write_bom</a> is set, and last block, which may be small), so there is often no need for additional buffering in the implementation. </p> @@ -231,9 +222,8 @@ <a name="manual.saving.subtree"></a><a class="link" href="saving.html#manual.saving.subtree" title="Saving a single subtree"> Saving a single subtree</a> </h3></div></div></div> <a name="xml_node::print"></a><a name="xml_node::print_stream"></a><p> - While the previously described functions saved the whole document to the - destination, it is easy to save a single subtree. The following functions - are provided: + While the previously described functions save the whole document to the destination, + it is easy to save a single subtree. The following functions are provided: </p> <pre class="programlisting"><span class="keyword">void</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">print</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span><span class="special">&</span> <span class="identifier">os</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">indent</span> <span class="special">=</span> <span class="string">"\t"</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">flags</span> <span class="special">=</span> <span class="identifier">format_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> <span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">depth</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> <span class="keyword">void</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">print</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">wostream</span><span class="special">&</span> <span class="identifier">os</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">indent</span> <span class="special">=</span> <span class="string">"\t"</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">flags</span> <span class="special">=</span> <span class="identifier">format_default</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">depth</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> @@ -246,10 +236,10 @@ </p> <p> Saving a subtree differs from saving the whole document: the process behaves - as if <code class="computeroutput"><span class="identifier">format_write_bom</span></code> is - off, and <code class="computeroutput"><span class="identifier">format_no_declaration</span></code> - is on, even if actual values of the flags are different. This means that - BOM is not written to the destination, and document declaration is only written + as if <a class="link" href="saving.html#format_write_bom">format_write_bom</a> is off, and + <a class="link" href="saving.html#format_no_declaration">format_no_declaration</a> is on, + even if actual values of the flags are different. This means that BOM is + not written to the destination, and document declaration is only written if it is the node itself or is one of node's children. Note that this also holds if you're saving a document; this example (<a href="../samples/save_subtree.cpp" target="_top">samples/save_subtree.cpp</a>) illustrates the difference: @@ -308,8 +298,8 @@ by default). If this flag is on, before every node the indentation string is output several times, where the amount of indentation depends on the node's depth relative to the output subtree. This flag has no effect - if <code class="computeroutput"><span class="identifier">format_raw</span></code> is enabled. - This flag is <span class="bold"><strong>on</strong></span> by default. <br><br> + if <a class="link" href="saving.html#format_raw">format_raw</a> is enabled. This flag + is <span class="bold"><strong>on</strong></span> by default. <br><br> </li> <li class="listitem"> @@ -318,9 +308,9 @@ and also no newlines that are not part of document text are printed. Raw mode can be used for serialization where the result is not intended to be read by humans; also it can be useful if the document was parsed - with <code class="computeroutput"><span class="identifier">parse_ws_pcdata</span></code> - flag, to preserve the original document formatting as much as possible. - This flag is <span class="bold"><strong>off</strong></span> by default. + with <a class="link" href="loading.html#parse_ws_pcdata">parse_ws_pcdata</a> flag, to + preserve the original document formatting as much as possible. This flag + is <span class="bold"><strong>off</strong></span> by default. </li> </ul></div> <p> @@ -429,7 +419,7 @@ </p> <p> Also note that wide stream saving functions do not have <code class="computeroutput"><span class="identifier">encoding</span></code> - argument and always assume <code class="computeroutput"><span class="identifier">encoding_wchar</span></code> + argument and always assume <a class="link" href="loading.html#encoding_wchar">encoding_wchar</a> encoding. </p> <div class="note"><table border="0" summary="Note"> @@ -456,7 +446,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: diff --git a/docs/manual/toc.html b/docs/manual/toc.html index e078307..97d0b6c 100644 --- a/docs/manual/toc.html +++ b/docs/manual/toc.html @@ -4,13 +4,14 @@ <title>Table of Contents</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="apiref.html" title="API Reference"> </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: @@ -134,7 +135,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: diff --git a/docs/manual/xpath.html b/docs/manual/xpath.html index 731a969..5a97a79 100644 --- a/docs/manual/xpath.html +++ b/docs/manual/xpath.html @@ -4,14 +4,15 @@ <title>XPath</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="saving.html" title="Saving document"> <link rel="next" href="changes.html" title="Changelog"> </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: @@ -33,6 +34,7 @@ <dt><span class="section"><a href="xpath.html#manual.xpath.types"> XPath types</a></span></dt> <dt><span class="section"><a href="xpath.html#manual.xpath.select"> Selecting nodes via XPath expression</a></span></dt> <dt><span class="section"><a href="xpath.html#manual.xpath.query"> Using query objects</a></span></dt> +<dt><span class="section"><a href="xpath.html#manual.xpath.variables"> Using variables</a></span></dt> <dt><span class="section"><a href="xpath.html#manual.xpath.errors"> Error handling</a></span></dt> <dt><span class="section"><a href="xpath.html#manual.xpath.w3c"> Conformance to W3C specification</a></span></dt> </dl></div> @@ -54,18 +56,6 @@ at tizag.com</a>, and <a href="http://www.w3.org/TR/xpath/" target="_top">the XPath 1.0 specification</a>. </p> -<div class="note"><table border="0" summary="Note"> -<tr> -<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td> -<th align="left">Note</th> -</tr> -<tr><td align="left" valign="top"><p> - As of version 0.9, you need both STL and exception support to use XPath; - XPath is disabled if either <code class="computeroutput"><span class="identifier">PUGIXML_NO_STL</span></code> - or <code class="computeroutput"><span class="identifier">PUGIXML_NO_EXCEPTIONS</span></code> - is defined. - </p></td></tr> -</table></div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="manual.xpath.types"></a><a class="link" href="xpath.html#manual.xpath.types" title="XPath types"> XPath types</a> @@ -76,7 +66,7 @@ type, number type corresponds to <code class="computeroutput"><span class="keyword">double</span></code> type, string type corresponds to either <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code> or <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wstring</span></code>, depending on whether <a class="link" href="dom.html#manual.dom.unicode" title="Unicode interface">wide - character interface is enabled</a>, and node set corresponds to <code class="computeroutput"><span class="identifier">xpath_node_set</span></code> type. There is an enumeration, + character interface is enabled</a>, and node set corresponds to <a class="link" href="xpath.html#xpath_node_set">xpath_node_set</a> type. There is an enumeration, <code class="computeroutput"><span class="identifier">xpath_value_type</span></code>, which can take the values <code class="computeroutput"><span class="identifier">xpath_type_boolean</span></code>, <code class="computeroutput"><span class="identifier">xpath_type_number</span></code>, <code class="computeroutput"><span class="identifier">xpath_type_string</span></code> or <code class="computeroutput"><span class="identifier">xpath_type_node_set</span></code>, @@ -117,12 +107,14 @@ for equality with each other. </p> <a name="xpath_node::ctor"></a><p> - You can also create XPath nodes with one of tree constructors: the default + You can also create XPath nodes with one of the three constructors: the default constructor, the constructor that takes node argument, and the constructor that takes attribute and node arguments (in which case the attribute must - belong to the attribute list of the node). However, usually you don't need - to create your own XPath node objects, since they are returned to you via - selection functions. + belong to the attribute list of the node). The constructor from <code class="computeroutput"><span class="identifier">xml_node</span></code> is implicit, so you can usually + pass <code class="computeroutput"><span class="identifier">xml_node</span></code> to functions + that expect <code class="computeroutput"><span class="identifier">xpath_node</span></code>. Apart + from that you usually don't need to create your own XPath node objects, since + they are returned to you via selection functions. </p> <a name="xpath_node_set"></a><p> XPath expressions operate not on single nodes, but instead on node sets. @@ -153,7 +145,7 @@ the iterators are random-access, all of the above operations are constant time, and accessing the element at index that is greater or equal than the set size results in undefined behavior. You can use both iterator-based and - index-based access for iteration, however the iterator-based can be faster. + index-based access for iteration, however the iterator-based one can be faster. </p> <a name="xpath_node_set::type"></a><a name="xpath_node_set::type_unsorted"></a><a name="xpath_node_set::type_sorted"></a><a name="xpath_node_set::type_sorted_reverse"></a><a name="xpath_node_set::sort"></a><p> The order of iteration depends on the order of nodes inside the set; the @@ -195,6 +187,21 @@ the complexity does - if the set is sorted, the complexity is constant, otherwise it is linear in the number of elements or worse. </p> +<a name="xpath_node_set::ctor"></a><p> + While in the majority of cases the node set is returned by XPath functions, + sometimes there is a need to manually construct a node set. For such cases, + a constructor is provided which takes an iterator range (<code class="computeroutput"><span class="identifier">const_iterator</span></code> + is a typedef for <code class="computeroutput"><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">*</span></code>), and an optional type: + </p> +<pre class="programlisting"><span class="identifier">xpath_node_set</span><span class="special">::</span><span class="identifier">xpath_node_set</span><span class="special">(</span><span class="identifier">const_iterator</span> <span class="identifier">begin</span><span class="special">,</span> <span class="identifier">const_iterator</span> <span class="identifier">end</span><span class="special">,</span> <span class="identifier">type_t</span> <span class="identifier">type</span> <span class="special">=</span> <span class="identifier">type_unsorted</span><span class="special">);</span> +</pre> +<p> + The constructor copies the specified range and sets the specified type. The + objects in the range are not checked in any way; you'll have to ensure that + the range contains no duplicates, and that the objects are sorted according + to the <code class="computeroutput"><span class="identifier">type</span></code> parameter. Otherwise + XPath operations with this set may produce unexpected results. + </p> </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> @@ -204,8 +211,8 @@ If you want to select nodes that match some XPath expression, you can do it with the following functions: </p> -<pre class="programlisting"><span class="identifier">xpath_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">select_single_node</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">query</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> -<span class="identifier">xpath_node_set</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">select_nodes</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">query</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +<pre class="programlisting"><span class="identifier">xpath_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">select_single_node</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">query</span><span class="special">,</span> <span class="identifier">xpath_variable_set</span><span class="special">*</span> <span class="identifier">variables</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +<span class="identifier">xpath_node_set</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">select_nodes</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">query</span><span class="special">,</span> <span class="identifier">xpath_variable_set</span><span class="special">*</span> <span class="identifier">variables</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> </pre> <p> <code class="computeroutput"><span class="identifier">select_nodes</span></code> function compiles @@ -219,7 +226,7 @@ returns null XPath node. </p> <p> - Both functions throw <code class="computeroutput"><span class="identifier">xpath_exception</span></code> + If exception handling is not disabled, both functions throw <a class="link" href="xpath.html#xpath_exception">xpath_exception</a> if the query can not be compiled or if it returns a value with type other than node set; see <a class="xref" href="xpath.html#manual.xpath.errors" title="Error handling"> Error handling</a> for details. </p> @@ -235,7 +242,7 @@ <span class="identifier">xpath_node_set</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">select_nodes</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_query</span><span class="special">&</span> <span class="identifier">query</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> </pre> <p> - Both functions throw <code class="computeroutput"><span class="identifier">xpath_exception</span></code> + If exception handling is not disabled, both functions throw <a class="link" href="xpath.html#xpath_exception">xpath_exception</a> if the query returns a value with type other than node set. </p> <p> @@ -268,8 +275,8 @@ <a name="xpath_query"></a><p> When you call <code class="computeroutput"><span class="identifier">select_nodes</span></code> with an expression string as an argument, a query object is created behind - the scene. A query object represents a compiled XPath expression. Query objects - can be needed in the following circumstances: + the scenes. A query object represents a compiled XPath expression. Query + objects can be needed in the following circumstances: </p> <div class="itemizedlist"><ul class="itemizedlist" type="disc"> <li class="listitem"> @@ -296,33 +303,34 @@ You can create a query object with the constructor that takes XPath expression as an argument: </p> -<pre class="programlisting"><span class="keyword">explicit</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">xpath_query</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">query</span><span class="special">);</span> +<pre class="programlisting"><span class="keyword">explicit</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">xpath_query</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">query</span><span class="special">,</span> <span class="identifier">xpath_variable_set</span><span class="special">*</span> <span class="identifier">variables</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span> </pre> <a name="xpath_query::return_type"></a><p> The expression is compiled and the compiled representation is stored in the - new query object. If compilation fails, <code class="computeroutput"><span class="identifier">xpath_exception</span></code> - is thrown (see <a class="xref" href="xpath.html#manual.xpath.errors" title="Error handling"> Error handling</a> for details). After the query is created, - you can query the type of the evaluation result using the following function: + new query object. If compilation fails, <a class="link" href="xpath.html#xpath_exception">xpath_exception</a> + is thrown if exception handling is not disabled (see <a class="xref" href="xpath.html#manual.xpath.errors" title="Error handling"> Error handling</a> for + details). After the query is created, you can query the type of the evaluation + result using the following function: </p> <pre class="programlisting"><span class="identifier">xpath_value_type</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">return_type</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> </pre> <a name="xpath_query::evaluate_boolean"></a><a name="xpath_query::evaluate_number"></a><a name="xpath_query::evaluate_string"></a><a name="xpath_query::evaluate_node_set"></a><p> You can evaluate the query using one of the following functions: </p> -<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">evaluate_boolean</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> -<span class="keyword">double</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">evaluate_number</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> -<span class="identifier">string_t</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">evaluate_string</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> -<span class="identifier">xpath_node_set</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">evaluate_node_set</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xml_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">evaluate_boolean</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +<span class="keyword">double</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">evaluate_number</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +<span class="identifier">string_t</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">evaluate_string</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +<span class="identifier">xpath_node_set</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">evaluate_node_set</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> </pre> <p> All functions take the context node as an argument, compute the expression - and return the result, converted to the requested type. By XPath specification, - value of any type can be converted to boolean, number or string value, but - no type other than node set can be converted to node set. Because of this, - <code class="computeroutput"><span class="identifier">evaluate_boolean</span></code>, <code class="computeroutput"><span class="identifier">evaluate_number</span></code> and <code class="computeroutput"><span class="identifier">evaluate_string</span></code> - always return a result, but <code class="computeroutput"><span class="identifier">evaluate_node_set</span></code> - throws an <code class="computeroutput"><span class="identifier">xpath_exception</span></code> - if the return type is not node set. + and return the result, converted to the requested type. According to XPath + specification, value of any type can be converted to boolean, number or string + value, but no type other than node set can be converted to node set. Because + of this, <code class="computeroutput"><span class="identifier">evaluate_boolean</span></code>, + <code class="computeroutput"><span class="identifier">evaluate_number</span></code> and <code class="computeroutput"><span class="identifier">evaluate_string</span></code> always return a result, + but <code class="computeroutput"><span class="identifier">evaluate_node_set</span></code> results + in an error if the return type is not node set (see <a class="xref" href="xpath.html#manual.xpath.errors" title="Error handling"> Error handling</a>). </p> <div class="note"><table border="0" summary="Note"> <tr> @@ -334,6 +342,36 @@ is equivalent to calling <code class="computeroutput"><span class="identifier">xpath_query</span><span class="special">(</span><span class="string">"query"</span><span class="special">).</span><span class="identifier">evaluate_node_set</span><span class="special">(</span><span class="identifier">node</span><span class="special">)</span></code>. </p></td></tr> </table></div> +<a name="xpath_query::evaluate_string_buffer"></a><p> + Note that <code class="computeroutput"><span class="identifier">evaluate_string</span></code> + function returns the STL string; as such, it's not available in <a class="link" href="install.html#PUGIXML_NO_STL">PUGIXML_NO_STL</a> + mode and also usually allocates memory. There is another string evaluation + function: + </p> +<pre class="programlisting"><span class="identifier">size_t</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">evaluate_string</span><span class="special">(</span><span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">size_t</span> <span class="identifier">capacity</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">xpath_node</span><span class="special">&</span> <span class="identifier">n</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<p> + This function evaluates the string, and then writes the result to <code class="computeroutput"><span class="identifier">buffer</span></code> (but at most <code class="computeroutput"><span class="identifier">capacity</span></code> + characters); then it returns the full size of the result in characters, including + the terminating zero. If <code class="computeroutput"><span class="identifier">capacity</span></code> + is not 0, the resulting buffer is always zero-terminated. You can use this + function as follows: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + First call the function with <code class="computeroutput"><span class="identifier">buffer</span> + <span class="special">=</span> <span class="number">0</span></code> + and <code class="computeroutput"><span class="identifier">capacity</span> <span class="special">=</span> + <span class="number">0</span></code>; then allocate the returned amount + of characters, and call the function again, passing the allocated storage + and the amount of characters; + </li> +<li class="listitem"> + First call the function with small buffer and buffer capacity; then, + if the result is larger than the capacity, the output has been trimmed, + so allocate a larger buffer and call the function again. + </li> +</ul></div> <p> This is an example of using query objects (<a href="../samples/xpath_query.cpp" target="_top">samples/xpath_query.cpp</a>): </p> @@ -367,22 +405,237 @@ </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> +<a name="manual.xpath.variables"></a><a class="link" href="xpath.html#manual.xpath.variables" title="Using variables"> Using variables</a> +</h3></div></div></div> +<p> + XPath queries may contain references to variables; this is useful if you + want to use queries that depend on some dynamic parameter without manually + preparing the complete query string, or if you want to reuse the same query + object for similar queries. + </p> +<p> + Variable references have the form <code class="computeroutput"><span class="identifier">$name</span></code>; in order to use them, you have to provide + a variable set, which includes all variables present in the query with correct + types. This set is passed to <code class="computeroutput"><span class="identifier">xpath_query</span></code> + constructor or to <code class="computeroutput"><span class="identifier">select_nodes</span></code>/<code class="computeroutput"><span class="identifier">select_single_node</span></code> functions: + </p> +<pre class="programlisting"><span class="keyword">explicit</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">xpath_query</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">query</span><span class="special">,</span> <span class="identifier">xpath_variable_set</span><span class="special">*</span> <span class="identifier">variables</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span> +<span class="identifier">xpath_node</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">select_single_node</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">query</span><span class="special">,</span> <span class="identifier">xpath_variable_set</span><span class="special">*</span> <span class="identifier">variables</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +<span class="identifier">xpath_node_set</span> <span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">select_nodes</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">query</span><span class="special">,</span> <span class="identifier">xpath_variable_set</span><span class="special">*</span> <span class="identifier">variables</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<p> + If you're using query objects, you can change the variable values before + <code class="computeroutput"><span class="identifier">evaluate</span></code>/<code class="computeroutput"><span class="identifier">select</span></code> + calls to change the query behavior. + </p> +<div class="note"><table border="0" summary="Note"> +<tr> +<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td> +<th align="left">Note</th> +</tr> +<tr><td align="left" valign="top"><p> + The variable set pointer is stored in the query object; you have to ensure + that the lifetime of the set exceeds that of query object. + </p></td></tr> +</table></div> +<a name="xpath_variable_set"></a><p> + Variable sets correspond to <code class="computeroutput"><span class="identifier">xpath_variable_set</span></code> + type, which is essentially a variable container. + </p> +<a name="xpath_variable_set::add"></a><p> + You can add new variables with the following function: + </p> +<pre class="programlisting"><span class="identifier">xpath_variable</span><span class="special">*</span> <span class="identifier">xpath_variable_set</span><span class="special">::</span><span class="identifier">add</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="identifier">xpath_value_type</span> <span class="identifier">type</span><span class="special">);</span> +</pre> +<p> + The function tries to add a new variable with the specified name and type; + if the variable with such name does not exist in the set, the function adds + a new variable and returns the variable handle; if there is already a variable + with the specified name, the function returns the variable handle if variable + has the specified type. Otherwise the function returns null pointer; it also + returns null pointer on allocation failure. + </p> +<p> + New variables are assigned the default value which depends on the type: + <code class="computeroutput"><span class="number">0</span></code> for numbers, <code class="computeroutput"><span class="keyword">false</span></code> for booleans, empty string for strings + and empty set for node sets. + </p> +<a name="xpath_variable_set::get"></a><p> + You can get the existing variables with the following functions: + </p> +<pre class="programlisting"><span class="identifier">xpath_variable</span><span class="special">*</span> <span class="identifier">xpath_variable_set</span><span class="special">::</span><span class="identifier">get</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="identifier">xpath_variable</span><span class="special">*</span> <span class="identifier">xpath_variable_set</span><span class="special">::</span><span class="identifier">get</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> + The functions return the variable handle, or null pointer if the variable + with the specified name is not found. + </p> +<a name="xpath_variable_set::set"></a><p> + Additionally, there are the helper functions for setting the variable value + by name; they try to add the variable with the corresponding type, if it + does not exist, and to set the value. If the variable with the same name + but with different type is already present, they return <code class="computeroutput"><span class="keyword">false</span></code>; + they also return <code class="computeroutput"><span class="keyword">false</span></code> on allocation + failure. Note that these functions do not perform any type conversions. + </p> +<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xpath_variable_set</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">name</span><span class="special">,</span> <span class="keyword">bool</span> <span class="identifier">value</span><span class="special">);</span> +<span class="keyword">bool</span> <span class="identifier">xpath_variable_set</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">name</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">value</span><span class="special">);</span> +<span class="keyword">bool</span> <span class="identifier">xpath_variable_set</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">name</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">value</span><span class="special">);</span> +<span class="keyword">bool</span> <span class="identifier">xpath_variable_set</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">name</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">xpath_node_set</span><span class="special">&</span> <span class="identifier">value</span><span class="special">);</span> +</pre> +<p> + The variable values are copied to the internal variable storage, so you can + modify or destroy them after the functions return. + </p> +<a name="xpath_variable"></a><p> + If setting variables by name is not efficient enough, or if you have to inspect + variable information or get variable values, you can use variable handles. + A variable corresponds to the <code class="computeroutput"><span class="identifier">xpath_variable</span></code> + type, and a variable handle is simply a pointer to <code class="computeroutput"><span class="identifier">xpath_variable</span></code>. + </p> +<a name="xpath_variable::type"></a><a name="xpath_variable::name"></a><p> + In order to get variable information, you can use one of the following functions: + </p> +<pre class="programlisting"><span class="keyword">const</span> <span class="identifier">char_t</span><span class="special">*</span> <span class="identifier">xpath_variable</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="identifier">xpath_value_type</span> <span class="identifier">xpath_variable</span><span class="special">::</span><span class="identifier">type</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<p> + Note that each variable has a distinct type which is specified upon variable + creation and can not be changed later. + </p> +<a name="xpath_variable::get_boolean"></a><a name="xpath_variable::get_number"></a><a name="xpath_variable::get_string"></a><a name="xpath_variable::get_node_set"></a><p> + In order to get variable value, you should use one of the following functions, + depending on the variable type: + </p> +<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xpath_variable</span><span class="special">::</span><span class="identifier">get_boolean</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="keyword">double</span> <span class="identifier">xpath_variable</span><span class="special">::</span><span class="identifier">get_number</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">xpath_variable</span><span class="special">::</span><span class="identifier">get_string</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="keyword">const</span> <span class="identifier">xpath_node_set</span><span class="special">&</span> <span class="identifier">xpath_variable</span><span class="special">::</span><span class="identifier">get_node_set</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<p> + These functions return the value of the variable. Note that no type conversions + are performed; if the type mismatch occurs, a dummy value is returned (<code class="computeroutput"><span class="keyword">false</span></code> for booleans, <code class="computeroutput"><span class="identifier">NaN</span></code> + for numbers, empty string for strings and empty set for node sets). + </p> +<a name="xpath_variable::set"></a><p> + In order to set variable value, you should use one of the following functions, + depending on the variable type: + </p> +<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">xpath_variable</span><span class="special">::</span><span class="identifier">set</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">value</span><span class="special">);</span> +<span class="keyword">bool</span> <span class="identifier">xpath_variable</span><span class="special">::</span><span class="identifier">set</span><span class="special">(</span><span class="keyword">double</span> <span class="identifier">value</span><span class="special">);</span> +<span class="keyword">bool</span> <span class="identifier">xpath_variable</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">value</span><span class="special">);</span> +<span class="keyword">bool</span> <span class="identifier">xpath_variable</span><span class="special">::</span><span class="identifier">set</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">xpath_node_set</span><span class="special">&</span> <span class="identifier">value</span><span class="special">);</span> +</pre> +<p> + These function modify the variable value. Note that no type conversions are + performed; if the type mismatch occurs, the functions return <code class="computeroutput"><span class="keyword">false</span></code>; they also return <code class="computeroutput"><span class="keyword">false</span></code> + on allocation failure. The variable values are copied to the internal variable + storage, so you can modify or destroy them after the functions return. + </p> +<p> + This is an example of using variables in XPath queries (<a href="../samples/xpath_variables.cpp" target="_top">samples/xpath_variables.cpp</a>): + </p> +<p> + +</p> +<pre class="programlisting"><span class="comment">// Select nodes via compiled query +</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_variable_set</span> <span class="identifier">vars</span><span class="special">;</span> +<span class="identifier">vars</span><span class="special">.</span><span class="identifier">add</span><span class="special">(</span><span class="string">"remote"</span><span class="special">,</span> <span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_type_boolean</span><span class="special">);</span> + +<span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_query</span> <span class="identifier">query_remote_tools</span><span class="special">(</span><span class="string">"/Profile/Tools/Tool[@AllowRemote = string($remote)]"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">vars</span><span class="special">);</span> + +<span class="identifier">vars</span><span class="special">.</span><span class="identifier">set</span><span class="special">(</span><span class="string">"remote"</span><span class="special">,</span> <span class="keyword">true</span><span class="special">);</span> +<span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_node_set</span> <span class="identifier">tools_remote</span> <span class="special">=</span> <span class="identifier">query_remote_tools</span><span class="special">.</span><span class="identifier">evaluate_node_set</span><span class="special">(</span><span class="identifier">doc</span><span class="special">);</span> + +<span class="identifier">vars</span><span class="special">.</span><span class="identifier">set</span><span class="special">(</span><span class="string">"remote"</span><span class="special">,</span> <span class="keyword">false</span><span class="special">);</span> +<span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_node_set</span> <span class="identifier">tools_local</span> <span class="special">=</span> <span class="identifier">query_remote_tools</span><span class="special">.</span><span class="identifier">evaluate_node_set</span><span class="special">(</span><span class="identifier">doc</span><span class="special">);</span> + +<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Remote tool: "</span><span class="special">;</span> +<span class="identifier">tools_remote</span><span class="special">[</span><span class="number">2</span><span class="special">].</span><span class="identifier">node</span><span class="special">().</span><span class="identifier">print</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">);</span> + +<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Local tool: "</span><span class="special">;</span> +<span class="identifier">tools_local</span><span class="special">[</span><span class="number">0</span><span class="special">].</span><span class="identifier">node</span><span class="special">().</span><span class="identifier">print</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">);</span> + +<span class="comment">// You can pass the context directly to select_nodes/select_single_node +</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xpath_node_set</span> <span class="identifier">tools_local_imm</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">select_nodes</span><span class="special">(</span><span class="string">"/Profile/Tools/Tool[@AllowRemote = string($remote)]"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">vars</span><span class="special">);</span> + +<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Local tool imm: "</span><span class="special">;</span> +<span class="identifier">tools_local_imm</span><span class="special">[</span><span class="number">0</span><span class="special">].</span><span class="identifier">node</span><span class="special">().</span><span class="identifier">print</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">);</span> +</pre> +<p> + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> <a name="manual.xpath.errors"></a><a class="link" href="xpath.html#manual.xpath.errors" title="Error handling"> Error handling</a> </h3></div></div></div> -<a name="xpath_exception"></a><a name="xpath_exception::what"></a><p> - As of version 0.9, all XPath errors result in thrown exceptions. The errors - can arise during expression compilation or node set evaluation. In both cases, - an <code class="computeroutput"><span class="identifier">xpath_exception</span></code> object - is thrown. This is an exception object that implements <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span></code> - interface, and thus has a single function <code class="computeroutput"><span class="identifier">what</span><span class="special">()</span></code>: +<p> + There are two different mechanisms for error handling in XPath implementation; + the mechanism used depends on whether exception support is disabled (this + is controlled with <a class="link" href="install.html#PUGIXML_NO_EXCEPTIONS">PUGIXML_NO_EXCEPTIONS</a> + define). + </p> +<a name="xpath_exception"></a><a name="xpath_exception::result"></a><a name="xpath_exception::what"></a><p> + By default, XPath functions throw <code class="computeroutput"><span class="identifier">xpath_exception</span></code> + object in case of errors; additionally, in the event any memory allocation + fails, an <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bad_alloc</span></code> exception is thrown. Also <code class="computeroutput"><span class="identifier">xpath_exception</span></code> is thrown if the query + is evaluated to a node set, but the return type is not node set. If the query + constructor succeeds (i.e. no exception is thrown), the query object is valid. + Otherwise you can get the error details via one of the following functions: </p> <pre class="programlisting"><span class="keyword">virtual</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">xpath_exception</span><span class="special">::</span><span class="identifier">what</span><span class="special">()</span> <span class="keyword">const</span> <span class="keyword">throw</span><span class="special">();</span> +<span class="keyword">const</span> <span class="identifier">xpath_parse_result</span><span class="special">&</span> <span class="identifier">xpath_exception</span><span class="special">::</span><span class="identifier">result</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<a name="xpath_query::unspecified_bool_type"></a><a name="xpath_query::result"></a><p> + If exceptions are disabled, then in the event of parsing failure the query + is initialized to invalid state; you can test if the query object is valid + by using it in a boolean expression: <code class="computeroutput"><span class="keyword">if</span> + <span class="special">(</span><span class="identifier">query</span><span class="special">)</span> <span class="special">{</span> <span class="special">...</span> + <span class="special">}</span></code>. Additionally, you can get parsing + result via the result() accessor: + </p> +<pre class="programlisting"><span class="keyword">const</span> <span class="identifier">xpath_parse_result</span><span class="special">&</span> <span class="identifier">xpath_query</span><span class="special">::</span><span class="identifier">result</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> </pre> <p> - This function returns the error message. Currently it is impossible to get - the exact place where query compilation failed. This functionality, along - with optional error handling without exceptions, will be available in version - 1.0. + Without exceptions, evaluating invalid query results in <code class="computeroutput"><span class="keyword">false</span></code>, + empty string, NaN or an empty node set, depending on the type; evaluating + a query as a node set results in an empty node set if the return type is + not node set. + </p> +<a name="xpath_parse_result"></a><p> + The information about parsing result is returned via <code class="computeroutput"><span class="identifier">xpath_parse_result</span></code> + object. It contains parsing status and the offset of last successfully parsed + character from the beginning of the source stream: + </p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">xpath_parse_result</span> +<span class="special">{</span> + <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">error</span><span class="special">;</span> + <span class="identifier">ptrdiff_t</span> <span class="identifier">offset</span><span class="special">;</span> + + <span class="keyword">operator</span> <span class="keyword">bool</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">description</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="special">};</span> +</pre> +<a name="xpath_parse_result::error"></a><p> + Parsing result is represented as the error message; it is either a null pointer, + in case there is no error, or the error message in the form of ASCII zero-terminated + string. + </p> +<a name="xpath_parse_result::description"></a><p> + <code class="computeroutput"><span class="identifier">description</span><span class="special">()</span></code> + member function can be used to get the error message; it never returns the + null pointer, so you can safely use description() even if query parsing succeeded. + </p> +<a name="xpath_parse_result::offset"></a><p> + In addition to the error message, parsing result has an <code class="computeroutput"><span class="identifier">offset</span></code> + member, which contains the offset of last successfully parsed character. + This offset is in units of <a class="link" href="dom.html#char_t">pugi::char_t</a> (bytes + for character mode, wide characters for wide character mode). + </p> +<a name="xpath_parse_result::bool"></a><p> + Parsing result object can be implicitly converted to <code class="computeroutput"><span class="keyword">bool</span></code> + like this: <code class="computeroutput"><span class="keyword">if</span> <span class="special">(</span><span class="identifier">result</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>. </p> <p> This is an example of XPath error handling (<a href="../samples/xpath_error.cpp" target="_top">samples/xpath_error.cpp</a>): @@ -440,7 +693,7 @@ but instead has three. </li> <li class="listitem"> - Since document can't have a document type declaration, <code class="computeroutput"><span class="identifier">id</span><span class="special">()</span></code> + Since the document type declaration is not used for parsing, <code class="computeroutput"><span class="identifier">id</span><span class="special">()</span></code> function always returns an empty node set. </li> <li class="listitem"> @@ -459,13 +712,7 @@ value, depending on the library configuration; this means that some string functions are not fully Unicode-aware. This affects <code class="computeroutput"><span class="identifier">substring</span><span class="special">()</span></code>, <code class="computeroutput"><span class="identifier">string</span><span class="special">-</span><span class="identifier">length</span><span class="special">()</span></code> and <code class="computeroutput"><span class="identifier">translate</span><span class="special">()</span></code> functions. </li> -<li class="listitem"> - Variable references are not supported. - </li> </ul></div> -<p> - Some of these incompatibilities will be fixed in version 1.0. - </p> </div> </div> <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> @@ -477,7 +724,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: diff --git a/docs/quickstart.html b/docs/quickstart.html index 966dfc3..d39e552 100644 --- a/docs/quickstart.html +++ b/docs/quickstart.html @@ -1,16 +1,16 @@ <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> -<title>pugixml 0.9</title> +<title>pugixml 1.0</title> <link rel="stylesheet" href="pugixml.css" type="text/css"> <meta name="generator" content="DocBook XSL Stylesheets V1.75.2"> -<link rel="home" href="quickstart.html" title="pugixml 0.9"> +<link rel="home" href="quickstart.html" title="pugixml 1.0"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> <div class="article"> <div class="section"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="quickstart.main"></a><a class="link" href="quickstart.html#quickstart.main" title="pugixml 0.9 quick start guide"> pugixml 0.9 quick start guide</a> +<a name="quickstart.main"></a><a class="link" href="quickstart.html#quickstart.main" title="pugixml 1.0 quick start guide"> pugixml 1.0 quick start guide</a> </h2></div></div></div> <div class="toc"><dl> <dt><span class="section"><a href="quickstart.html#quickstart.main.introduction"> Introduction</a></span></dt> @@ -28,16 +28,17 @@ <a name="quickstart.main.introduction"></a><a class="link" href="quickstart.html#quickstart.main.introduction" title="Introduction"> Introduction</a> </h3></div></div></div> <p> - pugixml is a light-weight C++ XML processing library. It consists of a DOM-like - interface with rich traversal/modification capabilities, an extremely fast - XML parser which constructs the DOM tree from an XML file/buffer, and an - XPath 1.0 implementation for complex data-driven tree queries. Full Unicode - support is also available, with Unicode interface variants and conversions - between different Unicode encodings (which happen automatically during parsing/saving). - The library is extremely portable and easy to integrate and use. pugixml - is developed and maintained since 2006 and has many users. All code is distributed - under the MIT license, making it completely free to use in both open-source - and proprietary applications. + <a href="http://pugixml.org/" target="_top">pugixml</a> is a light-weight C++ XML + processing library. It consists of a DOM-like interface with rich traversal/modification + capabilities, an extremely fast XML parser which constructs the DOM tree + from an XML file/buffer, and an XPath 1.0 implementation for complex data-driven + tree queries. Full Unicode support is also available, with Unicode interface + variants and conversions between different Unicode encodings (which happen + automatically during parsing/saving). The library is extremely portable and + easy to integrate and use. pugixml is developed and maintained since 2006 + and has many users. All code is distributed under the <a class="link" href="quickstart.html#quickstart.main.license" title="License">MIT + license</a>, making it completely free to use in both open-source and + proprietary applications. </p> <p> pugixml enables very fast, convenient and memory-efficient XML document processing. @@ -74,19 +75,21 @@ pugixml is distributed in source form. You can download a source distribution via one of the following links: </p> -<pre class="programlisting"><a href="http://pugixml.googlecode.com/files/pugixml-0.9.zip" target="_top">http://pugixml.googlecode.com/files/pugixml-0.9.zip</a> -<a href="http://pugixml.googlecode.com/files/pugixml-0.9.tar.gz" target="_top">http://pugixml.googlecode.com/files/pugixml-0.9.tar.gz</a> +<pre class="programlisting"><a href="http://pugixml.googlecode.com/files/pugixml-1.0.zip" target="_top">http://pugixml.googlecode.com/files/pugixml-1.0.zip</a> +<a href="http://pugixml.googlecode.com/files/pugixml-1.0.tar.gz" target="_top">http://pugixml.googlecode.com/files/pugixml-1.0.tar.gz</a> </pre> <p> The distribution contains library source, documentation (the guide you're reading now and the manual) and some code examples. After downloading the distribution, install pugixml by extracting all files from the compressed - archive. + archive. The files have different line endings depending on the archive format + - <code class="filename">.zip</code> archive has Windows line endings, <code class="filename">.tar.gz</code> archive has Unix line endings. + Otherwise the files in both archives are identical. </p> <p> - The complete pugixml source consists of four files - two source files, <code class="filename">pugixml.cpp</code> and - <code class="filename">pugixpath.cpp</code>, and two header files, <code class="filename">pugixml.hpp</code> and <code class="filename">pugiconfig.hpp</code>. <code class="filename">pugixml.hpp</code> is - the primary header which you need to include in order to use pugixml classes/functions. + The complete pugixml source consists of three files - one source file, <code class="filename">pugixml.cpp</code>, + and two header files, <code class="filename">pugixml.hpp</code> and <code class="filename">pugiconfig.hpp</code>. <code class="filename">pugixml.hpp</code> is the primary + header which you need to include in order to use pugixml classes/functions. The rest of this guide assumes that <code class="filename">pugixml.hpp</code> is either in the current directory or in one of include directories of your projects, so that <code class="computeroutput"><span class="preprocessor">#include</span> <span class="string">"pugixml.hpp"</span></code> can find the header; however you can also use relative path (i.e. <code class="computeroutput"><span class="preprocessor">#include</span> <span class="string">"../libs/pugixml/src/pugixml.hpp"</span></code>) @@ -94,13 +97,14 @@ <span class="special"><</span><span class="identifier">xml</span><span class="special">/</span><span class="identifier">thirdparty</span><span class="special">/</span><span class="identifier">pugixml</span><span class="special">/</span><span class="identifier">src</span><span class="special">/</span><span class="identifier">pugixml</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>). </p> <p> - The easiest way to build pugixml is to compile two source files, <code class="filename">pugixml.cpp</code> and - <code class="filename">pugixpath.cpp</code>, along with the existing library/executable. This process depends - on the method of building your application; for example, if you're using - Microsoft Visual Studio<sup>[<a name="trademarks" href="#ftn.trademarks" class="footnote">1</a>]</sup>, Apple Xcode, Code::Blocks or any other IDE, just add - <code class="filename">pugixml.cpp</code> and <code class="filename">pugixpath.cpp</code> to one of your projects. There are other building - methods available, including building pugixml as a standalone static/shared - library; read the manual for further information. + The easiest way to build pugixml is to compile the source file, <code class="filename">pugixml.cpp</code>, + along with the existing library/executable. This process depends on the method + of building your application; for example, if you're using Microsoft Visual + Studio<sup>[<a name="trademarks" href="#ftn.trademarks" class="footnote">1</a>]</sup>, + Apple Xcode, Code::Blocks or any other IDE, just add <code class="filename">pugixml.cpp</code> to one of + your projects. There are other building methods available, including building + pugixml as a standalone static/shared library; <a href="manual/install.html#manual.install.building" target="_top">read + the manual</a> for further information. </p> </div> <div class="section"> @@ -176,11 +180,10 @@ <code class="computeroutput"><span class="identifier">xml_document</span></code> is the owner of the entire document structure; destroying the document destroys the whole tree. The interface of <code class="computeroutput"><span class="identifier">xml_document</span></code> - consists of loading functions, saving functions and the 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 only used to simplify usage. + consists of loading functions, saving functions and the entire interface + of <code class="computeroutput"><span class="identifier">xml_node</span></code>, which allows + for document inspection and/or modification. Note that while <code class="computeroutput"><span class="identifier">xml_document</span></code> is a sub-class of <code class="computeroutput"><span class="identifier">xml_node</span></code>, <code class="computeroutput"><span class="identifier">xml_node</span></code> + is not a polymorphic type; the inheritance is present only to simplify usage. </p> <p> <code class="computeroutput"><span class="identifier">xml_node</span></code> is the handle to @@ -208,8 +211,8 @@ <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, there is a special null attribute - value, which propagates to function results. + handles pointing to the same underlying object and there is a special null + attribute value, which propagates to function results. </p> <p> There are two choices of interface and internal representation when configuring @@ -217,8 +220,8 @@ UTF-16/32 (also called wchar_t) one. The choice is controlled via <code class="computeroutput"><span class="identifier">PUGIXML_WCHAR_MODE</span></code> define; you can set it via <code class="filename">pugiconfig.hpp</code> or via preprocessor options. All tree functions that work with strings work with either C-style null terminated strings or STL - strings of the selected character type. Read the manual for additional information - on Unicode interface. + strings of the selected character type. <a href="manual/dom.html#manual.dom.unicode" target="_top">Read + the manual</a> for additional information on Unicode interface. </p> </div> <div class="section"> @@ -601,13 +604,13 @@ <p> </p> <p> - Nodes and attributes do not exist outside of document tree, so you can't - create them without adding them to some document. A node or attribute can - be created at the end of node/attribute list or before/after some other node. - All insertion functions return the handle to newly created object on success, - and null handle on failure. Even if the operation fails (for example, if - you're trying to add a child node to PCDATA node), the document remains in - consistent state, but the requested node/attribute is not added. + Nodes and attributes do not exist without a document tree, so you can't create + them without adding them to some document. A node or attribute can be created + at the end of node/attribute list or before/after some other node. All insertion + functions return the handle to newly created object on success, and null + handle on failure. Even if the operation fails (for example, if you're trying + to add a child node to PCDATA node), the document remains in consistent state, + but the requested node/attribute is not added. </p> <div class="caution"><table border="0" summary="Caution"> <tr> @@ -628,17 +631,14 @@ </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="identifier">node</span><span class="special">.</span><span class="identifier">set_name</span><span class="special">(</span><span class="string">"node"</span><span class="special">);</span> +</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="identifier">descr</span><span class="special">.</span><span class="identifier">set_name</span><span class="special">(</span><span class="string">"description"</span><span class="special">);</span> +</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="identifier">pugi</span><span class="special">::</span><span class="identifier">node_element</span><span class="special">,</span> <span class="identifier">descr</span><span class="special">);</span> -<span class="identifier">param</span><span class="special">.</span><span class="identifier">set_name</span><span class="special">(</span><span class="string">"param"</span><span class="special">);</span> +</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> @@ -647,7 +647,7 @@ </pre> <p> </p> -<a name="xml_node::remove_attribute"></a><a name="xml_node::remove_child"></a><p> +<p> If you do not want your document to contain some node or attribute, you can remove it with <code class="computeroutput"><span class="identifier">remove_attribute</span></code> and <code class="computeroutput"><span class="identifier">remove_child</span></code> functions. @@ -693,12 +693,12 @@ encoding conversions. </p> <p> - The node/attribute data is written to the destination properly formatted + Before writing to the destination the node/attribute data is properly formatted according to the node type; all special XML symbols, such as < and &, are properly escaped. In order to guard against forgotten node/attribute names, empty node/attribute names are printed as <code class="computeroutput"><span class="string">":anonymous"</span></code>. - For proper output, make sure all node and attribute names are set to meaningful - values. + For well-formed output, make sure all node and attribute names are set to + meaningful values. </p> <p> If you want to save the whole document to a file, you can use the <code class="computeroutput"><span class="identifier">save_file</span></code> function, which returns <code class="computeroutput"><span class="keyword">true</span></code> on success. This is a simple example @@ -713,11 +713,11 @@ <p> </p> <p> - For additional interoperability pugixml provides functions for saving document - to any object which implements C++ std::ostream interface. This allows you - to save documents to any standard C++ stream (i.e. file stream) or any third-party - compliant implementation (i.e. Boost Iostreams). Most notably, this allows - for easy debug output, since you can use <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span></code> + To enhance interoperability pugixml provides functions for saving document + to any object which implements C++ <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span></code> + interface. This allows you to save documents to any standard C++ stream (i.e. + file stream) or any third-party compliant implementation (i.e. Boost Iostreams). + Most notably, this allows for easy debug output, since you can use <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span></code> stream as saving target. There are two functions, one works with narrow character streams, another handles wide character ones. </p> @@ -763,11 +763,12 @@ <p> </p> <p> - While the previously described functions saved the whole document to the - destination, it is easy to save a single subtree. Instead of calling <code class="computeroutput"><span class="identifier">xml_document</span><span class="special">::</span><span class="identifier">save</span></code>, just call <code class="computeroutput"><span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">print</span></code> - function on the target node. You can save node contents to C++ IOstream object - or custom writer in this way. Saving a subtree slightly differs from saving - the whole document; read the manual for more information. + While the previously described functions save the whole document to the destination, + it is easy to save a single subtree. Instead of calling <code class="computeroutput"><span class="identifier">xml_document</span><span class="special">::</span><span class="identifier">save</span></code>, + just call <code class="computeroutput"><span class="identifier">xml_node</span><span class="special">::</span><span class="identifier">print</span></code> function on the target node. You + can save node contents to C++ IOstream object or custom writer in this way. + Saving a subtree slightly differs from saving the whole document; <a href="manual/saving.html#manual.saving.subtree" target="_top">read the manual</a> for + more information. </p> </div> <div class="section"> @@ -819,16 +820,25 @@ IN THE SOFTWARE. </p> </blockquote></div> +<p> + This means that you can freely use pugixml in your applications, both open-source + and proprietary. If you use pugixml in a product, it is sufficient to add + an acknowledgment like this to the product distribution: + </p> +<div class="blockquote"><blockquote class="blockquote"><p> + This software is based on pugixml library (http://pugixml.org).<br> +pugixml + is Copyright (C) 2006-2010 Arseny Kapoulkine. + </p></blockquote></div> </div> </div> <div class="footnotes"> <br><hr width="100" align="left"> -<div class="footnote"><p><sup>[<a name="ftn.trademarks" href="#trademarks" class="para">1</a>] </sup>All trademarks used are properties of their - respective owners.</p></div> +<div class="footnote"><p><sup>[<a name="ftn.trademarks" href="#trademarks" class="para">1</a>] </sup>All trademarks used are properties of their respective owners.</p></div> </div> </div> <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> -<td align="left"><p><small>Last revised: July 15, 2010 at 17:02:03 GMT</small></p></td> +<td align="left"><p><small>Last revised: October 31, 2010 at 07:44:52 GMT</small></p></td> <td align="right"><div class="copyright-footer"></div></td> </tr></table> </body> |