tsc_XmlReader

Added in version 1.90

This class is used to read and parse XML from a file or a string.  One instance of tsc_XmlReader may be used to parse multiple objects, repeatedly but not concurrently.

tsc_XmlReader is designed for simple XML fragments or documents.  In particular, the following XML features are not supported:

The reader can handle all usual file formats including UTF-8, UTF-16 with either endian, with or without BOM markers, and with any sane form of line ending.

Entity escapes are supported - the standard five (< > ' " &) as well as &#xhexdigits; and &#decimaldigits; where hexdigits and decimaldigits are a sequence of digits being a Unicode codepoint, a 24-bit unencoded number.  For instance the heart "♥" character is unicode point 0x2665 and would be encoded into an XML document as ♥.  This will be converted to the correct UTF-8 sequence when the element is accessed.

Starting with version 2.50, CDATA elements are interpreted literally and become part of the string value of the element in which they appear.  Note: tsc_XmlWriter will not recreate the CDATA element, it will simply write the data as the value of the enclosing element, with the appropriate escape sequences.

Public methods

tsc_XmlReader ();
Construct an XML reader.

tsc_XmlReader (const tsc_XmlReader&);
The copy constructor makes a reference to the same object.

void TrimElementContent (bool trim);
Controls the trimming of whitespace from the front and back of the text content of elements. Any interior whitespace is unaffected.

For example, the XML "<a>\r\n\tJoe and Jane <innertag /> Smith </a>" will return a StringValue for element "a" of "Joe and JaneSmith".

Whitespace is defined as spaces, tabs, and line delimiters (\n, \r, vertical tab, etc).

The default is ON (whitespace is trimmed). To change this, call with a trim parameter of false.

This parameter applies to the entire document and must be set correctly before calling a Read method.

tsc_XmlElement ReadFile (const char* filename);
Read and parse XML from the given file. The root element is returned, which has an Exists() of false if the operation failed.

tsc_XmlElement ReadString (const char* xml);
Parses the XML from the supplied string. The root element is returned, which has an Exists() of false if the operation failed.

x_Code LastError ();
Provides a generic error code for the last operation, or X_NULL if the operation was successful.   

The LastErrorText() method provides much more information about the error.

The following error codes may occur:
 X_FileDoesNotExist : The file path supplied to ReadFile was not found.
 X_FileError : The file could not be read.  LastErrorText supplies a message which includes an error code.
 X_InvalidSyntax : The XML content did not live up to expectations. This includes both syntax and semantic errors.

tsc_String LastErrorText ();
Provides a comprehensive English description of the last error.  For XML errors, the line number and character position are included in the message.

tsc_XmlReader& operator= (const tsc_XmlReader& from);
Assignment makes a reference to the same tsc_XmlReader object.