#include <cXmlHandle.h>

Inheritance diagram for GrayLib::cXmlHandle:

Public Member Functions
	cXmlHandle (cXmlNode *pNode)

	cXmlHandle (const cXmlHandle &ref)

cXmlHandle &	operator= (const cXmlHandle &ref)

cXmlHandle	get_Head () const

cXmlHandle	GetChildFirst (const char *value) const

cXmlHandle	get_FirstChildElement () const

cXmlHandle	GetFirstChildElement (const char *value) const

cXmlHandle	GetChild (int index) const

cXmlHandle	GetChild (const char *value, int index) const

cXmlHandle	GetChildElement (int index) const

cXmlHandle	GetChildElement (const char *value, int index) const

cXmlNode *	ToNode () const

cXmlElement *	ToElement () const

cXmlText *	ToText () const

cXmlUnknown *	ToUnknown () const

Public Member Functions inherited from Gray::cPtrFacade< cXmlNode >
	cPtrFacade (cXmlNode *p=nullptr) noexcept

	cPtrFacade (THIS_t &&ref) noexcept

bool	isValidPtr () const noexcept

cXmlNode **	get_PPtr ()

cXmlNode *	get_Ptr () const noexcept

void	put_Ptr (cXmlNode *p) noexcept

void	ReleasePtr () noexcept

void	AttachPtr (cXmlNode *p) noexcept

cXmlNode *	DetachPtr () noexcept

THIS_t &	operator= (cXmlNode *p) noexcept

THIS_t &	operator= (THIS_t &&ref) noexcept

	operator cXmlNode * () const noexcept

cXmlNode &	get_Ref () const

cXmlNode &	operator* () const

cXmlNode *	operator-> () const

bool	operator! () const noexcept
	Comparison ops. More...

bool	operator!= (cXmlNode *p2) const noexcept

bool	operator== (cXmlNode *p2) const noexcept

Additional Inherited Members
Public Types inherited from GrayLib::cXml
enum	XMLNODE_TYPE { XMLNODE_QTY }

Static Public Member Functions inherited from GrayLib::cXml
static StrLen_t GRAYCALL	ParseMicrosoftBOM (const BYTE *pszData)

static bool GRAYCALL	IsXML (const IniChar_t *pszStr, StrLen_t iLenMax=StrT::k_LEN_MAX)

static cXmlString GRAYCALL	GetAttributeStr (const IniChar_t *pszName, const cXmlString &sValue)

static void	AddPathElement (cXmlString &sPath, const cXmlString &sElement)

static void	RemovePathElement (cXmlString &sPath, const cXmlString &sElement)

Static Public Attributes inherited from GrayLib::cXml
static const char	k_xmlHeader [6] = "<?xml"
	"<?xml" // not case sensitive ! More...

static const char	k_xmlEnd [3] = "?>"
	"?>" More...

static const char	k_commentHeader [5] = "<!--"
	"<!--" // comments are not reentrant! More...

static const char	k_commentEnd [4] = "-->"
	"-->" More...

static const char	k_cdataHeader [10] = "<![CDATA["
	"<![CDATA[" More...

static const char	k_cdataEnd [4] = "]]>"
	"]]>" More...

static const char	k_dtdHeader [3] = "<!"
	"<!" More...

Protected Attributes inherited from Gray::cPtrFacade< cXmlNode >
cXmlNode *	m_p
	Pointer to some object of TYPE. More...

Detailed Description

A cXmlHandle is a class that (safely) wraps a cXmlNode pointer with nullptr checks; Similar to CVarHandle Note that cXmlHandle is not part of the cXml DOM structure. It is a separate utility class.

Take an example:

//!     <Document>
//!             <Element attributeA = "valueA">
//!                     <Child attributeB = "value1" />
//!                     <Child attributeB = "value2" />
//!             </Element>
//!     <Document>
//!

    Assuming you want the value of "attributeB" in the 2nd "Child" element, it's very
    easy to write a *lot* of code that looks like:

@verbatim

//! cXmlElement* root = document.FirstChildElement( "Document" ); //! if ( root ) //! { //! cXmlElement* element = root->FirstChildElement( "Element" ); //! if ( element ) //! { //! cXmlElement* child = element->FirstChildElement( "Child" ); //! if ( child ) //! { //! cXmlElement* child2 = child->NextSiblingElement( "Child" ); //! if ( child2 ) //! { //! // Finally do something useful. //!

    And that doesn't even cover "else" cases. cXmlHandle addresses the verbosity
    of such code. A cXmlHandle checks for null      pointers so it is perfectly safe
    and correct to use:

