diff options
| author | arseny.kapoulkine <arseny.kapoulkine@99668b35-9821-0410-8761-19e4c4f06640> | 2010-10-31 07:45:27 +0000 |
|---|---|---|
| committer | arseny.kapoulkine <arseny.kapoulkine@99668b35-9821-0410-8761-19e4c4f06640> | 2010-10-31 07:45:27 +0000 |
| commit | 186e491d1e7f7bddc04d5169084b224a648aa457 (patch) | |
| tree | 4ac670640a3f30be2565c964b00798769e10c04b /docs/manual/saving.html | |
| parent | 07043107c78192f279c3ab0fbb3d4d4cb1b026a4 (diff) | |
docs: Regenerated HTML documentation
git-svn-id: http://pugixml.googlecode.com/svn/trunk@790 99668b35-9821-0410-8761-19e4c4f06640
Diffstat (limited to 'docs/manual/saving.html')
| -rw-r--r-- | docs/manual/saving.html | 111 |
1 files changed, 51 insertions, 60 deletions
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: |