gloox  1.0.20
Classes | Public Types | Public Member Functions | List of all members
Tag Class Reference

#include <tag.h>

Classes

class  Attribute
 

Public Types

typedef std::list< Attribute * > AttributeList
 

Public Member Functions

 Tag (const std::string &name, const std::string &cdata=EmptyString)
 
 Tag (Tag *parent, const std::string &name, const std::string &cdata=EmptyString)
 
 Tag (const std::string &name, const std::string &attrib, const std::string &value)
 
 Tag (Tag *parent, const std::string &name, const std::string &attrib, const std::string &value)
 
virtual ~Tag ()
 
const std::string xml () const
 
bool setPrefix (const std::string &prefix)
 
const std::string & prefix () const
 
const std::string & prefix (const std::string &xmlns) const
 
bool setXmlns (const std::string &xmlns, const std::string &prefix=EmptyString)
 
const std::string xmlns () const
 
const std::string xmlns (const std::string &prefix) const
 
bool addAttribute (Attribute *attr)
 
bool addAttribute (const std::string &name, const std::string &value)
 
bool addAttribute (const std::string &name, int value)
 
bool addAttribute (const std::string &name, long value)
 
void setAttributes (const AttributeList &attributes)
 
void addChild (Tag *child)
 
void addChildCopy (const Tag *child)
 
bool setCData (const std::string &cdata)
 
bool addCData (const std::string &cdata)
 
const std::string & name () const
 
const std::string cdata () const
 
const AttributeListattributes () const
 
const TagListchildren () const
 
const std::string & findAttribute (const std::string &name) const
 
bool hasAttribute (const std::string &name, const std::string &value=EmptyString) const
 
TagfindChild (const std::string &name) const
 
TagfindChild (const std::string &name, const std::string &attr, const std::string &value=EmptyString) const
 
bool hasChild (const std::string &name, const std::string &attr=EmptyString, const std::string &value=EmptyString) const
 
TagfindChildWithAttrib (const std::string &attr, const std::string &value=EmptyString) const
 
bool hasChildWithAttrib (const std::string &attr, const std::string &value=EmptyString) const
 
TagList findChildren (const std::string &name, const std::string &xmlns=EmptyString) const
 
void removeChild (const std::string &name, const std::string &xmlns=EmptyString)
 
void removeChild (Tag *tag)
 
void removeAttribute (const std::string &attr, const std::string &value=EmptyString, const std::string &xmlns=EmptyString)
 
bool hasChildWithCData (const std::string &name, const std::string &cdata) const
 
Tagparent () const
 
Tagclone () const
 
const std::string findCData (const std::string &expression) const
 
const TagfindTag (const std::string &expression) const
 
ConstTagList findTagList (const std::string &expression) const
 
bool operator== (const Tag &right) const
 
bool operator!= (const Tag &right) const
 
 operator bool () const
 

Detailed Description

This is an abstraction of an XML element.

Note
Use setXmlns() to set namespaces and namespace prefixes.
Author
Jakob Schröter js@ca.nosp@m.maya.nosp@m..net
Since
0.4

Definition at line 46 of file tag.h.

Member Typedef Documentation

◆ AttributeList

typedef std::list<Attribute*> AttributeList

A list of XML element attributes.

Definition at line 187 of file tag.h.

Constructor & Destructor Documentation

◆ Tag() [1/4]

Tag ( const std::string &  name,
const std::string &  cdata = EmptyString 
)

Creates a new tag with a given name (and XML character data, if given).

Parameters
nameThe name of the element.
cdataThe XML character data of the element.

Definition at line 139 of file tag.cpp.

◆ Tag() [2/4]

Tag ( Tag parent,
const std::string &  name,
const std::string &  cdata = EmptyString 
)

Creates a new tag as a child tag of the given parent, with a given name (and XML character data, if given).

Parameters
parentThe parent tag.
nameThe name of the element.
cdataThe XML character data of the element.

Definition at line 150 of file tag.cpp.

◆ Tag() [3/4]

Tag ( const std::string &  name,
const std::string &  attrib,
const std::string &  value 
)

Creates a new tag with a given name and an attribute.

Parameters
nameThe name of the element.
attribThe attribute name.
valueThe attribute value.

Definition at line 164 of file tag.cpp.

◆ Tag() [4/4]

Tag ( Tag parent,
const std::string &  name,
const std::string &  attrib,
const std::string &  value 
)

Creates a new tag as a child tag of the given parent, with a given name and an attribute.

Parameters
parentThe parent tag.
nameThe name of the element.
attribThe attribute name.
valueThe attribute value.

