Class XMLElement

Synopsis

#include <tinyxml2.h>

class TINYXML2_LIB XMLElement : public XMLNode

Description

The element is a container class. It has a value, the element name, and can contain other elements, text, comments, and unknowns. Elements also contain an arbitrary number of attributes.

Mentioned in

Inheritance

Ancestors: XMLNode

Methods

AcceptAccept a hierarchical visit of the nodes in the TinyXML-2 DOM
AttributeGiven an attribute name, Attribute() returns the value for the attribute of that name, or null if none exists
BoolAttributeSee IntAttribute()
BoolTextSee QueryIntText()
ClosingType
DeleteAttribute OverloadDelete an attribute.
DoubleAttributeSee IntAttribute()
DoubleTextSee QueryIntText()
FindAttributeQuery a specific attribute in the list.
FirstAttributeReturn the first attribute in the list.
FloatAttributeSee IntAttribute()
FloatTextSee QueryIntText()
GetTextConvenience function for easy access to the text inside an element
InsertNewChildElementConvenience method to create a new XMLElement and add it as last (right) child of this node
InsertNewCommentSee InsertNewChildElement()
InsertNewDeclarationSee InsertNewChildElement()
InsertNewTextSee InsertNewChildElement()
InsertNewUnknownSee InsertNewChildElement()
Int64AttributeSee IntAttribute()
Int64TextSee QueryIntText()
IntAttributeGiven an attribute name, IntAttribute() returns the value of the attribute interpreted as an integer
IntText
NameGet the name of an element (which is the Value() of the node.)
ParseDeep
QueryAttribute OverloadGiven an attribute name, QueryAttribute() returns XML_SUCCESS, XML_WRONG_ATTRIBUTE_TYPE if the conversion can't be performed, or XML_NO_ATTRIBUTE if the attribute doesn't exist
QueryBoolAttributeSee QueryIntAttribute()
QueryBoolTextSee QueryIntText()
QueryDoubleAttributeSee QueryIntAttribute()
QueryDoubleTextSee QueryIntText()
QueryFloatAttributeSee QueryIntAttribute()
QueryFloatTextSee QueryIntText()
QueryInt64AttributeSee QueryIntAttribute()
QueryInt64TextSee QueryIntText()
QueryIntAttributeGiven an attribute name, QueryIntAttribute() returns XML_SUCCESS, XML_WRONG_ATTRIBUTE_TYPE if the conversion can't be performed, or XML_NO_ATTRIBUTE if the attribute doesn't exist
QueryIntTextConvenience method to query the value of a child text node
QueryStringAttributeSee QueryIntAttribute()
QueryUnsigned64AttributeSee QueryIntAttribute()
QueryUnsigned64TextSee QueryIntText()
QueryUnsignedAttributeSee QueryIntAttribute()
QueryUnsignedTextSee QueryIntText()
SetAttribute OverloadSets the named attribute to value.
SetNameSet the name of the element.
SetText OverloadConvenience function for easy access to the text inside an element
SetText OverloadConvenience method for setting text inside an element. See SetText() for important limitations.
ShallowCloneMake a copy of this node, but not its children
ShallowEqualTest if 2 nodes are the same, but don't test children
ToElement OverloadSafely cast to an Element, or null.
Unsigned64AttributeSee IntAttribute()
Unsigned64TextSee QueryIntText()
UnsignedAttributeSee IntAttribute()
UnsignedTextSee QueryIntText()

Source

Lines 1263-1701 in tinyxml2.h.

class TINYXML2_LIB XMLElement : public XMLNode
{
    friend class XMLDocument;
public:
    /// Get the name of an element (which is the Value() of the node.)
    const char* Name() const        {
        return Value();
    }
    /// Set the name of the element.
    void SetName( const char* str, bool staticMem=false )   {
        SetValue( str, staticMem );
    }

    virtual XMLElement* ToElement()             {
        return this;
    }
    virtual const XMLElement* ToElement() const {
        return this;
    }
    virtual bool Accept( XMLVisitor* visitor ) const;

    /** Given an attribute name, Attribute() returns the value
        for the attribute of that name, or null if none
        exists. For example:

        @verbatim
        const char* value = ele->Attribute( "foo" );
        @endverbatim

        The 'value' parameter is normally null. However, if specified,
        the attribute will only be returned if the 'name' and 'value'
        match. This allow you to write code:

        @verbatim
        if ( ele->Attribute( "foo", "bar" ) ) callFooIsBar();
        @endverbatim

        rather than:
        @verbatim
        if ( ele->Attribute( "foo" ) ) {
            if ( strcmp( ele->Attribute( "foo" ), "bar" ) == 0 ) callFooIsBar();
        }
        @endverbatim
    */
    const char* Attribute( const char* name, const char* value=0 ) const;