@verbatim

//! cXmlHandle docHandle( &document ); //! cXmlElement* child2 = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", 1 ).ToElement(); //! if ( child2 ) //! { //! // do something useful //!

Which is MUCH more concise and useful.

 It is also safe to copy handles - internally they are nothing more than node pointers.
@verbatim

//! cXmlHandle handleCopy = handle; //!

What they should not be used for is iteration:

@verbatim

//! int i=0; //! while ( true ) //! { //! cXmlElement* child = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", i ).ToElement(); //! if ( !child ) //! break; //! // do something //! ++i; //! } //!

    It seems reasonable, but it is in fact two embedded while loops. The Child method is
 a linear walk to find the element, so this code would iterate much more than it needs
    to. Instead, prefer:

@verbatim

//! cXmlElement* child = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).FirstChild( "Child" ).ToElement(); //! //! for( child; child; child=child->NextSiblingElement()) //! { //! // do something //! } //!

Constructor & Destructor Documentation

◆ cXmlHandle() [1/2]

GrayLib::cXmlHandle::cXmlHandle ( cXmlNode * pNode )

inline

Create a handle from any node (at any depth of the tree.) This can be a null pointer.

◆ cXmlHandle() [2/2]

GrayLib::cXmlHandle::cXmlHandle ( const cXmlHandle & ref )

inline

Copy constructor

Member Function Documentation

◆ get_FirstChildElement()

cXmlHandle GrayLib::cXmlHandle::get_FirstChildElement ( ) const

Return a handle to the first child element.

◆ get_Head()

cXmlHandle GrayLib::cXmlHandle::get_Head ( void ) const

Return a handle to the first child node in a container.

◆ GetChild() [1/2]

cXmlHandle GrayLib::cXmlHandle::GetChild	(	const char *	value,
		int	index
	)		const

Return a handle to the "index" child with the given name. The first child is 0, the second 1, etc.

◆ GetChild() [2/2]

cXmlHandle GrayLib::cXmlHandle::GetChild ( int index ) const

Return a handle to the "index" child. The first child is 0, the second 1, etc.

◆ GetChildElement() [1/2]

cXmlHandle GrayLib::cXmlHandle::GetChildElement	(	const char *	value,
		int	index
	)		const

Return a handle to the "index" child element with the given name. The first child element is 0, the second 1, etc. Note that only cXmlElements are indexed: other types are not counted.

◆ GetChildElement() [2/2]

cXmlHandle GrayLib::cXmlHandle::GetChildElement ( int index ) const

Return a handle to the "index" child element. The first child element is 0, the second 1, etc. Note that only cXmlElements are indexed: other types are not counted.

◆ GetChildFirst()

cXmlHandle GrayLib::cXmlHandle::GetChildFirst ( const char * value ) const

Return a handle to the first child node with the given name.

◆ GetFirstChildElement()

cXmlHandle GrayLib::cXmlHandle::GetFirstChildElement ( const char * value ) const

Return a handle to the first child element with the given name.

◆ operator=()

cXmlHandle& GrayLib::cXmlHandle::operator= ( const cXmlHandle & ref )

inline

◆ ToElement()

cXmlElement* GrayLib::cXmlHandle::ToElement ( ) const

inline

Return the handle as a cXmlElement. This may return null.

◆ ToNode()

cXmlNode* GrayLib::cXmlHandle::ToNode ( ) const

inline

Return the handle as a cXmlNode. This may return null. TODO Operator ?

◆ ToText()

cXmlText* GrayLib::cXmlHandle::ToText ( ) const

inline

Return the handle as a cXmlText. This may return null.

◆ ToUnknown()

cXmlUnknown* GrayLib::cXmlHandle::ToUnknown ( ) const

inline

Return the handle as a cXmlUnknown. This may return null.

The documentation for this class was generated from the following files:

c:/Dennis/Source/Gray/GrayLib/include/Xml/cXmlHandle.h
c:/Dennis/Source/Gray/GrayLib/src/Xml/cXmlHandle.cpp

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ cXmlHandle() [1/2]

◆ cXmlHandle() [2/2]

Member Function Documentation

◆ get_FirstChildElement()

◆ get_Head()

◆ GetChild() [1/2]

◆ GetChild() [2/2]

◆ GetChildElement() [1/2]

◆ GetChildElement() [2/2]

◆ GetChildFirst()

◆ GetFirstChildElement()

◆ operator=()

◆ ToElement()

◆ ToNode()

◆ ToText()

◆ ToUnknown()