CMarkup SetDoc Method
SetDoc method parses a string containing an XML document. Do not pass a filename to this method (see Load for that). For example:
CMarkup xml; xml.SetDoc( "<msg>Hello World</msg>" );
The newly populated CMarkup object has no current position; i.e. the position is logically before the beginning of the document. In this state, calling
FindElem() would find the first element (the root element) in the document and
FindNode() would find the first node (possibly the XML declaration if there).
If the document is not well-formed, this method returns
false but the CMarkup object retains the string. The Save method saves this unmodified string and likewise the GetDoc method returns this string unmodified, regardless of whether it is well-formed.
A CMarkup object can be non-empty and not well-formed at the same time. Even if you call
SetDoc with garbled text, the CMarkup object will retain that text. So you cannot test if GetDoc returns an empty string as a way of determining well-formedness. To determine if the document is well-formed, call IsWellFormed.
SetDoc expects proper markup text. If the document is edited manually, ensure that special characters in text data and attribute values are escaped with the appropriate ampersand code. The quotes do not need to be escaped in data, only in attribute values.
- < < less than
- > > greater than
- & & ampersand
- ' ' apostrophe or single quote (only escape this in attribute value)
- " " double quote (only escape this in attribute value)
You do not need to worry about these special characters if you have created the document using CMarkup or any other XML tool. See Standard Special Characters.
Update June 7, 2009: Release 11.1 includes a deflate feature with
SetDoc(NULL) to be used when you want to release the object's extra allocated memory.
SetDoc(NULL) behaves differently than
str is an empty string. Passing a
NULL causes the
CMarkup object to deflate its string and index memory back to the minimum, while the other forms hold onto the index memory and may keep the string memory depending on the string class's implementation of the assignment operator.