static bool CMarkup::WriteTextFile( MCD_CSTR szFileName, MCD_STR& strDoc, MCD_STR* pstrResult=NULL, int* pnFlags=NULL, MCD_STR* pstrEncoding=NULL );
WriteTextFile is a static function (with no knowledge of the data members of a CMarkup object) that writes a string to file, creating the file or replacing it if it exists, sometimes performing a text encoding conversion (see ANSI and Unicode files and C++ strings). WriteTextFile is the corresponding function to ReadTextFile.
There are 3 optional arguments: a result string, a flags integer, and an encoding string.
If the result string argument is supplied, WriteTextFile sets it to the result markup string upon return (see GetResult).
The optional flags argument is needed to write the file in UTF-16 or with a UTF-8 preamble. WriteTextFile will write the file with the BOM and encoding corresponding to the flag. If you are going to write the same file back to disk after modifying it, it is best to get the flags from ReadTextFile and keep them to pass them to WriteTextFile so the file is saved the same way it is loaded. For more on these flags, see UTF-8 Files and the Preamble and UTF-16 Files and the Byte Order Mark (BOM).
| Flag | Meaning |
|---|---|
MDF_UTF8PREAMBLE | include the UTF-8 preamble |
MDF_UTF16LEFILE | write to UTF-16LE with little endian BOM |
MDF_UTF16BEFILE | write to UTF-16BE with big endian BOM |
If you use the pstrEncoding argument with an encoding name it will override any encoding specified in the document text itself. If you pass an empty string, the automatically determined encoding name is returned in that string.
Update March 24, 2009: The pstrError argument has been renamed to pstrResult with CMarkup release 11.0. The string that this argument provides is now a markup result in the format of GetResult rather than just descriptive text as in GetError.
Update December 17, 2008: With CMarkup release 10.1, WriteTextFile and ReadTextFile have greatly expanded character conversion capabilities. WriteTextFile can create the file according to an ANSI or double-byte encoding specified in the XML declaration or HTML Content-Type meta tag (see GetDeclaredEncoding) of the markup document, or in the optional pstrEncoding argument of WriteTextFile. This release adds support for big endian and little endian UTF-16 files across Windows, OS X, Linux and other platforms. Also the file handling flags mentioned above are available in the Evaluation version of this release.