FindElem and FindChildElem only search forward. You have to call ResetMainPos or ResetChildPos if you don't know the order of the siblings and/or don't want to process sequentially. For example, you would call ResetChildPos after finding child element CHILD3 before finding child element CHILD1. If you didn't know the order you could call ResetChildPos before every FindChildElem, or loop through all child elements and get each child tag name and process accordingly. Keep in mind that there are no internal lookup tables of tag names; FindChildElem just looks sequentially and CMarkup keeps track of the current child position. So whenever you know the order and have the opportunity you should find and process CHILD1 first since that is fastest.

Update: go backwards with FindPrevElem added in developer release 7.0.

The only confusing thing with GetData returning the child elements would be that SetData would not perform the complimentary operation in this case. SetData would treat the tags as special chars and convert them to ampersand codes.

Update July 12, 2005: What you want is the equivalent of .NET's InnerXml which works for children and/or mixed content. CMarkup release 8.0 now has the GetElemContent method to do just this. It returns the XML content and any child elements.

CMarkup doc;
CString data;
doc.AddElem("set");
data = doc.GetData();
ASSERT(data.IsEmpty());
doc.AddChildElem("elem");
doc.RemoveChildElem();
data = doc.GetData();
ASSERT(data.IsEmpty());

Well, CMarkup doesn't necessarily collapse an element back into the empty element <elem/> form. Implementing this might be too tricky and I don't think its a good thing to rely on. The way to check if there are no children is to ResetChildElem and test the result of FindChildElem.

<test>
    <a/>
    <b/>
    <c/>
</test>

After you call IntoElem(), the first call to FindChildElem will find the first child, and subsequent calls to FindChildElem will find the next ones. You can use the following loop to loop through the children without specifying the tagname in FindChildElem:

while ( xml.FindChildElem() )
{
  CString csTag = xml.GetChildTagName();
  if ( csTag == "a" )
    do this; // a
  else if ( csTag == "b" )
    do that; // b
  else if ( csTag == "c" )
    do the other; // c
}

If you find child c and then want to find a or b, call ResetChildPos(). If you always specify the tag name and do not know the order, then you should always call ResetChildPos() before FindChildElem("tagname"). When you specify the tagname in FindChildElem, it finds the first one with the matching tagname and then it will find the next one with the matching tagname, etc. As in other things, you have to judge what is the most efficient approach for your particular problem.

xml.SetDoc...
xml.FindElem();
xml.IntoElem();
while ( xml.FindElem("MsgItem") )

Just change FindElem to FindPrevElem. When there is no current main position element, FindPrevElem will start from the last MsgItem element and go to previous ones.

As mentioned above, FindPrevElem is in the developer version since release 7.0.

MCD_STR GetData() const { return x_GetData(m_iPos); };
bool FindElem( MCD_CSTR szName=NULL );

Thanks for clearly laying out this problem. As you mentioned, FindElem is not const because it does actually change the CMarkup object, since the current position is stored within the CMarkup object. The "navigation" methods were purposefully not called "read" methods because they do modify the object's internally stored position or bookmark, and therefore are often actually "write" methods. I have actually begun to move away from the original grouping of "navigation" methods (see CMarkup Methods) partly because of this potential confusion.

This issue is also mentioned in The CMarkup Twist in Multithreading and CMarkup.

Using the mutable storage class specifier is a very resourceful idea and creative solution but ultimately I cannot use it because strictly speaking if you pass a CMarkup object as a constant reference you expect that it's internal position will not be modified. The mutable keyword is a way of fudging on that for the sake of a higher concept of "read" and "write," but in this case would serve to hide or disguise what might really be happening in the called function.

I have given this issue of internalized position a lot of thought since the very beginning of CMarkup and it certainly was a debatable design choice with many ramifications, including some unfortunate issues in the design of FOAL, but with the chief advantage that there is only one single class. Many times I have considered integrating a struct to contain the position, allowing you to optionally navigate without modifying the CMarkup object by instantiating a separate position struct. This will add complexity which is a trade off. I have not seen a way to cleanly integrate this into the existing API and so I have not found a way to release this functionality as part of the product yet.