    /** Given an attribute name, IntAttribute() returns the value
        of the attribute interpreted as an integer. The default
        value will be returned if the attribute isn't present,
        or if there is an error. (For a method with error
        checking, see QueryIntAttribute()).
    */
    int IntAttribute(const char* name, int defaultValue = 0) const;
    /// See IntAttribute()
    unsigned UnsignedAttribute(const char* name, unsigned defaultValue = 0) const;
    /// See IntAttribute()
    int64_t Int64Attribute(const char* name, int64_t defaultValue = 0) const;
    /// See IntAttribute()
    uint64_t Unsigned64Attribute(const char* name, uint64_t defaultValue = 0) const;
    /// See IntAttribute()
    bool BoolAttribute(const char* name, bool defaultValue = false) const;
    /// See IntAttribute()
    double DoubleAttribute(const char* name, double defaultValue = 0) const;
    /// See IntAttribute()
    float FloatAttribute(const char* name, float defaultValue = 0) const;

    /** Given an attribute name, QueryIntAttribute() returns
        XML_SUCCESS, XML_WRONG_ATTRIBUTE_TYPE if the conversion
        can't be performed, or XML_NO_ATTRIBUTE if the attribute
        doesn't exist. If successful, the result of the conversion
        will be written to 'value'. If not successful, nothing will
        be written to 'value'. This allows you to provide default
        value:

        @verbatim
        int value = 10;
        QueryIntAttribute( "foo", &value );       // if "foo" isn't found, value will still be 10
        @endverbatim
    */
    XMLError QueryIntAttribute( const char* name, int* value ) const                {
        const XMLAttribute* a = FindAttribute( name );
        if ( !a ) {
            return XML_NO_ATTRIBUTE;
        }
        return a->QueryIntValue( value );
    }

    /// See QueryIntAttribute()
    XMLError QueryUnsignedAttribute( const char* name, unsigned int* value ) const  {
        const XMLAttribute* a = FindAttribute( name );
        if ( !a ) {
            return XML_NO_ATTRIBUTE;
        }
        return a->QueryUnsignedValue( value );
    }

    /// See QueryIntAttribute()
    XMLError QueryInt64Attribute(const char* name, int64_t* value) const {
        const XMLAttribute* a = FindAttribute(name);
        if (!a) {
            return XML_NO_ATTRIBUTE;
        }
        return a->QueryInt64Value(value);
    }

    /// See QueryIntAttribute()
    XMLError QueryUnsigned64Attribute(const char* name, uint64_t* value) const {
        const XMLAttribute* a = FindAttribute(name);
        if(!a) {
            return XML_NO_ATTRIBUTE;
        }
        return a->QueryUnsigned64Value(value);
    }

    /// See QueryIntAttribute()
    XMLError QueryBoolAttribute( const char* name, bool* value ) const              {
        const XMLAttribute* a = FindAttribute( name );
        if ( !a ) {
            return XML_NO_ATTRIBUTE;
        }
        return a->QueryBoolValue( value );
    }
    /// See QueryIntAttribute()
    XMLError QueryDoubleAttribute( const char* name, double* value ) const          {
        const XMLAttribute* a = FindAttribute( name );
        if ( !a ) {
            return XML_NO_ATTRIBUTE;
        }
        return a->QueryDoubleValue( value );
    }
    /// See QueryIntAttribute()
    XMLError QueryFloatAttribute( const char* name, float* value ) const            {
        const XMLAttribute* a = FindAttribute( name );
        if ( !a ) {
            return XML_NO_ATTRIBUTE;
        }
        return a->QueryFloatValue( value );
    }

    /// See QueryIntAttribute()
    XMLError QueryStringAttribute(const char* name, const char** value) const {
        const XMLAttribute* a = FindAttribute(name);
        if (!a) {
            return XML_NO_ATTRIBUTE;
        }
        *value = a->Value();
        return XML_SUCCESS;
    }



    /** Given an attribute name, QueryAttribute() returns
        XML_SUCCESS, XML_WRONG_ATTRIBUTE_TYPE if the conversion
        can't be performed, or XML_NO_ATTRIBUTE if the attribute
        doesn't exist. It is overloaded for the primitive types,
        and is a generally more convenient replacement of
        QueryIntAttribute() and related functions.

        If successful, the result of the conversion
        will be written to 'value'. If not successful, nothing will
        be written to 'value'. This allows you to provide default
        value:

        @verbatim
        int value = 10;
        QueryAttribute( "foo", &value );      // if "foo" isn't found, value will still be 10
        @endverbatim
    */
    XMLError QueryAttribute( const char* name, int* value ) const {
        return QueryIntAttribute( name, value );
    }

