TinyXML-2: tinyxml2::XMLDocument Class Reference

TinyXML-2 5.0.1

Public Member Functions | List of all members
tinyxml2::XMLDocument Class Reference

`#include <tinyxml2.h>`

Inheritance diagram for tinyxml2::XMLDocument:

## Public Member Functions
| XMLDocument (bool processEntities=true, Whitespace whitespaceMode=PRESERVE_WHITESPACE)
| constructor
virtual XMLDocument * | ToDocument ()
| Safely cast to a Document, or null.
XMLError | Parse (const char *xml, size_t nBytes=(size_t)(-1))
XMLError | LoadFile (const char *filename)
XMLError | LoadFile (FILE *)
XMLError | SaveFile (const char *filename, bool compact=false)
XMLError | SaveFile (FILE *fp, bool compact=false)
bool | HasBOM () const
void | SetBOM (bool useBOM)
XMLElement * | RootElement ()
void | Print (XMLPrinter *streamer=0) const
virtual bool | Accept (XMLVisitor *visitor) const
XMLElement * | NewElement (const char *name)
XMLComment * | NewComment (const char *comment)
XMLText * | NewText (const char *text)
XMLDeclaration * | NewDeclaration (const char *text=0)
XMLUnknown * | NewUnknown (const char *text)
void | DeleteNode (XMLNode *node)
bool | Error () const
| Return true if there was an error parsing the document.
XMLError | ErrorID () const
| Return the errorID.
const char * | GetErrorStr1 () const
| Return a possibly helpful diagnostic location or string.
const char * | GetErrorStr2 () const
| Return a possibly helpful secondary diagnostic location or string.
int | GetErrorLineNum () const
| Return the line where the error occured, or zero if unknown.
void | PrintError () const
| If there is an error, print it to stdout.
void | Clear ()
| Clear the document, resetting it to the initial state.
void | DeepCopy (XMLDocument *target)
virtual XMLNode * | ShallowClone (XMLDocument *) const
virtual bool | ShallowEqual (const XMLNode *) const
Public Member Functions inherited from tinyxml2::XMLNode
const XMLDocument * | GetDocument () const
| Get the XMLDocument that owns this XMLNode.
XMLDocument * | GetDocument ()
| Get the XMLDocument that owns this XMLNode.
virtual XMLElement * | ToElement ()
| Safely cast to an Element, or null.
virtual XMLText * | ToText ()
| Safely cast to Text, or null.
virtual XMLComment * | ToComment ()
| Safely cast to a Comment, or null.
virtual XMLDeclaration * | ToDeclaration ()
| Safely cast to a Declaration, or null.
virtual XMLUnknown * | ToUnknown ()
| Safely cast to an Unknown, or null.
const char * | Value () const
void | SetValue (const char *val, bool staticMem=false)
int | GetLineNum () const
| Gets the line number the node is in, if the document was parsed from a file.
const XMLNode * | Parent () const
| Get the parent of this node on the DOM.
bool | NoChildren () const
| Returns true if this node has no children.
const XMLNode * | FirstChild () const
| Get the first child node, or null if none exists.
const XMLElement * | FirstChildElement (const char *name=0) const
const XMLNode * | LastChild () const
| Get the last child node, or null if none exists.
const XMLElement * | LastChildElement (const char *name=0) const
const XMLNode * | PreviousSibling () const
| Get the previous (left) sibling node of this node.
const XMLElement * | PreviousSiblingElement (const char *name=0) const
| Get the previous (left) sibling element of this node, with an optionally supplied name.
const XMLNode * | NextSibling () const
| Get the next (right) sibling node of this node.
const XMLElement * | NextSiblingElement (const char *name=0) const
| Get the next (right) sibling element of this node, with an optionally supplied name.
XMLNode * | InsertEndChild (XMLNode *addThis)
XMLNode * | InsertFirstChild (XMLNode *addThis)
XMLNode * | InsertAfterChild (XMLNode *afterThis, XMLNode *addThis)
void | DeleteChildren ()
void | DeleteChild (XMLNode *node)
XMLNode * | DeepClone (XMLDocument *target) const
void | SetUserData (void *userData)
void * | GetUserData () const

## Detailed Description

A Document binds together all the functionality. It can be saved, loaded, and printed to the screen. All Nodes are connected and allocated to a Document. If the Document is deleted, all its Nodes are also deleted.

## Member Function Documentation

## ◆ Accept()

virtual bool tinyxml2::XMLDocument::Accept | ( | XMLVisitor * | visitor | ) | const
| virtual

Accept a hierarchical visit of the nodes in the TinyXML-2 DOM. Every node in the XML tree will be conditionally visited and the host will be called back via the XMLVisitor interface.

