C++ Elmax

Table of contents

Element

Element is the main class in Elmax. Most activities takes place directly or indirectly with Element class. This section deals with the in and outs of the Element class.

Element Creation

Element can be created by calling Create and CreateNew method explicitly or by calling one of the mutators which will create the element node if it does not exists. Create does not create if the node with name is already exists. CreateNew will always create. Note that when you call CreateNew repeatedly, only the last element gets created. Let me show you a code example to explain this. In ther example below, In the first CreateNew call, elements aa, bb, and cc are created. In each subsequent call, only the element cc is created. Note: please pass in a valid non-null namespace URI argument if there is a namespace associated with the new element.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndInitDom(pDoc);
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);

    Element elem1 = root[L"aa|bb|cc"].CreateNew();
    Element elem2 = root[L"aa|bb|cc"].CreateNew();
    Element elem3 = root[L"aa|bb|cc"].CreateNew();
}

This is the output XML.

<aa><bb><cc/><cc/><cc/></bb></aa>

Element Deletion

Element is deleted through the Delete method. This is the code to delete the node.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndInitDom(pDoc);
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);

    Element elem = root[L"aa"][L"bb"][L"cc"].CreateNew();
	elem.Delete();
}

Element Mutators

Element values are set through the mutators. This is the code to set value of the element node.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndInitDom(pDoc);
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);

    Element elem = root[L"aa"][L"bb"][L"cc"].CreateNew();
    int dd = 2000000000;
    elem[L"dd"].SetInt32(dd);
}

This is a list of mutators which the Element class supports.

bool SetBool(bool val);

bool SetChar(char val);

bool SetShort(short val);

bool SetInt32(int val);

bool SetInt64(__int64 val);

bool SetUChar(unsignedchar val);

bool SetUShort(unsignedshort val);

bool SetUInt32(unsignedint val);

bool SetUInt64(unsigned __int64 val);

bool SetFloat(float val);

bool SetDouble(double val);

bool SetString(const std::wstring& val);

bool SetString(const std::string& val);

bool SetCString(const CString& val);

bool SetGUID(const GUID& val, bool bRemoveBraces=false);

bool SetDate(const Elmax::Date& val);

bool SetDateTime(const Elmax::DateAndTime& val);

bool SetFileContents(const std::wstring& filepath, bool bSaveFilename, bool bSaveFileLength);

bool SetHex(unsignedint val, bool bAddPrefix=false);

Element Accessors

Developer supplies a default value to the accessor, in case the value does not exists or it is invalid. The default value will be assigned back to the caller. This is an example of calling the integer accessor.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndInitDom(pDoc);
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);

    Element elem = root[L"aa"][L"bb"][L"cc"].CreateNew();
    int dd = 2000000000;
    elem[L"dd"].SetInt32(dd);

    int dd2 = elem[L"dd"].GetInt32(10);
}

This is a list of accessors which the Element class supports.

bool GetBool(bool defaultVal) const;

char GetChar(char defaultVal) const;

short GetShort(short defaultVal) const;

int GetInt32(int defaultVal) const;

__int64 GetInt64(__int64 defaultVal) const;

unsignedchar GetUChar(unsignedchar defaultVal) const;

unsignedshort GetUShort(unsignedshort defaultVal) const;

unsignedint GetUInt32(unsignedint defaultVal) const;

unsigned __int64 GetUInt64(unsigned __int64 defaultVal) const;

float GetFloat(float defaultVal) const;

double GetDouble(double defaultVal) const;

std::wstring GetString(const std::wstring& defaultVal) const;

std::string GetString(const std::string& defaultVal) const;

CString GetCString(const CString& defaultVal) const;

GUID GetGUID(const GUID& defaultVal) const;

Elmax::Date GetDate(const Elmax::Date& defaultVal) const;

Elmax::DateAndTime GetDateTime(const Elmax::DateAndTime& defaultVal) const;

char* GetFileContents(std::wstring& filename, int& length);

unsignedint ReadHex(unsignedint defaultVal) const;

Element Collection

Collection of the element children is done through the GetCollection method. There is a similar AsCollection method which get the siblings with the same name. Below is the code to call GetCollection.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndInitDom(pDoc);
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);

    Element elem1 = root[L"aa|bb|cc"].CreateNew();
    elem1.SetInt32(11);
    Element elem2 = root[L"aa|bb|cc"].CreateNew();
    elem2.SetInt32(22);
    Element elem3 = root[L"aa|bb|cc"].CreateNew();
    elem3.SetInt32(33);

    Element::collection_t vec = root[L"aa"][L"bb"].GetCollection(L"cc");
}

