CMarkup SetData Method

bool CMarkup::SetData( MCD_CSTR szData, int nFlags = 0 );
bool CMarkup::SetData( int nValue );

Call SetData to replace the main position element's contents with szData. This will remove any child elements of the main position element if any. It returns false if there is no main position.

See the GetData method for details on the data value for nodes other than elements.

The following example shows the result of calling SetData("n<6") when the main position is the EQUATION element. The less than sign is encoded, and will be unencoded by the GetData method.

<EQUATION>n&lt;6</EQUATION>

Update March 24, 2009: SetData can be used with CMarkup release 11.0 developer version file write mode (see C++ XML writer), but only if the element was created without specifying a data value in AddElem.

Using a CDATA Section

If MNF_WITHCDATA is specified for nFlags, a CDATA Section is used. This is useful for making the document more human readable because the character data is not processed to encode special markup characters. In the following example if the main position is the EQUATION element, the CDATA section is created by calling SetData("n<6",MNF_WITHCDATA).

<EQUATION><![CDATA[n<6]]></EQUATION>

The data passed to be stored in a CDATA Section inside an element may in rare cases happen to contain the same ]]> end delimiter that is used to indicate the end of the CDATA Section in the XML. A call to SetData("]]>",MNF_WITHCDATA) generates multiple CDATA Sections in order to store the data satisfactorily in the XML. For the delimiter string occurring in the data not to be mistaken for a delimiter string, it is split between two CDATA Sections after the second bracket.

doc.AddElem( "EQUATION" );
doc.SetData( "]]>", MNF_WITHCDATA );
<EQUATION><![CDATA[]]]]><![CDATA[>]]></EQUATION>

The GetData method concatenates the data from the consecutive CDATA Sections in the content of the element. Now the SetData, GetData, SetChildData and GetChildData methods all work to support CDATA Sections without tedious handling of this rare case.

Note that MNF_WITHCDATA is now also supported in AddElem and similar methods, whereas previously you had to call AddElem and SetData to generate CData Section data content in a new element.

Entity and numeric character references

If MNF_WITHREFS is specified for nFlags, the ampersand of entity references and numeric character references is not escaped. Use this to put Unicode numeric character references and entity references in the XML document. Without this flag the ampersand will be encoded as &amp; causing the references in your data value not to be treated as references.

doc.AddElem( "note" );
doc.SetData( "the &#22269; char means nation", MNF_WITHREFS );
<note>the &#22269; char means nation</note>

See also AddElem and SetData Flags