CMarkup GetSubDoc Method

MCD_STR CMarkup::GetSubDoc();

The GetSubDoc method returns the main position element and any elements it contains as an XML document markup string.

Update June 7, 2009: In Release 11.1 GetSubDoc is no longer const because it can be used in file read mode which can alter the state of the CMarkup object as you progress through the file, see the "File read mode" section below.

GetSubDoc is like GetDoc because the returned string is an XML document of its own. It is different from GetData, which only gets the data content and no child elements. The GetSubDoc method returns an XML document in which the root element was the main position element in the source document. If you want the XML in between the start and end tags, see the GetElemContent method.

See Subdocuments and Fragments of XML Documents.

Here is an example document to illustrate subdocuments.

<config>
  <diagnostics d="3">
    <file>C:\temp\a.txt</file>
  </diagnostics>
  <diagnostics d="7">
    <file>D:\temp\a.txt</file>
    <proxy usedefault="true"/>
  </diagnostics>
</config>

If the current main position is the first diagnostics element, GetSubDoc() returns the following subdocument.

  <diagnostics d="3">
    <file>C:\temp\a.txt</file>
  </diagnostics>

File read mode

In release 11.1, when you open a file in file read mode with Open, GetSubDoc can be used to extract subdocuments. If the subdocument consists of one element without child elements, then the element is kept as the current position and you can still access attributes and data. However, if in file read mode the subdocument has child elements the current position goes to right after the subdocument.

You can SetDoc the string returned from GetSubDoc into another CMarkup object and use all the CMarkup navigation and modification methods on it. GetSubDoc is also handy for transferring portions of the input file to other documents such as described in Split XML file into smaller pieces.