Saving document

- 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 ":anonymous". - 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 ":anonymous". + For well-formed output, make sure all node and attribute names are set to meaningful values.

+ CDATA sections with values that contain "]]>" + are split into several sections as follows: section with value "pre]]>post" is written as <![CDATA[pre]]]]><![CDATA[>post]]>. + 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. +

Saving document to a file

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

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

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

+ File path is passed to the system file opening function as is in case of + the first function (which accepts const + char* path); 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.

save_file opens the target @@ -96,19 +100,6 @@ handle as the only constructor argument and then calling save; see Saving document via writer interface for writer interface details.

- - - - - -

	Note
	- 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. -

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

@@ -126,11 +117,11 @@ Saving document to C++ IOstreams

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

write function is called with relatively large blocks (size is usually several kilobytes, except for - the first block with BOM, which is output only if format_write_bom + the first block with BOM, which is output only if format_write_bom is set, and last block, which may be small), so there is often no need for additional buffering in the implementation.

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