This is essentially a SAX interface for TinyXML-2. (Note however it doesn't re-parse the XML for the callbacks, so the performance of TinyXML-2 is unchanged by using this interface versus any other.)

The interface has been based on ideas from:

- http://www.saxproject.org/
- http://c2.com/cgi/wiki?HierarchicalVisitorPattern

Which are both good references for "visiting".

An example of using Accept():

    XMLPrinter printer;
    tinyxmlDoc.Accept( &printer );
    const char* xmlcstr = printer.CStr();

Implements tinyxml2::XMLNode.

## ◆ DeepCopy()

void tinyxml2::XMLDocument::DeepCopy | ( | XMLDocument * | target | ) |

Copies this document to a target document. The target will be completely cleared before the copy. If you want to copy a sub-tree, see XMLNode::DeepClone().

NOTE: that the 'target' must be non-null.

## ◆ DeleteNode()

void tinyxml2::XMLDocument::DeleteNode | ( | XMLNode * | node | ) |

Delete a node associated with this document. It will be unlinked from the DOM.

## ◆ HasBOM()

bool tinyxml2::XMLDocument::HasBOM | ( |  | ) | const
| inline

Returns true if this document has a leading Byte Order Mark of UTF8.

## ◆ LoadFile() [1/2]

XMLError tinyxml2::XMLDocument::LoadFile | ( | const char * | filename | ) |

Load an XML file from disk. Returns XML_SUCCESS (0) on success, or an errorID.

## ◆ LoadFile() [2/2]

XMLError tinyxml2::XMLDocument::LoadFile | ( | FILE * |  | ) |

Load an XML file from disk. You are responsible for providing and closing the FILE*.

NOTE: The file should be opened as binary ("rb") not text in order for TinyXML-2 to correctly do newline normalization.

Returns XML_SUCCESS (0) on success, or an errorID.

## ◆ NewComment()

XMLComment* tinyxml2::XMLDocument::NewComment | ( | const char * | comment | ) |

Create a new Comment associated with this Document. The memory for the Comment is managed by the Document.

## ◆ NewDeclaration()

XMLDeclaration* tinyxml2::XMLDocument::NewDeclaration | ( | const char * | text = `0` | ) |

Create a new Declaration associated with this Document. The memory for the object is managed by the Document.

If the 'text' param is null, the standard declaration is used.:

        <?xml version="1.0" encoding="UTF-8"?>

## ◆ NewElement()

XMLElement* tinyxml2::XMLDocument::NewElement | ( | const char * | name | ) |

Create a new Element associated with this Document. The memory for the Element is managed by the Document.

## ◆ NewText()

XMLText* tinyxml2::XMLDocument::NewText | ( | const char * | text | ) |

Create a new Text associated with this Document. The memory for the Text is managed by the Document.

## ◆ NewUnknown()

XMLUnknown* tinyxml2::XMLDocument::NewUnknown | ( | const char * | text | ) |

Create a new Unknown associated with this Document. The memory for the object is managed by the Document.

## ◆ Parse()

XMLError tinyxml2::XMLDocument::Parse | ( | const char * | xml,
|  | size_t | nBytes = `(size_t)(-1)`
| ) |  |

Parse an XML file from a character string. Returns XML_SUCCESS (0) on success, or an errorID.

You may optionally pass in the 'nBytes', which is the number of bytes which will be parsed. If not specified, TinyXML-2 will assume 'xml' points to a null terminated string.

## ◆ Print()

void tinyxml2::XMLDocument::Print | ( | XMLPrinter * | streamer = `0` | ) | const

Print the Document. If the Printer is not provided, it will print to stdout. If you provide Printer, this can print to a file:

    XMLPrinter printer( fp );
    doc.Print( &printer );

Or you can use a printer to print to memory:

    XMLPrinter printer;
    doc.Print( &printer );
    // printer.CStr() has a const char* to the XML

## ◆ RootElement()

XMLElement* tinyxml2::XMLDocument::RootElement | ( |  | ) |
| inline

Return the root element of DOM. Equivalent to FirstChildElement(). To get the first node, use FirstChild().

## ◆ SaveFile() [1/2]

XMLError tinyxml2::XMLDocument::SaveFile | ( | const char * | filename,
|  | bool | compact = `false`
| ) |  |

Save the XML file to disk. Returns XML_SUCCESS (0) on success, or an errorID.

## ◆ SaveFile() [2/2]

XMLError tinyxml2::XMLDocument::SaveFile | ( | FILE * | fp,
|  | bool | compact = `false`
| ) |  |

Save the XML file to disk. You are responsible for providing and closing the FILE*.

Returns XML_SUCCESS (0) on success, or an errorID.

## ◆ SetBOM()

void tinyxml2::XMLDocument::SetBOM | ( | bool | useBOM | ) |
| inline

Sets whether to write the BOM when writing the file.

## ◆ ShallowClone()

virtual XMLNode* tinyxml2::XMLDocument::ShallowClone | ( | XMLDocument * | document | ) | const
| inlinevirtual

Make a copy of this node, but not its children. You may pass in a Document pointer that will be the owner of the new Node. If the 'document' is null, then the node returned will be allocated from the current Document. (this->GetDocument())

Note: if called on a XMLDocument, this will return null.

Implements tinyxml2::XMLNode.

## ◆ ShallowEqual()

virtual bool tinyxml2::XMLDocument::ShallowEqual | ( | const XMLNode * | compare | ) | const
| inlinevirtual

Test if 2 nodes are the same, but don't test children. The 2 nodes do not need to be in the same Document.

Note: if called on a XMLDocument, this will return false.

Implements tinyxml2::XMLNode.

The documentation for this class was generated from the following file:

- tinyxml2.h