There is a predicate version of the GetCollection and AsCollection method. Below is the example to call predicate version of GetCollection with function object.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndInitDom(pDoc);
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);

    Element elem1 = root[L"aa|bb|cc"].CreateNew();
    elem1.SetInt32(11);
    Element elem2 = root[L"aa|bb|cc"].CreateNew();
    elem2.SetInt32(22);
    Element elem3 = root[L"aa|bb|cc"].CreateNew();
    elem3.SetInt32(33);

    Pred pred;
    Element::collection_t vec = root[L"aa"][L"bb"].GetCollection(L"cc",  pred);
}

Root Element

RootElement is the helper class contributed by PJ Arends to eliminate the need to call SetConverter and SetDomDoc. To build this class successfully, you need to download and build C++ Boost FileSystem library. If user decides not to use RootElement class, he/she can exclude this class from the Elmax project and not include FileSystem Library.

Root Element Load File

The RootElement constructor takes in a file path and loads the XML file into the DOM if exists. Else the document is a empty DOM. When the user calls SaveFile, he/she can either specifies a new path or the constructor path is used.

usingnamespace Elmax;
std::wstring path = L"D:\\temp.xml";
RootElement root(path); // load the file if it exists// Use RootElement like other elements
Element elem = root[L"aa"][L"bb"][L"cc"].CreateNew();
elem["dd"].SetBool(true);

If user used an Element as root, the equivalent win32 code is

MSXML2::IXMLDOMDocumentPtr pDoc;

HRESULT hr = pDoc.CreateInstance(__uuidof(MSXML2::DOMDocument30));
if (SUCCEEDED(hr))
{
    // these methods should not fail so don't inspect result
    pDoc->async = VARIANT_FALSE;
    pDoc->validateOnParse = VARIANT_FALSE;
    pDoc->resolveExternals = VARIANT_FALSE;
}

std::wstring path = L"D:\\temp.xml";

DWORD       fileAttr;
fileAttr = GetFileAttributes(fileName);
if (0xFFFFFFFF != fileAttr) // file exists
    pDoc->LoadXml(path)

usingnamespace Elmax;

Element root;
root.SetConverter(REGEX_CONV);
root.SetDomDoc(doc);

// Use RootElement like other elements
Element elem = root[L"aa"][L"bb"][L"cc"].CreateNew();
elem[L"dd"].SetBool(true);

Root Element Save File

File is saved through the SaveFile method.

usingnamespace Elmax;
std::wstring path = L"D:\\temp.xml";
RootElement root(path); // load the file if it exists// Use RootElement like other elements
Element elem = root[L"aa"][L"bb"][L"cc"].CreateNew();
elem[L"dd"].SetBool(true);

root.SaveFile();

Attribute

Attribute Creation

Attribute can be created by calling Create method explicitly or by calling one of the mutators which will create the attribute node if it does not exists. Please note exception will be thrown if the element, on which the attribute is to be created, does not exists. Please use Element's Exists to check the element exists before calling the mutators. Calling the mutators is the recommended way to create attribute nodes. Below is example code of calling the integer mutator to create the attribute implicitly.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndInitDom(pDoc);
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);

    Element elem = root[L"aa"][L"bb"][L"cc"].CreateNew();
    int dd = 2000000000;
	// attr attribute will be created automatically
    Attribute attr = elem.Attribute(L"Attr");
    attr.SetInt32(dd);
}

Attribute Deletion

Attribute node is deleted, using the Delete method on the Attribute class. This is an example of deleting a attribute.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndInitDom(pDoc);
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);

    Element elem = root[L"aa"][L"bb"][L"cc"].CreateNew();
    int dd = 2000000000;
    elem.Attribute(L"Attr").SetInt32(dd);

    Elmax::Attribute attr = elem.Attribute(L"Attr");

    attr.Delete();
}

Attribute Mutators

We use mutators to change the value of the attribute. This is an an example of using the mutators.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndInitDom(pDoc);
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);

    Element elem = root[L"aa"][L"bb"][L"cc"].CreateNew();
    int dd = 2000000000;
	// attr attribute will be created automatically
    Attribute attr = elem.Attribute(L"Attr");
    attr.SetInt32(dd);
}

This is a full list of mutators which Attribute class supports.

bool SetBool(bool val);

bool SetChar(char val);

bool SetShort(short val);

bool SetInt32(int val);

bool SetInt64(__int64 val);

bool SetUChar(unsignedchar val);

bool SetUShort(unsignedshort val);

bool SetUInt32(unsignedint val);

bool SetUInt64(unsigned __int64 val);