Definition at line 177 of file tag.cpp.

◆ ~Tag()

~Tag ( )
virtual

Virtual destructor.

Definition at line 229 of file tag.cpp.

Member Function Documentation

◆ addAttribute() [1/4]

bool addAttribute ( Attribute attr)

Use this function to add a new attribute to the tag. The Tag will become the owner of the Attribute and take care of deletion. If an Attribute with the same name already exists, it will be replaced by the new one.

Parameters
attrA pointer to the attribute to add.
Returns
True if the input is valid UTF-8, false otherwise. Invalid input will be ignored.
Since
1.0
Note
Do not use this function to set XML namespaces, use setXmlns() instead.

Definition at line 354 of file tag.cpp.

◆ addAttribute() [2/4]

bool addAttribute ( const std::string &  name,
const std::string &  value 
)

Use this function to add a new attribute to the tag.

Parameters
nameThe name of the attribute.
valueThe value of the attribute.
Note
Do not use this function to set XML namespaces, use setXmlns() instead.
Returns
True if the input is valid UTF-8, false otherwise. Invalid input will be ignored.

Definition at line 385 of file tag.cpp.

◆ addAttribute() [3/4]

bool addAttribute ( const std::string &  name,
int  value 
)

Use this function to add a new attribute to the tag. The value is an int here.

Parameters
nameThe name of the attribute.
valueThe value of the attribute.
Note
Do not use this function to set XML namespaces, use setXmlns() instead.
Returns
True if the input is valid UTF-8, false otherwise. Invalid input will be ignored.
Since
0.8

Definition at line 393 of file tag.cpp.

◆ addAttribute() [4/4]

bool addAttribute ( const std::string &  name,
long  value 
)

Use this function to add a new attribute to the tag. The value is a long here.

Parameters
nameThe name of the attribute.
valueThe value of the attribute.
Returns
True if the input is valid UTF-8, false otherwise. Invalid input will be ignored.
Note
Do not use this function to set XML namespaces, use setXmlns() instead.
Since
0.9

Definition at line 401 of file tag.cpp.

◆ addCData()

bool addCData ( const std::string &  cdata)

Adds the string to the existing XML character data for this Tag.

Parameters
cdataThe additional cdata.
Returns
True if the input is valid UTF-8, false otherwise. Invalid input will be ignored.

Definition at line 481 of file tag.cpp.

◆ addChild()

void addChild ( Tag child)

Use this function to add a child node to the tag. The Tag will be owned by Tag.

Parameters
childThe node to be inserted.

Definition at line 424 of file tag.cpp.

◆ addChildCopy()

void addChildCopy ( const Tag child)

Use this function to add a copy of the given element to the tag.

Parameters
childThe node to be inserted.
Since
0.9

Definition at line 439 of file tag.cpp.

◆ attributes()

const Tag::AttributeList & attributes ( ) const

Use this function to fetch a const list of attributes.

Returns
A constant reference to the list of attributes.

Definition at line 516 of file tag.cpp.

◆ cdata()

const std::string cdata ( ) const

Use this function to retrieve the XML character data of an element.

Returns
The cdata the element contains.

Definition at line 497 of file tag.cpp.

◆ children()

const TagList & children ( ) const

Use this function to fetch a const list of child elements.

Returns
A constant reference to the list of child elements.

Definition at line 510 of file tag.cpp.

◆ clone()

Tag * clone ( ) const

This function creates a deep copy of this Tag.

Returns
An independent copy of the Tag.
Since
0.7

Definition at line 670 of file tag.cpp.

◆ findAttribute()

const std::string & findAttribute ( const std::string &  name) const

This function can be used to retrieve the value of a Tag's attribute.

Parameters
nameThe name of the attribute to look for.
Returns
The value of the attribute if found, an empty string otherwise.

Definition at line 589 of file tag.cpp.

◆ findCData()

const std::string findCData ( const std::string &  expression) const

Evaluates the given XPath expression and returns the result Tag's character data, if any. If more than one Tag match, only the first one's character data is returned.

Note
Currently, XPath support is somewhat limited. However, it should be useable for basic expressions. For now, see src/tests/xpath/xpath_test.cpp for supported expressions.
Parameters
expressionAn XPath expression to evaluate.
Returns
A matched Tag's character data, or the empty string.
Since
1.0

Definition at line 799 of file tag.cpp.

◆ findChild() [1/2]

Tag * findChild ( const std::string &  name) const

This function finds and returns the first element within the child elements of the current tag that has a matching tag name.

Parameters
nameThe name of the element to search for.
Returns
The found Tag, or 0.

