CMarkup ReadTextFile Method

static bool CMarkup::ReadTextFile(
  MCD_CSTR szFileName,
  MCD_STR& strDoc,
  MCD_STR* pstrResult=NULL,
  int* pnFlags=NULL,
  MCD_STR* pstrEncoding=NULL
  );

ReadTextFile is a static function (with no knowledge of the data members of a CMarkup object) that reads a file into a string, sometimes performing a text encoding conversion (see ANSI and Unicode files and C++ strings). The ReadTextFile function returns true if the text file is successfully loaded into the document string argument.

MCD_STR strDoc;
if ( CMarkup::ReadTextFile(MCD_T("file.xml"),strDoc) )
{
  // strDoc has been populated from file.xml
}

See also WriteTextFile.

The Load method of CMarkup can be inconvenient as described in When CMarkup Load Returns false when you need to know whether a failure to load is due to a file error, or a parser error. That's why you can do it in 2 separate steps: ReadTextFile and then SetDoc.

Optional arguments

There are 3 optional arguments: a result string, a flags integer, and an encoding string.

If the result string argument is supplied, ReadTextFile sets it to the result markup string upon return (see GetResult).

The optional flags argument does not change the way a file is read, it is only a way of discovering whether or not there was a BOM in the file. ReadTextFile will set the MDF_UTF16LEFILE, MDF_UTF16BEFILE or MDF_UTF8PREAMBLE flag if the corresponding BOM is encountered (BOMs are removed from the text). 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).

If you use the pstrEncoding argument with an encoding name it will override any encoding specified in the file itself. If you pass an empty string to pstrEncoding, the automatically determined encoding name is returned in that string.

This example uses all of the arguments:

CMarkup xml;
int nFlags = 0;
MCD_STR strDoc, strResult, strEncoding;
bool bSuccess = CMarkup::ReadTextFile("file.xml",strDoc,&strResult,&nFlags,&strEncoding);

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, ReadTextFile and WriteTextFile have greatly expanded character conversion capabilities. ReadTextFile can interpret 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 ReadTextFile. This release adds support for big endian and little endian UTF-16 files across Windows, OS X, Linux and other platforms. ReadTextFile now removes nulls when reading text files. Also the file handling flags mentioned above are available in the Evaluation version of this release.

Update September 27, 2008: With CMarkup release 10.0, ReadTextFile allocates an extra 1% for the document string so that modifications slightly increasing the document size do not require reallocations. See Memory limit workaround.