bool SetFloat(float val);

bool SetDouble(double val);

bool SetString(const std::wstring& val);

bool SetString(const std::string& val);

bool SetCString(const CString& val);

bool SetGUID(const GUID& val, bool bRemoveBraces=false);

bool SetDate(const Elmax::Date& val);

bool SetDateTime(const Elmax::DateAndTime& val);

bool SetHex(unsignedint val, bool bAddPrefix=false);

Attribute Accessors

Developer would use accessors to retrieve the value of the attribute. If the value does not exist or it is invalid, the default value supplied to the accessor will be re-assigned to the caller. This is an example of calling the 32 bit integer accessor.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndInitDom(pDoc);
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);

    Element elem = root[L"aa"][L"bb"][L"cc"].CreateNew();
    int dd = 2000000000;
	// attr attribute will be created automatically
    Attribute attr = elem.Attribute(L"Attr");
	attr.SetInt32(dd);
    int dd3 = attr.GetInt32(10);
}

This is a full list of accessors which Attribute class supports.

bool GetBool(bool defaultVal) const;

char GetChar(char defaultVal) const;

short GetShort(short defaultVal) const;

int GetInt32(int defaultVal) const;

__int64 GetInt64(__int64 defaultVal) const;

unsignedchar GetUChar(unsignedchar defaultVal) const;

unsignedshort GetUShort(unsignedshort defaultVal) const;

unsignedint GetUInt32(unsignedint defaultVal) const;

unsigned __int64 GetUInt64(unsigned __int64 defaultVal) const;

float GetFloat(float defaultVal) const;

double GetDouble(double defaultVal) const;

std::wstring GetString(const std::wstring& defaultVal) const;

std::string GetString(const std::string& defaultVal) const;

CString GetCString(const CString& defaultVal) const;

GUID GetGUID(const GUID& defaultVal) const;

Elmax::Date GetDate(const Elmax::Date& defaultVal) const;

Elmax::DateAndTime GetDateTime(const Elmax::DateAndTime& defaultVal) const;

unsignedint ReadHex(unsignedint defaultVal) const;

Attribute Collection

We can get a list of attributes which the element node currently holds, by calling the Element's GetAttributes method. This is an example of calling GetAttributes.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndInitDom(pDoc);
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);

    Element elem = root[L"aa"][L"bb"][L"cc"].CreateNew();
    bool dd = true;
    int dd2 = 123;
    elem.Attribute(L"Attr1").SetBool(dd);
    elem.Attribute(L"Attr2").SetInt32(dd2);
    elem.Attribute(L"Attr3").SetString(L"Hello");

    std::vector<Elmax::Attribute> attrs = elem.GetAttributes();
}

CData Section

This section shows the methods to manipulate the CData section node.

CData Creation

CData section node can be added to the element through the AddCData method of the Element class. Below is an example of how to add a CData section.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndLoadXml(pDoc, L"example.xml");
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);

    Element elem = root[L"aa"][L"bb"][L"cc"].CreateNew();
    Assert::IsTrue(elem.Exists());
    std::wstring strCData = L"<data>Where is my data?</data>";
    elem.AddCData(strCData);
}

CData Deletion

The CData section node can be deleted through the Delete method of the CData class. Element class provides a DeleteAllCData method to delete all the CData section under the element. Below is an example of how to delete a CData section.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndLoadXml(pDoc, L"example.xml");
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);

    Element elem = root[L"aa"][L"bb"][L"cc"].CreateNew();
    elem.AddCData(strCData);

    CData cdata = elem.GetCDataCollection().at(0);

    cdata.Delete();
}

CData Mutators

The contents of CData section node can be changed through the Update method of the CData class. Below is an example of how to update a CData section contents.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndLoadXml(pDoc, L"example.xml");
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);

    Element elem = root[L"aa"][L"bb"][L"cc"].CreateNew();
    std::wstring strCData = L"<data>Where is my data?</data>";
    elem.AddCData(strCData);

    CData cdata = elem.GetCDataCollection().at(0);

    std::wstring strUpdate = L"<data>Where is my world?</data>";
    cdata.Update(strUpdate);
}

CData Accessors

The contents of the CData section can be retrieved through the GetContent method which returns a string. Below is the example of getting the CData contents.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndLoadXml(pDoc, L"example.xml");
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);

    Element elem = root[L"aa"][L"bb"][L"cc"].CreateNew();

    CData cdata = elem.GetCDataCollection().at(0);

    std::wstring s = cdata.GetContent();
}

CData Collection

