From 2094a4fd3da85c1972f215cb5977f6157590ff79 Mon Sep 17 00:00:00 2001 From: Arseny Kapoulkine Date: Fri, 28 Feb 2014 06:01:16 +0000 Subject: docs: Regenerate HTML documentation git-svn-id: https://pugixml.googlecode.com/svn/trunk@993 99668b35-9821-0410-8761-19e4c4f06640 --- docs/manual/saving.html | 226 ++++++++++++++++++++++++------------------------ 1 file changed, 111 insertions(+), 115 deletions(-) (limited to 'docs/manual/saving.html') diff --git a/docs/manual/saving.html b/docs/manual/saving.html index d0b2e02..2c05a7b 100644 --- a/docs/manual/saving.html +++ b/docs/manual/saving.html @@ -3,16 +3,16 @@ Saving document - - - + + +
-pugixml 1.2 manual | +pugixml 1.4 manual | Overview | Installation | Document: @@ -28,16 +28,16 @@
-
-
Saving document to a file
-
Saving document to C++ IOstreams
-
Saving document via writer interface
-
Saving a single subtree
-
Output options
-
Encodings
-
Customizing document declaration
+
+
Saving document to a file
+
Saving document to C++ IOstreams
+
Saving document via writer interface
+
Saving a single subtree
+
Output options
+
Encodings
+
Customizing document declaration

Often after creating a new document or loading the existing one and processing @@ -46,8 +46,8 @@ include debug printing, serialization via network or other text-oriented medium, etc. pugixml provides several functions to output any subtree of the document to a file, stream or another generic transport interface; these functions allow - to customize the output format (see Output options), and also perform - necessary encoding conversions (see Encodings). This section documents + to customize the output format (see Output options), and also perform + necessary encoding conversions (see Encodings). This section documents the relevant functionality.

@@ -68,19 +68,20 @@

-

- If you want to save the whole document to a file, you can use one of the - following functions: +

+ If + you want to save the whole document to a file, you can use one of the following + functions: 

bool xml_document::save_file(const char* path, const char_t* indent = "\t", unsigned int flags = format_default, xml_encoding encoding = encoding_auto) const;
 bool xml_document::save_file(const wchar_t* path, const char_t* indent = "\t", unsigned int flags = format_default, xml_encoding encoding = encoding_auto) const;

These functions accept file path as its first argument, and also three optional - arguments, which specify indentation and other output options (see Output options) - and output data encoding (see Encodings). The path has the target + arguments, which specify indentation and other output options (see Output options) + and output data encoding (see Encodings). The path has the target operating system format, so it can be a relative or absolute one, it should have the delimiters of the target system, it should have the exact case if the target file system is case-sensitive, etc. @@ -92,38 +93,39 @@ 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.

-

- save_file opens the target - file for writing, outputs the requested header (by default a document declaration - is output, unless the document already has one), and then saves the document - contents. If the file could not be opened, the function returns false. Calling save_file - is equivalent to creating an xml_writer_file - object with FILE* +

+ save_file + opens the target file for writing, outputs the requested header (by default + a document declaration is output, unless the document already has one), and + then saves the document contents. If the file could not be opened, the function + returns false. Calling save_file is equivalent to creating an + xml_writer_file object with + FILE* handle as the only constructor argument and then calling save; - see Saving document via writer interface for writer interface details. + see Saving document via writer interface for writer interface details.

This is a simple example of saving XML document to file (samples/save_file.cpp):

-

-
// save document to file
-std::cout << "Saving result: " << doc.save_file("save_file_output.xml") << std::endl;
+
// save document to file
+std::cout << "Saving result: " << doc.save_file("save_file_output.xml") << std::endl;
-

- To enhance 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 std::cout +

+ To enhance 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 std::cout stream as saving target. There are two functions, one works with narrow character streams, another handles wide character ones:

@@ -143,20 +145,19 @@ you with the ability to save documents to non-Unicode encodings, i.e. you can save Shift-JIS encoded data if you set the correct locale.

-

- Calling save with stream - target is equivalent to creating an xml_writer_stream - object with stream as the only constructor argument and then calling save; see Saving document via writer interface for writer +

+ Calling save + with stream target is equivalent to creating an xml_writer_stream + object with stream as the only constructor argument and then calling save; see Saving document via writer interface for writer interface details.