    XMLError QueryAttribute( const char* name, unsigned int* value ) const {
        return QueryUnsignedAttribute( name, value );
    }

    XMLError QueryAttribute(const char* name, int64_t* value) const {
        return QueryInt64Attribute(name, value);
    }

    XMLError QueryAttribute(const char* name, uint64_t* value) const {
        return QueryUnsigned64Attribute(name, value);
    }

    XMLError QueryAttribute( const char* name, bool* value ) const {
        return QueryBoolAttribute( name, value );
    }

    XMLError QueryAttribute( const char* name, double* value ) const {
        return QueryDoubleAttribute( name, value );
    }

    XMLError QueryAttribute( const char* name, float* value ) const {
        return QueryFloatAttribute( name, value );
    }

    XMLError QueryAttribute(const char* name, const char** value) const {
        return QueryStringAttribute(name, value);
    }

    /// Sets the named attribute to value.
    void SetAttribute( const char* name, const char* value )    {
        XMLAttribute* a = FindOrCreateAttribute( name );
        a->SetAttribute( value );
    }
    /// Sets the named attribute to value.
    void SetAttribute( const char* name, int value )            {
        XMLAttribute* a = FindOrCreateAttribute( name );
        a->SetAttribute( value );
    }
    /// Sets the named attribute to value.
    void SetAttribute( const char* name, unsigned value )       {
        XMLAttribute* a = FindOrCreateAttribute( name );
        a->SetAttribute( value );
    }

    /// Sets the named attribute to value.
    void SetAttribute(const char* name, int64_t value) {
        XMLAttribute* a = FindOrCreateAttribute(name);
        a->SetAttribute(value);
    }

    /// Sets the named attribute to value.
    void SetAttribute(const char* name, uint64_t value) {
        XMLAttribute* a = FindOrCreateAttribute(name);
        a->SetAttribute(value);
    }

    /// Sets the named attribute to value.
    void SetAttribute( const char* name, bool value )           {
        XMLAttribute* a = FindOrCreateAttribute( name );
        a->SetAttribute( value );
    }
    /// Sets the named attribute to value.
    void SetAttribute( const char* name, double value )     {
        XMLAttribute* a = FindOrCreateAttribute( name );
        a->SetAttribute( value );
    }
    /// Sets the named attribute to value.
    void SetAttribute( const char* name, float value )      {
        XMLAttribute* a = FindOrCreateAttribute( name );
        a->SetAttribute( value );
    }

    /**
        Delete an attribute.
    */
    void DeleteAttribute( const char* name );

    /// Return the first attribute in the list.
    const XMLAttribute* FirstAttribute() const {
        return _rootAttribute;
    }
    /// Query a specific attribute in the list.
    const XMLAttribute* FindAttribute( const char* name ) const;

    /** Convenience function for easy access to the text inside an element. Although easy
        and concise, GetText() is limited compared to getting the XMLText child
        and accessing it directly.

        If the first child of 'this' is a XMLText, the GetText()
        returns the character string of the Text node, else null is returned.

        This is a convenient method for getting the text of simple contained text:
        @verbatim
        <foo>This is text</foo>
            const char* str = fooElement->GetText();
        @endverbatim

        'str' will be a pointer to "This is text".

        Note that this function can be misleading. If the element foo was created from
        this XML:
        @verbatim
            <foo><b>This is text</b></foo>
        @endverbatim

        then the value of str would be null. The first child node isn't a text node, it is
        another element. From this XML:
        @verbatim
            <foo>This is <b>text</b></foo>
        @endverbatim
        GetText() will return "This is ".
    */
    const char* GetText() const;

    /** Convenience function for easy access to the text inside an element. Although easy
        and concise, SetText() is limited compared to creating an XMLText child
        and mutating it directly.

        If the first child of 'this' is a XMLText, SetText() sets its value to
        the given string, otherwise it will create a first child that is an XMLText.

        This is a convenient method for setting the text of simple contained text:
        @verbatim
        <foo>This is text</foo>
            fooElement->SetText( "Hullaballoo!" );
        <foo>Hullaballoo!</foo>
        @endverbatim

        Note that this function can be misleading. If the element foo was created from
        this XML:
        @verbatim
            <foo><b>This is text</b></foo>
        @endverbatim

        then it will not change "This is text", but rather prefix it with a text element:
        @verbatim
            <foo>Hullaballoo!<b>This is text</b></foo>
        @endverbatim

        For this XML:
        @verbatim
            <foo />
        @endverbatim
        SetText() will generate
        @verbatim
            <foo>Hullaballoo!</foo>
        @endverbatim
    */
    void SetText( const char* inText );
    /// Convenience method for setting text inside an element. See SetText() for important limitations.
    void SetText( int value );
    /// Convenience method for setting text inside an element. See SetText() for important limitations.
    void SetText( unsigned value );
    /// Convenience method for setting text inside an element. See SetText() for important limitations.
    void SetText(int64_t value);
    /// Convenience method for setting text inside an element. See SetText() for important limitations.
    void SetText(uint64_t value);
    /// Convenience method for setting text inside an element. See SetText() for important limitations.
    void SetText( bool value );
    /// Convenience method for setting text inside an element. See SetText() for important limitations.
    void SetText( double value );
    /// Convenience method for setting text inside an element. See SetText() for important limitations.
    void SetText( float value );