CData section collection can be retrieved through the GetCDataCollection method of the Element class. Below is an example on how to call GetCDataCollection method.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndLoadXml(pDoc, L"example.xml");
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);

    Element elem = root[L"aa"][L"bb"][L"cc"].CreateNew();

    std::vector<CData> vec = elem.GetCDataCollection();
}

Base64

Some programmers prefer to store binary data in Base64 format under an element, instead of in the CData section, to easily identify and find it. The downside is Base64 format takes up more space, and data conversion takes time. C++ version of the Element class provides some helper method to ease the burden of using Base64 conversion; The .NET BCL has standard Convert class to do the Base64 conversion. This code example shows how to use Base64 conversion before assignment, and also convert back from Base64 to binary data after reading.

Elmax::Element elem1;
std::string strNormal = "@#$^*_+-|\~<>";
// Assigning base64 data
elem1 = Element::ConvToBase64(strNormal.c_str(), strNormal.length());

// Reading base64 data
std::wstring strBase64 = elem1.GetString(L"ABC");

size_t len = 0;
// Get the length required
Element::ConvFromBase64(strBase64, NULL, len);

char* p = newchar[len+1];
memset(p, 0, len+1);

Element::ConvFromBase64(strBase64, p, len);
// process p here (not shown)(Remember to delete p).

Comment

This section shows the methods to manipulate the comment node.

Comment Creation

Comment objects are created through the AddComment method of the Element class. Below is an example on how to add a comment node to the element.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndLoadXml(pDoc, L"example.xml");
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);

    Element elem = root[L"aa"][L"bb"][L"cc"].CreateNew();
    Assert::IsTrue(elem.Exists());
    std::wstring strComment = L"Can you see me?";
    elem.AddComment(strComment);
}

Comment Deletion

Comment node is deleted through the Delete method in the Comment class. To delete all comments in a element, call DeleteAllComment method of the Element class. This is the way to call Delete method.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndLoadXml(pDoc, L"example.xml");
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);

    Element elem = root[L"aa"][L"bb"][L"cc"].CreateNew();
    Assert::IsTrue(elem.Exists());
    std::wstring strComment = L"Can you see me?";
    elem.AddComment(strComment);

    Comment comment = elem.GetCommentCollection().at(0);

    comment.Delete();
}

Comment Mutators

Comment node are changed through the Update method on the Comment class. Below is an example on how to update the comment node.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndLoadXml(pDoc, L"example.xml");
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);

    Element elem = root[L"aa"][L"bb"][L"cc"].CreateNew();
    Assert::IsTrue(elem.Exists());
    std::wstring strComment = L"Can you see me?";
    elem.AddComment(strComment);

    Comment comment = elem.GetCommentCollection().at(0);

    System::String^ s1 = gcnew System::String(strComment.c_str());
    System::String^ s2 = gcnew System::String(comment.GetContent().c_str());

    Assert::AreEqual(s1, s2);

    std::wstring strUpdate = L"Cannot see anything!";
    Assert::IsTrue(comment.Update(strUpdate));
}

Comment Accessors

The contents of the comment can be retrieved through the GetContent of the Comment class. Below is the sample code of how to call GetContent.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndLoadXml(pDoc, L"example.xml");
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);

    Element elem = root[L"aa"][L"bb"][L"cc"].CreateNew();

    Comment comment = elem.GetCommentCollection().at(0);

    std::wstring s = comment.GetContent();
}

Get Comment Collection

As the reader has seen earlier, he/she can get a collection from element through the GetCommentCollection method. Below is an example on how to use this method.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndLoadXml(pDoc, L"example.xml");
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);

    Element elem = root[L"aa"][L"bb"][L"cc"].CreateNew();

    std::vector<Comment> vec = elem.GetCommentCollection();
}

HyperElement

One to One Join

HyperElement is a class which can link one element to another element elsewhere. vecElem1 and vecElem2 are a list of elements to be link up. attrName1 and attrName2 are names of the attributes whose exact same values will be linked up. In the case of more than 1 element whose attribute has the same value, it is a case of 1st found, 1st linked. if attribute name is empty, the element value will be used instead of the attribute value. CaseSensitive indicates if the attribute value comparison is case sensitive.

static std::vector< std::pair<Elmax::Element, Elmax::Element> >
    JoinOneToOne(
    std::vector<Elmax::Element>& vecElem1,
    const std::wstring& attrName1,
    std::vector<Elmax::Element>& vecElem2,
    const std::wstring& attrName2,
    bool bCaseSensitive);

