added docs. basic handles tests

This commit is contained in:
Lee Thomason (grinliz) 2012-04-04 22:00:07 -07:00
parent 70e9c6b6a0
commit ae209f6aed
3 changed files with 52 additions and 23 deletions

View File

@ -11,8 +11,7 @@ github.com/leethomason/tinyxml2
The online HTML version of these docs: The online HTML version of these docs:
http://grinninglizard.com/tinyxml2docs/index.html http://grinninglizard.com/tinyxml2docs/index.html
Where examples are in the "related pages" tab: Examples are in the "related pages" tab of the HTML docs.
http://grinninglizard.com/tinyxml2docs/pages.html
<h2> What it does. </h2> <h2> What it does. </h2>

View File

@ -1133,7 +1133,7 @@ private:
/** /**
A XMLHandle is a class that wraps a node pointer with null checks; this is A XMLHandle is a class that wraps a node pointer with null checks; this is
an incredibly useful thing. Note that XMLHandle is not part of the TinyXml an incredibly useful thing. Note that XMLHandle is not part of the TinyXML
DOM structure. It is a separate utility class. DOM structure. It is a separate utility class.
Take an example: Take an example:
@ -1150,23 +1150,23 @@ private:
easy to write a *lot* of code that looks like: easy to write a *lot* of code that looks like:
@verbatim @verbatim
TiXmlElement* root = document.FirstChildElement( "Document" ); XMLElement* root = document.FirstChildElement( "Document" );
if ( root ) if ( root )
{ {
TiXmlElement* element = root->FirstChildElement( "Element" ); XMLElement* element = root->FirstChildElement( "Element" );
if ( element ) if ( element )
{ {
TiXmlElement* child = element->FirstChildElement( "Child" ); XMLElement* child = element->FirstChildElement( "Child" );
if ( child ) if ( child )
{ {
TiXmlElement* child2 = child->NextSiblingElement( "Child" ); XMLElement* child2 = child->NextSiblingElement( "Child" );
if ( child2 ) if ( child2 )
{ {
// Finally do something useful. // Finally do something useful.
@endverbatim @endverbatim
And that doesn't even cover "else" cases. TiXmlHandle addresses the verbosity And that doesn't even cover "else" cases. XMLHandle addresses the verbosity
of such code. A TiXmlHandle checks for null pointers so it is perfectly safe of such code. A XMLHandle checks for null pointers so it is perfectly safe
and correct to use: and correct to use:
@verbatim @verbatim
@ -1181,33 +1181,49 @@ private:
It is also safe to copy handles - internally they are nothing more than node pointers. It is also safe to copy handles - internally they are nothing more than node pointers.
@verbatim @verbatim
TiXmlHandle handleCopy = handle; XMLHandle handleCopy = handle;
@endverbatim @endverbatim
See also XMLConstHandle, which is the same as XMLHandle, but operates on const objects.
*/ */
class XMLHandle class XMLHandle
{ {
public: public:
/// Create a handle from any node (at any depth of the tree.) This can be a null pointer. /// Create a handle from any node (at any depth of the tree.) This can be a null pointer.
XMLHandle( XMLNode* _node ) { node = _node; } XMLHandle( XMLNode* _node ) { node = _node; }
/// Create a handle from a node.
XMLHandle( XMLNode& _node ) { node = &_node; } XMLHandle( XMLNode& _node ) { node = &_node; }
/// Copy constructor
XMLHandle( const XMLHandle& ref ) { node = ref.node; } XMLHandle( const XMLHandle& ref ) { node = ref.node; }
/// Assignment
XMLHandle operator=( const XMLHandle& ref ) { node = ref.node; return *this; } XMLHandle operator=( const XMLHandle& ref ) { node = ref.node; return *this; }
/// Get the first child of this handle.
XMLHandle FirstChild() { return XMLHandle( node ? node->FirstChild() : 0 ); } XMLHandle FirstChild() { return XMLHandle( node ? node->FirstChild() : 0 ); }
/// Get the first child element of this handle.
XMLHandle FirstChildElement( const char* value=0 ) { return XMLHandle( node ? node->FirstChildElement( value ) : 0 ); } XMLHandle FirstChildElement( const char* value=0 ) { return XMLHandle( node ? node->FirstChildElement( value ) : 0 ); }
/// Get the last child of this handle.
XMLHandle LastChild() { return XMLHandle( node ? node->LastChild() : 0 ); } XMLHandle LastChild() { return XMLHandle( node ? node->LastChild() : 0 ); }
/// Get the last child element of this handle.
XMLHandle LastChildElement( const char* _value=0 ) { return XMLHandle( node ? node->LastChildElement( _value ) : 0 ); } XMLHandle LastChildElement( const char* _value=0 ) { return XMLHandle( node ? node->LastChildElement( _value ) : 0 ); }
/// Get the previous sibling of this handle.
XMLHandle PreviousSibling() { return XMLHandle( node ? node->PreviousSibling() : 0 ); } XMLHandle PreviousSibling() { return XMLHandle( node ? node->PreviousSibling() : 0 ); }
/// Get the previous sibling element of this handle.
XMLHandle PreviousSiblingElement( const char* _value=0 ) { return XMLHandle( node ? node->PreviousSiblingElement( _value ) : 0 ); } XMLHandle PreviousSiblingElement( const char* _value=0 ) { return XMLHandle( node ? node->PreviousSiblingElement( _value ) : 0 ); }
/// Get the next sibling of this handle.
XMLHandle NextSibling() { return XMLHandle( node ? node->NextSibling() : 0 ); } XMLHandle NextSibling() { return XMLHandle( node ? node->NextSibling() : 0 ); }
/// Get the next sibling element of this handle.
XMLHandle NextSiblingElement( const char* _value=0 ) { return XMLHandle( node ? node->NextSiblingElement( _value ) : 0 ); } XMLHandle NextSiblingElement( const char* _value=0 ) { return XMLHandle( node ? node->NextSiblingElement( _value ) : 0 ); }
/// Safe cast to XMLNode. This can return null.
XMLNode* ToNode() { return node; } XMLNode* ToNode() { return node; }
/// Safe cast to XMLElement. This can return null.
XMLElement* ToElement() { return ( ( node && node->ToElement() ) ? node->ToElement() : 0 ); } XMLElement* ToElement() { return ( ( node && node->ToElement() ) ? node->ToElement() : 0 ); }
/// Safe cast to XMLText. This can return null.
XMLText* ToText() { return ( ( node && node->ToText() ) ? node->ToText() : 0 ); } XMLText* ToText() { return ( ( node && node->ToText() ) ? node->ToText() : 0 ); }
/// Safe cast to XMLUnknown. This can return null.
XMLUnknown* ToUnknown() { return ( ( node && node->ToUnknown() ) ? node->ToUnknown() : 0 ); } XMLUnknown* ToUnknown() { return ( ( node && node->ToUnknown() ) ? node->ToUnknown() : 0 ); }
/// Safe cast to XMLDeclaration. This can return null.
XMLDeclaration* ToDeclaration() { return ( ( node && node->ToDeclaration() ) ? node->ToDeclaration() : 0 ); } XMLDeclaration* ToDeclaration() { return ( ( node && node->ToDeclaration() ) ? node->ToDeclaration() : 0 ); }
private: private:
@ -1216,7 +1232,8 @@ private:
/** /**
A variant of the XMLHandle class for working with const XMLNodes and Documents. A variant of the XMLHandle class for working with const XMLNodes and Documents. It is the
same in all regards, except for the 'const' qualifiers. See XMLHandle for API.
*/ */
class XMLConstHandle class XMLConstHandle
{ {

View File

@ -94,12 +94,12 @@ int example_2()
int example_3() int example_3()
{ {
static const char* xml = static const char* xml =
"<?xml version=\"1.0\"?>" "<?xml version=\"1.0\"?>"
"<!DOCTYPE PLAY SYSTEM \"play.dtd\">" "<!DOCTYPE PLAY SYSTEM \"play.dtd\">"
"<PLAY>" "<PLAY>"
"<TITLE>A Midsummer Night's Dream</TITLE>" "<TITLE>A Midsummer Night's Dream</TITLE>"
"</PLAY>"; "</PLAY>";
XMLDocument doc; XMLDocument doc;
doc.Parse( xml ); doc.Parse( xml );
@ -756,16 +756,29 @@ int main( int /*argc*/, const char ** /*argv*/ )
static const char* xml = "<element attrib='bar'><sub>Text</sub></element>"; static const char* xml = "<element attrib='bar'><sub>Text</sub></element>";
XMLDocument doc; XMLDocument doc;
doc.Parse( xml ); doc.Parse( xml );
const XMLDocument& docC = doc;
XMLElement* ele = XMLHandle( doc ).FirstChildElement( "element" ).FirstChild().ToElement(); XMLElement* ele = XMLHandle( doc ).FirstChildElement( "element" ).FirstChild().ToElement();
XMLTest( "Handle, success, mutable", ele->Value(), "sub" ); XMLTest( "Handle, success, mutable", ele->Value(), "sub" );
const XMLElement* eleC = XMLConstHandle( docC ).FirstChildElement( "element" ).FirstChild().ToElement(); XMLHandle docH( doc );
XMLTest( "Handle, success, mutable", eleC->Value(), "sub" ); ele = docH.FirstChildElement( "none" ).FirstChildElement( "element" ).ToElement();
XMLTest( "Handle, dne, mutable", 0, (int)ele );
} }
{
static const char* xml = "<element attrib='bar'><sub>Text</sub></element>";
XMLDocument doc;
doc.Parse( xml );
XMLConstHandle docH( doc );
const XMLElement* ele = docH.FirstChildElement( "element" ).FirstChild().ToElement();
XMLTest( "Handle, success, const", ele->Value(), "sub" );
ele = docH.FirstChildElement( "none" ).FirstChildElement( "element" ).ToElement();
XMLTest( "Handle, dne, const", 0, (int)ele );
}
// ----------- Performance tracking -------------- // ----------- Performance tracking --------------
{ {