Definition at line 624 of file tag.cpp.

◆ findChild() [2/2]

Tag * findChild ( const std::string &  name,
const std::string &  attr,
const std::string &  value = EmptyString 
) const

This function finds and returns the first element within the child elements of the current tag, that has a certain name, and a certain attribute with a certain value.

Parameters
nameThe name of the element to search for.
attrThe name of the attribute of the child element.
valueThe value of the attribute of the child element.
Returns
The found Tag, or 0.

Definition at line 635 of file tag.cpp.

◆ findChildren()

TagList findChildren ( const std::string &  name,
const std::string &  xmlns = EmptyString 
) const

Returns a list of child tags of the current tag with the given name.

Parameters
nameThe name of the tags to look for.
xmlnsAn optional namespace to check for.
Returns
A list of tags with the given name.
Note
The tags are still linked to the current Tag and should not be deleted.
Since
0.9

Definition at line 714 of file tag.cpp.

◆ findChildWithAttrib()

Tag * findChildWithAttrib ( const std::string &  attr,
const std::string &  value = EmptyString 
) const

This function checks whether the Tag has a child element which posesses a given attribute with an optional value. The name of the child element does not matter.

Parameters
attrThe name of the attribute of the child element.
valueThe value of the attribute of the child element.
Returns
The child if found, 0 otherwise.

Definition at line 659 of file tag.cpp.

◆ findTag()

const Tag * findTag ( const std::string &  expression) const

Evaluates the given XPath expression and returns the result Tag. If more than one Tag match, only the first one is returned.

Note
Currently, XPath support is somewhat limited. However, it should be useable for basic expressions. For now, see src/tests/xpath/xpath_test.cpp for supported expressions.
Parameters
expressionAn XPath expression to evaluate.
Returns
A matched Tag, or 0.
Since
0.9

Definition at line 805 of file tag.cpp.

◆ findTagList()

ConstTagList findTagList ( const std::string &  expression) const

Evaluates the given XPath expression and returns the matched Tags.

Note
Currently, XPath support is somewhat limited. However, it should be useable for basic expressions. For now, see src/tests/xpath/xpath_test.cpp for supported expressions.
Parameters
expressionAn XPath expression to evaluate.
Returns
A list of matched Tags, or an empty TagList.
Since
0.9

Definition at line 811 of file tag.cpp.

◆ hasAttribute()

bool hasAttribute ( const std::string &  name,
const std::string &  value = EmptyString 
) const

Checks whether the tag has a attribute with given name and optional value.

Parameters
nameThe name of the attribute to check for.
valueThe value of the attribute to check for.
Returns
Whether the attribute exists (optionally with the given value).

Definition at line 602 of file tag.cpp.

◆ hasChild()

bool hasChild ( const std::string &  name,
const std::string &  attr = EmptyString,
const std::string &  value = EmptyString 
) const

This function checks whether the Tag has a child element with a given name, and optionally this child element is checked for having a given attribute with an optional value.

Parameters
nameThe name of the child element.
attrThe name of the attribute of the child element.
valueThe value of the attribute of the child element.
Returns
True if the given child element exists, false otherwise.

Definition at line 615 of file tag.cpp.

◆ hasChildWithAttrib()

bool hasChildWithAttrib ( const std::string &  attr,
const std::string &  value = EmptyString 
) const
inline

This function checks whether the Tag has a child element which posesses a given attribute with an optional value. The name of the child element does not matter.

Parameters
attrThe name of the attribute of the child element.
valueThe value of the attribute of the child element.
Returns
True if any such child element exists, false otherwise.

Definition at line 475 of file tag.h.

◆ hasChildWithCData()

bool hasChildWithCData ( const std::string &  name,
const std::string &  cdata 
) const

This function checks whether a child element with given name exists and has XML character data that equals the given cdata string.

Parameters
nameThe name of the child element.
cdataThe character data that has to exist in the child element.
Returns
True if a child element with given cdata exists, false otherwise.

Definition at line 647 of file tag.cpp.

◆ name()

const std::string& name ( ) const
inline

Use this function to retrieve the name of an element.

Returns
The name of the tag.

Definition at line 394 of file tag.h.

◆ operator bool()

operator bool ( ) const
inline

Returns true if the Tag is valid, false otherwise.

Definition at line 587 of file tag.h.

◆ operator!=()

bool operator!= ( const Tag right) const
inline

Checks two Tags for inequality. Order of attributes and child tags does matter.

Parameters
rightThe Tag to check against the current Tag.
Since
0.9

Definition at line 582 of file tag.h.

◆ operator==()

bool operator== ( const Tag right) const