Below is sample code of how the JoinOneToOne is used.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndLoadXml(pDoc, L"example.xml");
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);

    Element elem1 = root[L"aa|bb|cc"];

    Element elem4 = root[L"dd|ee"];

    std::vector< std::pair<Elmax::Element, Elmax::Element> > vec =
        HyperElement::JoinOneToOne(elem1.AsCollection(), L"", elem4.AsCollection(), L"SomeValue", false);
}

There is also a predicate version of JoinOneToOne where lambda and function object can be used as predicate for the comparison.

template<typename DoubleElementPredicate>
static std::vector< std::pair<Elmax::Element, Elmax::Element> >
    JoinOneToOne(
        std::vector<Elmax::Element>& vecElem1,
        std::vector<Elmax::Element>& vecElem2,
        DoubleElementPredicate pred);

Below is a sample code of how the prediate version of JoinOneToOne is used. DoubleElementPred is a function object declared elsewhere.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndLoadXml(pDoc, L"example.xml");
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);

    Element elem1 = root[L"aa|bb|cc"];

    Element elem4 = root[L"dd|ee"];

    DoubleElementPred pred;
    std::vector< std::pair<Elmax::Element, Elmax::Element> > vec =
        HyperElement::JoinOneToOne(elem1.AsCollection(), elem4.AsCollection(), pred);
}

One to Many Join

HyperElement is a class which can link one element to a list of elements whose attribute values matched. vecElem1 and vecElem2 are a list of elements to be link up. attrName1 and attrName2 are names of the attributes whose exact same values will be linked up. In the case of more than 1 element whose attribute has the same value, it is a case of 1st found, 1st linked. if attribute name is empty, the element value will be used instead of the attribute value. CaseSensitive indicates if the attribute value comparison is case sensitive.

static std::vector< std::pair<Elmax::Element, std::vector<Elmax::Element> > >
    JoinOneToMany(
        std::vector<Elmax::Element>& vecElem1,
        const std::wstring& attrName1,
        std::vector<Elmax::Element>& vecElem2,
        const std::wstring& attrName2,
        bool bCaseSensitive);

Below is sample code of how the JoinOneToMany is used.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndLoadXml(pDoc, L"example.xml");
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);

    Element elem1 = root[L"aa|bb|cc"];

    Element elem4 = root[L"dd|ee"];

    std::vector< std::pair<Elmax::Element, std::vector<Elmax::Element> > > vec =
        HyperElement::JoinOneToMany(elem1.AsCollection(), L"", elem4.AsCollection(), L"SomeValue", false);
}

template<typename DoubleElementPredicate>
static std::vector< std::pair<Elmax::Element, std::vector<Elmax::Element> > >
    JoinOneToMany(
        std::vector<Elmax::Element>& vecElem1,
        std::vector<Elmax::Element>& vecElem2,
        DoubleElementPredicate pred)

Below is sample code of how the prediate version of JoinOneToMany is used. DoubleElementPred is a function object declared elsewhere.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndInitDom(pDoc, L"example.xml");
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);

    Element elem1 = root[L"aa|bb|cc"];

    Element elem4 = root[L"dd|ee"];

    DoubleElementPred pred;
    std::vector< std::pair<Elmax::Element, std::vector<Elmax::Element> > > vec =
        HyperElement::JoinOneToMany(elem1.AsCollection(), elem4.AsCollection(), pred);
}

XPath

Document level

Document level XPath is done, using the Document class.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndLoadXml(pDoc, L"example.xml");
Document elmaxDoc(pDoc);
std::vector<Element> nodes = elmaxDoc.GetElementsByTagName(L"dd");

Below is the list of XPath methods in Document class.

std::vector<Elmax::Element> GetElementsByTagName(const std::wstring& tagName);
std::vector<Elmax::Element> SelectNodes(const std::wstring& xpath);
Elmax::Element SelectSingleNode(const std::wstring& xpath);

Element level

Element level XPath is done, using the Element class.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndLoadXml(pDoc, L"example.xml");
if (SUCCEEDED(hr))
{
    usingnamespace Elmax;
    Element root;
    root.SetConverter(NORMAL_CONV);
    root.SetDomDoc(pDoc);
    Element elem = root[L"aa/bb/cc"].CreateNew();

    Element singleNode = elem.SelectSingleNode(L"//dd");
}

Below is the list of XPath methods in Element class.

Element SelectSingleNode(const std::wstring& szXPath);
std::vector<Element> SelectNodes(const std::wstring& szXPath);

Linq-To-XML Style of Node Creation

Example

To use Linq-to-XML Style of Node Creation to create the XML, we have to use the new classes, NewElement, NewAttribute, NewCData and NewComment. Below is an example of how to create a simple XML with these classes.

