IO::XmlWriter class

A simple class that can be used to easily write XML files.

Public types

enum WriteEncoding { kWriteEncodingUnknown, kWriteEncodingUTF16 = 1, kWriteEncodingLatin1 = 2, kWriteEncodingASCII = 3, kWriteEncodingUTF8 = 4 }
Character encodings for XmlWriter.
enum LineEnd { kLineEndUnix, kLineEndWindows, kLineEndDefault = kLineEndWindows }
Defines.

Public static variables

static const size_t kIndentSpacesDefault
Default number of space chars per indent.

Constructors, destructors, conversion operators

XmlWriter(bool bFormatPretty = true, WriteEncoding writeEncoding = kWriteEncodingUnknown)

Public functions

void SetOutputStream(IO::IStream* pStream, bool bFormatPretty = true)
Set the destination stream for the XML - output will fail if this is unset.
auto WriteXmlHeader() -> bool virtual
Write the header at the beginning of the XML file.
auto BeginElement(const char16_t* pElementName) -> bool virtual
Begin a new element.
auto EndElement(const char16_t* pElementName) -> bool virtual
End the current element.
auto BeginProcessingInstruction(const char16_t* pInstructionName) -> bool virtual
Begin a new processing intruction.
auto EndProcessingInstruction() -> bool virtual
End the current processing instruction.
auto AppendAttribute(const char16_t* pAttrName, const char16_t* pAttrValue) -> bool virtual
Append a string attribute to the most recently written element or processing instruction, assuming that it has not been closed.
auto AppendAttributeF(const char16_t* pAttrName, const char16_t* pAttrValueFmt, ...) -> bool virtual
VPrintF version of AppendAttribute().
auto WriteCharData(const char16_t* pCharData) -> bool virtual
Write a string of character data.
auto WriteCDATA(const char16_t* pCharData) -> bool virtual
Write a string of unencoded character data.
auto WriteComment(const char16_t* pCommentText, bool bNewlineBefore = true) -> bool virtual
Write a comment tag, including the enclosing .
auto WriteName(const char16_t* pString) -> bool virtual
Writes a C-string as a piece of raw text.
auto WriteText(const char16_t* pString, size_t nLength) -> bool virtual
Write a piece of raw text.

Protected types

enum EState { kStateChars, kStateElement, kStateProcessingInstruction, kStateCDATA }

Protected variables

WriteEncoding mWriteEncoding
bool mbFormatPretty
The text encoding (e.g. UTF8) that we write.
bool mbSimpleElement
True if we format the output to have automatic indentation.
EState mnState
True if the current element has no child elements.
size_t mnIndentLevel
Used to tell what we are currently writing.
size_t mnIndentSpaces
Level of indentation. Starts at zero, increases by one for each indentation.
LineEnd mLineEnd
Number of space chars per indent. Total indent at any time = mnIndentLevel * mnIndentSpaces.
intrusive_ptr<IStream> mpStream
Defines whether we use Windows or standard indentation.

Function documentation

void IO::XmlWriter::SetOutputStream(IO::IStream* pStream, bool bFormatPretty = true)

Set the destination stream for the XML - output will fail if this is unset.

Parameters
pStream The output IStream.
bFormatPretty True if we format the output to have automatic indentation.

bool IO::XmlWriter::WriteXmlHeader() virtual

Write the header at the beginning of the XML file.

The header is also known as a "prologue".

bool IO::XmlWriter::BeginElement(const char16_t* pElementName) virtual

Begin a new element.

Parameters
pElementName The name of the element.

bool IO::XmlWriter::EndElement(const char16_t* pElementName) virtual

End the current element.

Parameters
pElementName The name of the element.

bool IO::XmlWriter::BeginProcessingInstruction(const char16_t* pInstructionName) virtual

Begin a new processing intruction.

Parameters
pInstructionName The name of the instruction.

bool IO::XmlWriter::AppendAttribute(const char16_t* pAttrName, const char16_t* pAttrValue) virtual

Append a string attribute to the most recently written element or processing instruction, assuming that it has not been closed.

Parameters
pAttrName The name of the attribute.
pAttrValue The value of the attribute.

This should be called before any character data or child elements are written. XML special characters in the attribute value will be escaped as entities.

bool IO::XmlWriter::AppendAttributeF(const char16_t* pAttrName, const char16_t* pAttrValueFmt, ...) virtual

VPrintF version of AppendAttribute().

Parameters
pAttrName The name of the attribute.
pAttrValueFmt The format used by the value.

bool IO::XmlWriter::WriteCharData(const char16_t* pCharData) virtual

Write a string of character data.

Parameters
pCharData The string of characters.

XML special characters will be escaped as entities.

bool IO::XmlWriter::WriteCDATA(const char16_t* pCharData) virtual

Write a string of unencoded character data.

Parameters
pCharData The string of characters.

Consecutive calls to WriteCDATA will be merged into a single CDATA block. It is an error to include the string "]]>" in the character data.

bool IO::XmlWriter::WriteComment(const char16_t* pCommentText, bool bNewlineBefore = true) virtual

Write a comment tag, including the enclosing .

Parameters
pCommentText The comment text.
bNewlineBefore If true, then a newline will be written before the comment is written.

For compatibility with the XML standard, a run of dashes (-—) will be converted into a single dash. No other encoding is performed.

bool IO::XmlWriter::WriteName(const char16_t* pString) virtual

Writes a C-string as a piece of raw text.

Parameters
pString The null-terminated string to write.

bool IO::XmlWriter::WriteText(const char16_t* pString, size_t nLength) virtual

Write a piece of raw text.

Parameters
pString The string to write.
nLength The length of the string.