Checks two Tags for equality. Order of attributes and child tags does matter.

Parameters
rightThe Tag to check against the current Tag.
Since
0.9

Definition at line 249 of file tag.cpp.

◆ parent()

Tag* parent ( ) const
inline

Returns the tag's parent Tag.

Returns
The Tag above the current Tag. May be 0.

Definition at line 526 of file tag.h.

◆ prefix() [1/2]

const std::string& prefix ( ) const
inline

Returns the namespace prefix for this Tag, if any.

Returns
The namespace prefix.
Since
1.0

Definition at line 249 of file tag.h.

◆ prefix() [2/2]

const std::string & prefix ( const std::string &  xmlns) const

Returns the namespace prefix for the given namespace.

Returns
The namespace prefix for the given namespace.
Since
1.0

Definition at line 574 of file tag.cpp.

◆ removeAttribute()

void removeAttribute ( const std::string &  attr,
const std::string &  value = EmptyString,
const std::string &  xmlns = EmptyString 
)

Removes the attribute with the given name and optional value from this Tag.

Parameters
attrThe attribute's name.
valueThe attribute's optional value.
xmlnsAn optional namespace to check for.

Definition at line 779 of file tag.cpp.

◆ removeChild() [1/2]

void removeChild ( const std::string &  name,
const std::string &  xmlns = EmptyString 
)

Removes and deletes all child tags that have the given name and are, optionally, within the given namespace.

Parameters
nameThe name of the tag(s) to remove from the list of child tags.
xmlnsAn optional namespace to check for.

Definition at line 733 of file tag.cpp.

◆ removeChild() [2/2]

void removeChild ( Tag tag)

Removes the given Tag from the list of child Tags.

Parameters
tagThe Tag to remove from the list of child Tags.
Note
The Tag tag is not deleted.

Definition at line 759 of file tag.cpp.

◆ setAttributes()

void setAttributes ( const AttributeList attributes)

Sets the given attributes. Any existing attributes are lost.

Parameters
attributesThe attributes to set.
Returns
True if the input is valid UTF-8, false otherwise. Invalid input will be ignored.
Note
Do not use this function to set XML namespaces, use setXmlns() instead.
Since
0.9

Definition at line 409 of file tag.cpp.

◆ setCData()

bool setCData ( const std::string &  cdata)

Sets the XML character data for this Tag.

Parameters
cdataThe new cdata.
Returns
True if the input is valid UTF-8, false otherwise. Invalid input will be ignored.

Definition at line 447 of file tag.cpp.

◆ setPrefix()

bool setPrefix ( const std::string &  prefix)

Sets the Tag's namespace prefix.

Parameters
prefixThe namespace prefix.
Returns
True if the input is valid UTF-8, false otherwise. Invalid input will be ignored.
Since
1.0

Definition at line 565 of file tag.cpp.

◆ setXmlns()

bool setXmlns ( const std::string &  xmlns,
const std::string &  prefix = EmptyString 
)

Sets an XML namespace with a given prefix, or the default namespace if prefix is empty.

Parameters
xmlnsThe namespace value.
prefixAn optional namespace prefix.
Returns
True if the input is valid UTF-8, false otherwise. Invalid input will be ignored.
Since
1.0

Definition at line 522 of file tag.cpp.

◆ xml()

const std::string xml ( ) const

This function can be used to retrieve the complete XML of a tag as a string. It includes all the attributes, child nodes and character data.

Returns
The complete XML.

Definition at line 302 of file tag.cpp.

◆ xmlns() [1/2]

const std::string xmlns ( ) const

Returns the namespace for this element. Namespace declarations in parent tags as well as prefixes will be taken into account.

Returns
The namespace for this element.
Since
1.0

Definition at line 543 of file tag.cpp.

◆ xmlns() [2/2]

const std::string xmlns ( const std::string &  prefix) const

Returns the namespace for the given prefix, or the default namespace if prefix is empty. Namespace declarations in parent tags will be taken into account. Consider the following XML:

&lt;foo:bar xmlns:foo='foobar'/&gt;

<bar/> is in the foobar namespace, having a prefix of foo. A call to prefix() will return 'foo'. A call to xmlns( "foo" ) or xmlns( prefix() ) will return 'foobar'. A call to xmlns() will also return 'foobar' (it is a shortcut to xmlns( prefix() ).

Parameters
prefixThe namespace prefix to look up, or an empty string to fetch the default namespace.
Returns
The namespace for the given prefix, or the empty string if no such prefix exists. The default namespace if an empty prefix is given.
Since
1.0

Definition at line 548 of file tag.cpp.


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