MSXML2::IXMLDOMDocumentPtr pDoc;
HRESULT hr = CreateAndInitDom(pDoc);

if (SUCCEEDED(hr))
{
    usingnamespace Elmax;

    NewElement root(L"Foods");

    root.Add(
        NewElement(L"Food",
            NewAttribute(L"Name", L"Luncheon Meat"),
            NewAttribute(L"Price", L"8.40"),
            NewAttribute(L"Category", L"Grocery"),
            NewElement(L"Manufacturer",
                NewElement(L"Address", L"Jurong, Singapore"),
                NewElement(L"Name", L"Acme Canned Food")
            )
        ),
        NewElement(L"Food",
            NewAttribute(L"Name", L"Instant Noodle"),
            NewAttribute(L"Price", L"12.30"),
            NewAttribute(L"Category", L"Dried Food"),
            NewElement(L"Manufacturer",
                NewElement(L"Address", L"Ang Mo Kio, Singapore"),
                NewElement(L"Name", L"Ah Kong Food Industrial")
            )
        )
    );

    root.PrettySave(pDoc, szPath);
}

Here is the XML contents generated from the above Linq-to-XML Style of Node Creation code.

<?xmlversion="1.0"encoding="UTF-16"?><Foods><FoodName="Luncheon Meat"Price="8.40"Category="Grocery"><Manufacturer><Address>Jurong, Singapore</Address><Name>Acme Canned Food</Name></Manufacturer></Food><FoodName="Instant Noodle"Price="12.30"Category="Dried Food"><Manufacturer><Address>Ang Mo Kio, Singapore</Address><Name>Ah Kong Food Industrial</Name></Manufacturer></Food></Foods>

The constructors and the Add methods of NewElement restricted to adding to a maximum of 16 elements. There is a way to add more than 16 elements; There is an overloaded Add method which takes in an lambda. This method is only available on Visual C++ 11. On earlier version of Visual C++ (such as Visual C++ 10), the method is disabled by a MSCVER check due to lambda support in Visual C++ 10 is partially broken. Below is the definition of the Add method.

NewElement Add(auto func(NewElement& parent)->void)
{
    func(*this);
    return *this;
}

Below is an example of how do we add more than 16 elements, using lambda. Note: parent argument actually refers to hollywood element.

usingnamespace Elmax;
NewElement hollywood(L"Hollywood");

hollywood.Add([](Elmax::NewElement& parent)->void {

    usingnamespace Elmax;
    NewElement elem = NewElement(L"Stars");

    elem.Add(NewElement(L"Actor", L"Johnny Depp"));
    elem.Add(NewElement(L"Actor", L"Brad Pitt"));
    elem.Add(NewElement(L"Actor", L"Leonardo DiCaprio"));
    elem.Add(NewElement(L"Actor", L"Will Smith"));
    elem.Add(NewElement(L"Actor", L"George Clooney"));
    elem.Add(NewElement(L"Actor", L"Tom Cruise"));
    elem.Add(NewElement(L"Actor", L"Matt Damon"));
    elem.Add(NewElement(L"Actor", L"Orlando Bloom"));
    elem.Add(NewElement(L"Actor", L"Bruce Willis"));
    elem.Add(NewElement(L"Actor", L"Steve Carell"));
    elem.Add(NewElement(L"Actress", L"Jennifer Aniston"));
    elem.Add(NewElement(L"Actress", L"Jessica Alba"));
    elem.Add(NewElement(L"Actress", L"Halle Berry"));
    elem.Add(NewElement(L"Actress", L"Angelina Jolie"));
    elem.Add(NewElement(L"Actress", L"Sandra Bullock"));
    elem.Add(NewElement(L"Actress", L"Reese Witherspoon"));
    elem.Add(NewElement(L"Actress", L"Jennifer Garner"));
    elem.Add(NewElement(L"Actress", L"Julia Roberts"));
    elem.Add(NewElement(L"Actress", L"Gwyneth Paltrow"));
    elem.Add(NewElement(L"Actress", L"Meg Ryan"));
    elem.Add(NewElement(L"Actress", L"Hillary Swank"));
    elem.Add(NewElement(L"Actress", L"Uma Thurman"));
    elem.Add(NewElement(L"Actress", L"Keira Knightley"));
    elem.Add(NewElement(L"Actress", L"Meryl Streep"));
    elem.Add(NewElement(L"Actress", L"Cameron Diaz"));
    elem.Add(NewElement(L"Actress", L"Salma Hayek"));
    elem.Add(NewElement(L"Actress", L"Penelope Cruz"));
    elem.Add(NewElement(L"Actress", L"Nicole Kidman"));
    elem.Add(NewElement(L"Actress", L"Michelle Pfeiffer"));
    elem.Add(NewElement(L"Actress", L"Drew Barrymore"));
    elem.Add(NewElement(L"Actress", L"Jennifer Lopez"));
    elem.Add(NewElement(L"Actress", L"Catherine Zeta-Jones"));

    parent.Add(elem);
});