This is a simple example of saving XML document to standard output (samples/save_stream.cpp):

-

-
// save document to standard output
-std::cout << "Document:\n";
+
// save document to standard output
+std::cout << "Document:\n";
 doc.save(std::cout);
 

 

@@ -164,10 +165,11 @@
-

- All of the above saving functions are implemented in terms of writer interface. +

+ All + of the above saving functions are implemented in terms of writer interface. This is a simple interface with a single function, which is called several times during output process with chunks of document data as input:

@@ -203,7 +205,6 @@ read the sample code for more complex examples:

- 

struct xml_string_writer: pugi::xml_writer
 {
@@ -220,10 +221,11 @@
-

- While the previously described functions save the whole document to the destination, +

+ 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: 

void xml_node::print(std::ostream& os, const char_t* indent = "\t", unsigned int flags = format_default, xml_encoding encoding = encoding_auto, unsigned int depth = 0) const;
@@ -246,22 +248,21 @@
         illustrates the difference:
       

 

-        
 

-
// get a test document
-pugi::xml_document doc;
+
// get a test document
+pugi::xml_document doc;
 doc.load("<foo bar='baz'><call>hey</call></foo>");
 
-// print document to standard output (prints <?xml version="1.0"?><foo bar="baz"><call>hey</call></foo>)
-doc.save(std::cout, "", pugi::format_raw);
+// print document to standard output (prints <?xml version="1.0"?><foo bar="baz"><call>hey</call></foo>)
+doc.save(std::cout, "", pugi::format_raw);
 std::cout << std::endl;
 
-// print document to standard output as a regular node (prints <foo bar="baz"><call>hey</call></foo>)
-doc.print(std::cout, "", pugi::format_raw);
+// print document to standard output as a regular node (prints <foo bar="baz"><call>hey</call></foo>)
+doc.print(std::cout, "", pugi::format_raw);
 std::cout << std::endl;
 
-// print a subtree to standard output (prints <call>hey</call>)
-doc.child("foo").child("call").print(std::cout, "", pugi::format_raw);
+// print a subtree to standard output (prints <call>hey</call>)
+doc.child("foo").child("call").print(std::cout, "", pugi::format_raw);
 std::cout << std::endl;
 

 

@@ -269,7 +270,7 @@

All saving functions accept the optional parameter flags. @@ -291,7 +292,7 @@

These flags control the resulting tree contents:

-
    +
    • format_indent determines if all nodes should be indented with the indentation string (this is an additional @@ -301,7 +302,6 @@ node's depth relative to the output subtree. This flag has no effect if format_raw is enabled. This flag is on by default.

      -
    • format_raw switches between formatted and @@ -312,24 +312,23 @@ with parse_ws_pcdata flag, to preserve the original document formatting as much as possible. This flag is off by default.

      -
    • format_no_escapes disables output - escaping for attribute values and PCDATA contents. If this flag is on, + escaping for attribute values and PCDATA contents. If this flag is off, special symbols (', &, <, >) and all non-printable characters (those with codepoint values less than 32) are converted to XML escape - sequences (i.e. &amp;) during output. If this flag is off, no text + sequences (i.e. &amp;) during output. If this flag is on, no text processing is performed; therefore, output XML can be malformed if output contents contains invalid symbols (i.e. having a stray < in the PCDATA - will make the output malformed). This flag is on + will make the output malformed). This flag is off by default.

    These flags control the additional output information:

    -
      +
      • format_no_declaration disables default node declaration output. By default, if the document is saved @@ -338,7 +337,6 @@ the document contents. Enabling this flag disables this declaration. This flag has no effect in xml_node::print functions: they never output the default declaration. This flag is off by default.

        -
      • format_write_bom enables Byte Order @@ -364,7 +362,7 @@

        Additionally, there is one predefined option mask:

        -
        • +
          • format_default is the default set of flags, i.e. it has all options set to their default values. It sets formatted output with indentation, without BOM and with default node declaration, @@ -374,44 +372,43 @@ This is an example that shows the outputs of different output options (samples/save_options.cpp):

            -

            -
            // get a test document
-pugi::xml_document doc;
+
            // get a test document
+pugi::xml_document doc;
 doc.load("<foo bar='baz'><call>hey</call></foo>");
 
-// default options; prints
-// <?xml version="1.0"?>
-// <foo bar="baz">
-//         <call>hey</call>
-// </foo>
-doc.save(std::cout);
+// default options; prints
+// <?xml version="1.0"?>
+// <foo bar="baz">
+//         <call>hey</call>
+// </foo>
+doc.save(std::cout);
 std::cout << std::endl;
 
-// default options with custom indentation string; prints
-// <?xml version="1.0"?>
-// <foo bar="baz">
-// --<call>hey</call>
-// </foo>
-doc.save(std::cout, "--");
+// default options with custom indentation string; prints
+// <?xml version="1.0"?>
+// <foo bar="baz">
+// --<call>hey</call>
+// </foo>
+doc.save(std::cout, "--");
 std::cout << std::endl;
 
-// default options without indentation; prints
-// <?xml version="1.0"?>
-// <foo bar="baz">
-// <call>hey</call>
-// </foo>
-doc.save(std::cout, "\t", pugi::format_default & ~pugi::format_indent); // can also pass "" instead of indentation string for the same effect
-std::cout << std::endl;
+// default options without indentation; prints
+// <?xml version="1.0"?>
+// <foo bar="baz">
+// <call>hey</call>
+// </foo>
+doc.save(std::cout, "\t", pugi::format_default & ~pugi::format_indent); // can also pass "" instead of indentation string for the same effect
+std::cout << std::endl;
 
-// raw output; prints
-// <?xml version="1.0"?><foo bar="baz"><call>hey</call></foo>
-doc.save(std::cout, "\t", pugi::format_raw);
+// raw output; prints
+// <?xml version="1.0"?><foo bar="baz"><call>hey</call></foo>
+doc.save(std::cout, "\t", pugi::format_raw);
 std::cout << std::endl << std::endl;
 
-// raw output without declaration; prints
-// <foo bar="baz"><call>hey</call></foo>
-doc.save(std::cout, "\t", pugi::format_raw | pugi::format_no_declaration);
+// raw output without declaration; prints
+// <foo bar="baz"><call>hey</call></foo>
+doc.save(std::cout, "\t", pugi::format_raw | pugi::format_no_declaration);
 std::cout << std::endl;
 
            
 
            
@@ -419,7 +416,7 @@

          pugixml supports all popular Unicode encodings (UTF-8, UTF-16 (big and little @@ -427,7 +424,7 @@ it's a strict subset of UTF-16) and handles all encoding conversions during output. The output encoding is set via the encoding parameter of saving functions, which is of type xml_encoding. - The possible values for the encoding are documented in Encodings; + The possible values for the encoding are documented in Encodings; the only flag that has a different meaning is encoding_auto.

          @@ -460,7 +457,7 @@

          When you are saving the document using xml_document::save() or xml_document::save_file(), a default XML document declaration is @@ -493,23 +490,22 @@ This is an example that shows how to create a custom declaration node (samples/save_declaration.cpp):

          -

          -
          // get a test document
-pugi::xml_document doc;
+
          // get a test document
+pugi::xml_document doc;
 doc.load("<foo bar='baz'><call>hey</call></foo>");
 
-// add a custom declaration node
-pugi::xml_node decl = doc.prepend_child(pugi::node_declaration);
+// add a custom declaration node
+pugi::xml_node decl = doc.prepend_child(pugi::node_declaration);
 decl.append_attribute("version") = "1.0";
 decl.append_attribute("encoding") = "UTF-8";
 decl.append_attribute("standalone") = "no";
 
-// <?xml version="1.0" encoding="UTF-8" standalone="no"?> 
-// <foo bar="baz">
-//         <call>hey</call>
-// </foo>
-doc.save(std::cout);
+// <?xml version="1.0" encoding="UTF-8" standalone="no"?> 
+// <foo bar="baz">
+//         <call>hey</call>
+// </foo>
+doc.save(std::cout);
 std::cout << std::endl;
 
          
 
          
@@ -518,7 +514,7 @@
          - @@ -526,7 +522,7 @@
          Copyright © 2012 Arseny Kapoulkine

          +

          Copyright © 2014 Arseny Kapoulkine

          Distributed under the MIT License

          -pugixml 1.2 manual | +pugixml 1.4 manual | Overview | Installation | Document: -- cgit v1.2.3