Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | Related Pages
gloox::Tag

Tag Class Reference

This is an abstraction of an XML element. More...

#include <tag.h>

List of all members.

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 AttributeList & attributes () const
const TagList & children () const
const std::string & findAttribute (const std::string &name) const
bool hasAttribute (const std::string &name, const std::string &value=EmptyString) const
Tag * findChild (const std::string &name) const
Tag * findChild (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
Tag * findChildWithAttrib (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
Tag * parent () const
Tag * clone () const
const std::string findCData (const std::string &expression) const
const Tag * findTag (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

Classes

class  Attribute

Detailed Description

This is an abstraction of an XML element.

Note:
Use setXmlns() to set namespaces and namespace prefixes.
Author:
Jakob Schroeter <js@camaya.net>
Since:
0.4

Definition at line 46 of file tag.h.

Member Typedef Documentation

typedef std::list<Attribute*> AttributeList
 

A list of XML element attributes.

Definition at line 187 of file tag.h.

Constructor & Destructor Documentation

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:
name The name of the element.
cdata The XML character data of the element.

Definition at line 138 of file tag.cpp.

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:
parent The parent tag.
name The name of the element.
cdata The XML character data of the element.

Definition at line 149 of file tag.cpp.

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:
name The name of the element.
attrib The attribute name.
value The attribute value.

Definition at line 163 of file tag.cpp.

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:
parent The parent tag.
name The name of the element.
attrib The attribute name.
value The attribute value.

Definition at line 176 of file tag.cpp.

~Tag (   )  [virtual]
 

Virtual destructor.

Definition at line 228 of file tag.cpp.

Member Function Documentation

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:
name The name of the attribute.
value The 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 400 of file tag.cpp.

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:
name The name of the attribute.
value The 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 392 of file tag.cpp.

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

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

Parameters:
name The name of the attribute.
value The 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 384 of file tag.cpp.

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:
attr A 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 353 of file tag.cpp.

bool addCData (  const std::string &  cdata  ) 
 

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

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

Definition at line 476 of file tag.cpp.

void addChild (  Tag *  child  ) 
 

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

Parameters:
child The node to be inserted.

Definition at line 423 of file tag.cpp.

void addChildCopy (  const Tag *  child  ) 
 

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

Parameters:
child The node to be inserted.
Since:
0.9

Definition at line 438 of file tag.cpp.

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 511 of file tag.cpp.

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 492 of file tag.cpp.

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 505 of file tag.cpp.

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 665 of file tag.cpp.

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

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

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

Definition at line 584 of file tag.cpp.

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:
expression An XPath expression to evaluate.
Returns:
A matched Tag's character data, or the empty string.
Since:
1.0

Definition at line 794 of file tag.cpp.

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:
name The name of the element to search for.
attr The name of the attribute of the child element.
value The value of the attribute of the child element.
Returns:
The found Tag, or 0.

Definition at line 630 of file tag.cpp.

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:
name The name of the element to search for.
Returns:
The found Tag, or 0.

Definition at line 619 of file tag.cpp.

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:
name The name of the tags to look for.
xmlns An 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 709 of file tag.cpp.

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:
attr The name of the attribute of the child element.
value The value of the attribute of the child element.
Returns:
The child if found, 0 otherwise.

Definition at line 654 of file tag.cpp.

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:
expression An XPath expression to evaluate.
Returns:
A matched Tag, or 0.
Since:
0.9

Definition at line 800 of file tag.cpp.

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:
expression An XPath expression to evaluate.
Returns:
A list of matched Tags, or an empty TagList.
Since:
0.9

Definition at line 806 of file tag.cpp.

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:
name The name of the attribute to check for.
value The value of the attribute to check for.
Returns:
Whether the attribute exists (optionally with the given value).

Definition at line 597 of file tag.cpp.

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:
name The name of the child element.
attr The name of the attribute of the child element.
value The value of the attribute of the child element.
Returns:
True if the given child element exists, false otherwise.

Definition at line 610 of file tag.cpp.

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:
attr The name of the attribute of the child element.
value The 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.

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:
name The name of the child element.
cdata The 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 642 of file tag.cpp.

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 (   )  const [inline]
 

Returns true if the Tag is valid, false otherwise.

Definition at line 587 of file tag.h.

bool operator!= (  const Tag &  right  )  const [inline]
 

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

Parameters:
right The Tag to check against the current Tag.
Since:
0.9

Definition at line 582 of file tag.h.

bool operator== (  const Tag &  right  )  const
 

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

Parameters:
right The Tag to check against the current Tag.
Since:
0.9

Definition at line 248 of file tag.cpp.

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.

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 569 of file tag.cpp.

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.

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:
attr The attribute's name.
value The attribute's optional value.
xmlns An optional namespace to check for.

Definition at line 774 of file tag.cpp.

void removeChild (  Tag *  tag  ) 
 

Removes the given Tag from the list of child Tags.

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

Definition at line 754 of file tag.cpp.

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:
name The name of the tag(s) to remove from the list of child tags.
xmlns An optional namespace to check for.

Definition at line 728 of file tag.cpp.

void setAttributes (  const AttributeList &  attributes  ) 
 

Sets the given attributes. Any existing attributes are lost.

Parameters:
attributes The 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 408 of file tag.cpp.

bool setCData (  const std::string &  cdata  ) 
 

Sets the XML character data for this Tag.

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

Definition at line 446 of file tag.cpp.

bool setPrefix (  const std::string &  prefix  ) 
 

Sets the Tag's namespace prefix.

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

Definition at line 560 of file tag.cpp.

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:
xmlns The namespace value.
prefix An 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 517 of file tag.cpp.

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 301 of file tag.cpp.

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:
prefix The 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 543 of file tag.cpp.

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 538 of file tag.cpp.

The documentation for this class was generated from the following files:
Generated on Sat Oct 31 19:54:41 2009 for gloox by  doxygen 1.4.1