hollywood.Save(L"C:\\Stars.xml", L"1.0", true);

This is what the Stars.xml looked like.

<?xmlversion="1.0"encoding="UTF-8"?><Hollywood><Stars><Actor>Johnny Depp</Actor><Actor>Brad Pitt</Actor><Actor>Leonardo DiCaprio</Actor><Actor>Will Smith</Actor><Actor>George Clooney</Actor><Actor>Tom Cruise</Actor><Actor>Matt Damon</Actor><Actor>Orlando Bloom</Actor><Actor>Bruce Willis</Actor><Actor>Steve Carell</Actor><Actress>Jennifer Aniston</Actress><Actress>Jessica Alba</Actress><Actress>Halle Berry</Actress><Actress>Angelina Jolie</Actress><Actress>Sandra Bullock</Actress><Actress>Reese Witherspoon</Actress><Actress>Jennifer Garner</Actress><Actress>Julia Roberts</Actress><Actress>Gwyneth Paltrow</Actress><Actress>Meg Ryan</Actress><Actress>Hillary Swank</Actress><Actress>Uma Thurman</Actress><Actress>Keira Knightley</Actress><Actress>Meryl Streep</Actress><Actress>Cameron Diaz</Actress><Actress>Salma Hayek</Actress><Actress>Penelope Cruz</Actress><Actress>Nicole Kidman</Actress><Actress>Michelle Pfeiffer</Actress><Actress>Drew Barrymore</Actress><Actress>Jennifer Lopez</Actress><Actress>Catherine Zeta-Jones</Actress></Stars></Hollywood>

Structured Data