    /**
        Convenience method to query the value of a child text node. This is probably best
        shown by example. Given you have a document is this form:
        @verbatim
            <point>
                <x>1</x>
                <y>1.4</y>
            </point>
        @endverbatim

        The QueryIntText() and similar functions provide a safe and easier way to get to the
        "value" of x and y.

        @verbatim
            int x = 0;
            float y = 0;    // types of x and y are contrived for example
            const XMLElement* xElement = pointElement->FirstChildElement( "x" );
            const XMLElement* yElement = pointElement->FirstChildElement( "y" );
            xElement->QueryIntText( &x );
            yElement->QueryFloatText( &y );
        @endverbatim

        @returns XML_SUCCESS (0) on success, XML_CAN_NOT_CONVERT_TEXT if the text cannot be converted
                 to the requested type, and XML_NO_TEXT_NODE if there is no child text to query.

    */
    XMLError QueryIntText( int* ival ) const;
    /// See QueryIntText()
    XMLError QueryUnsignedText( unsigned* uval ) const;
    /// See QueryIntText()
    XMLError QueryInt64Text(int64_t* uval) const;
    /// See QueryIntText()
    XMLError QueryUnsigned64Text(uint64_t* uval) const;
    /// See QueryIntText()
    XMLError QueryBoolText( bool* bval ) const;
    /// See QueryIntText()
    XMLError QueryDoubleText( double* dval ) const;
    /// See QueryIntText()
    XMLError QueryFloatText( float* fval ) const;

    int IntText(int defaultValue = 0) const;

    /// See QueryIntText()
    unsigned UnsignedText(unsigned defaultValue = 0) const;
    /// See QueryIntText()
    int64_t Int64Text(int64_t defaultValue = 0) const;
    /// See QueryIntText()
    uint64_t Unsigned64Text(uint64_t defaultValue = 0) const;
    /// See QueryIntText()
    bool BoolText(bool defaultValue = false) const;
    /// See QueryIntText()
    double DoubleText(double defaultValue = 0) const;
    /// See QueryIntText()
    float FloatText(float defaultValue = 0) const;

    /**
        Convenience method to create a new XMLElement and add it as last (right)
        child of this node. Returns the created and inserted element.
    */
    XMLElement* InsertNewChildElement(const char* name);
    /// See InsertNewChildElement()
    XMLComment* InsertNewComment(const char* comment);
    /// See InsertNewChildElement()
    XMLText* InsertNewText(const char* text);
    /// See InsertNewChildElement()
    XMLDeclaration* InsertNewDeclaration(const char* text);
    /// See InsertNewChildElement()
    XMLUnknown* InsertNewUnknown(const char* text);


    // internal:
    enum ElementClosingType {
        OPEN,       // <foo>
        CLOSED,     // <foo/>
        CLOSING     // </foo>
    };
    ElementClosingType ClosingType() const {
        return _closingType;
    }
    virtual XMLNode* ShallowClone( XMLDocument* document ) const;
    virtual bool ShallowEqual( const XMLNode* compare ) const;

protected:
    char* ParseDeep( char* p, StrPair* parentEndTag, int* curLineNumPtr );

private:
    XMLElement( XMLDocument* doc );
    virtual ~XMLElement();
    XMLElement( const XMLElement& );    // not supported
    void operator=( const XMLElement& );    // not supported

    XMLAttribute* FindOrCreateAttribute( const char* name );
    char* ParseAttributes( char* p, int* curLineNumPtr );
    static void DeleteAttribute( XMLAttribute* attribute );
    XMLAttribute* CreateAttribute();

    enum { BUF_SIZE = 200 };
    ElementClosingType _closingType;
    // The attribute list is ordered; there is no 'lastAttribute'
    // because the list needs to be scanned for dupes before adding
    // a new attribute.
    XMLAttribute* _rootAttribute;
};





Add Discussion as Guest

Log in