CMarkup SetDoc Method

bool CMarkup::SetDoc( MCD_PCSZ szDoc );
bool CMarkup::SetDoc( const MCD_STR& strDoc );

The 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.

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 SetDoc("") and SetDoc(str) where 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.