The StrUtil class in the StringUtils folder provides convenient helper methods to format strings (Format methods) (similar to .NET's String.Format) and split strings (Split methods) back to primitive types.

Formatting Strings

Formatting is basically done through the Format methods.

Element elem;

StrUtil util;
Rectangle rect(10, 20, 100, 200);
elem.SetString( util.Format(L"{0}, {1}, {2}, {3}", rect.X(), rect.Y(), rect.Width(), rect.Height()) );
// elem now contains "10, 20, 100, 200"

Splitting Strings

Before a string is splitted, a strategy need to be selected first. Other than the C string strtok, Boost splitter and regular expression are available as alternative string splitter strategies.

Element elem;

StrUtil util;
StrtokStrategy strTok(L", ");
util.SetSplitStrategy(&strTok); // set a splitting strategyint x = 0;
int y = 0;
int width = 0;
int height = 0;
util.Split( elem.GetString(L""), x, y, width, height ); 

Rectangle rect(x, y, width, height); // instaniate a rectangle using the splitted data.

Aggregation

The following SQL aggregation functions are provided: Count, Minimum, Maximum, Sum and Average. In terms of performance, it would still be better to read the values into your custom data structures and do the aggregation yourself. These functions are meant to be used for the future LINQ-like features. They are not meant to be used by end-users but they are there if user want to use them for aggregation. What is missing is the GroupBy functionality. OrderBy is covered by the Sort method.

Count, Minimum, Maximum, Sum and Average

The Minimum, Maximum, Sum and Average functions take in 2 string parameters. The 1st parameter is name of children and 2nd parameter is the attribute name. The user can leave the 2nd parameter blank if it is not attribute value which he/she wants to aggregate. Min, Max, Sum and Avg returns a 64 bit integer result while MinF, MaxF, SumF and AvgF returns a 32 bit float value and MinD, MaxD, SumD and AvgD returns a 64 bit float value.

usingnamespace Elmax;
Element elem = root[L"aa"][L"bb"]; // bb contains a group of cc elements// cc are the children of bb, dd is child element of cc, whose value will be use for maximum search.
__int64 nMax = elem.Max(L"cc|dd", L"attr");

This is the XML to get the maximum value.

<aa><bb><cc><dd>55</dd></cc><cc><dd>33</dd></cc><cc><dd>22</dd></cc></bb></aa>

Sort

Sorting is done through the Sort method. The 1st parameter is name of children and 2nd is the comparison predicate which can be a lambda. This is not an in-place sort due to MSXML limitation. In-place sort can only be implemented in cross-platform Elmax where the XML nodes are truly managed by Elmax.

usingnamespace Elmax;
Element elem;

collection_t vec = 
elem.Sort(L"cc", [](Element elem1, Element elem2) -> bool
{
	return elem1[L"dd"].GetInt32(0) < elem2[L"dd"].GetInt32(0);
});

Count function takes in a string parameter and a predicate parameter, and return a unsigned integer. The predicate determines whether the element should be counted towards the total.

usingnamespace Elmax;
Element root;

Element elem1 = root[L"aa|bb|cc"].CreateNew();
elem1.SetInt32(11);
Element elem2 = root[L"aa|bb|cc"].CreateNew();
elem2.SetInt32(22);
Element elem3 = root[L"aa|bb|cc"].CreateNew();
elem3.SetInt32(33);

Pred pred;
unsignedint cnt = root[L"aa"][L"bb"].Count(L"cc",  pred);

// Predicate definitionstruct Pred : public std::unary_function<Elmax::Element, bool>
{
	booloperator() (Elmax::Element& ele) 
	{
		if(ele.GetInt32(0)<33)
			returntrue;

		returnfalse;
	}
};

Helper Methods

The helper methods used in this documentation to load and save XML are listed in this section.

Create Empty XML Document

You can use the below methods to create a empty UTF-8 DOM document.

HRESULT CTryoutDlg::CreateAndInitDom(MSXML2::IXMLDOMDocumentPtr& pDoc)
{
    HRESULT hr = pDoc.CreateInstance(__uuidof(MSXML2::DOMDocument30));
    if (SUCCEEDED(hr))
    {
        // these methods should not fail so don't inspect result
        pDoc->async = VARIANT_FALSE;
        pDoc->validateOnParse = VARIANT_FALSE;
        pDoc->resolveExternals = VARIANT_FALSE;
        MSXML2::IXMLDOMProcessingInstructionPtr pi = pDoc->createProcessingInstruction(L"xml", L" version='1.0' encoding='UTF-8'");
        pDoc->appendChild(pi);
    }
    return hr;
}

Load XML Document

You can use the below methods to load the XML from file.

HRESULT CreateAndLoadXml(MSXML2::IXMLDOMDocumentPtr& pDoc, const std::wstring& szFile)
{
    HRESULT hr = pDoc.CreateInstance(__uuidof(MSXML2::DOMDocument30));
    VARIANT_BOOL b = VARIANT_FALSE;
    if (SUCCEEDED(hr))
    {
        variant_t file(szFile.c_str());
        b = pDoc->load(file);
    }
    return b == VARIANT_FALSE ? E_FAIL : S_OK;
}

Save XML Document

You can use the below methods to save the XML.

bool SaveXml(MSXML2::IXMLDOMDocumentPtr& pDoc, const std::wstring& strFilename)
{
    variant_t varFile(szPath);
    return SUCCEEDED(pDoc->save(varFile));
}

Save XML Document with Indentation

You can use the PrettySave method of the Document class to save the XML with the proper indentation and newlines. The method signature is as follows.

//! Save with the indentation and newlines//!//! @param file is file path//! @param xmlVersion is the xml version for the processing instruction, eg, L"1.0"//! @param utf8 specifies it should be saved in utf-8 or utf-16//! @param indent is indentation string used, eg L"\t"bool PrettySave(const std::wstring&amp; file, const std::wstring& xmlVersion, bool utf8, const std::wstring& indent = L"    ");

An example on how to use PrettySave methd.

bool SaveXml(MSXML2::IXMLDOMDocumentPtr& pDoc, const std::wstring& strFilename)
{
    Elmax::Document doc(pDoc);
    return doc.PrettySave(strFilename, L"1.0", true, L"\t");
}

Saving XML without Processing Instruction

Processing instruction usually comes (in the form below) before the rest of the XML elements. Note: if you are using the MS XML to save your XML, do not add the prcessing instruction. This section pertains to NewElement class Save and PrettySave method, not MS XML.

<?xmlversion="1.0"encoding="UTF-8"standalone="yes"?>

For some users, they might not want to save the processing instruction. To do that, very ironically, is to make use of the ProcessingInstruction class.

ProcessingInstruction procInstr(true, true);
root.PrettySave(szPath, procInstr, L"    "); // 4 whitespace as the indentation

The declaration of the ProcessingInstruction's constructor is as below, set noProcessingInstruction to true if you do not want to save the processing instruction.

// Constructorclass ProcessingInstruction
{
public:
    ProcessingInstruction(bool noProcessingInstruction=true, bool noWriteStandalone=true);
    ...
}