xml::node Class Reference

The xml::node class is used to hold information about one XML node. More...

#include <node.h>

List of all members.

Classes

struct  cdata
 Helper struct for creating a xml::node of type_cdata. More...
struct  comment
 Helper struct for creating a xml::node of type_comment. More...
class  const_iterator
 The xml::node::const_iterator provides a way to access children nodes similar to a standard C++ container. More...
class  iterator
 The xml::node::iterator provides a way to access children nodes similar to a standard C++ container. More...
struct  pi
 Helper struct for creating a xml::node of type_pi. More...
struct  text
 Helper struct for creating a xml::node of type_text. More...

Public Types

enum  node_type {
  type_element, type_text, type_cdata, type_pi,
  type_comment, type_entity, type_entity_ref, type_xinclude,
  type_document, type_document_type, type_document_frag, type_notation,
  type_dtd, type_dtd_element, type_dtd_attribute, type_dtd_entity,
  type_dtd_namespace
}
 

enum for the different types of XML nodes

More...
typedef std::size_t size_type
 size type

Public Member Functions

 node ()
 Construct a new blank xml::node.
 node (const char *name)
 Construct a new xml::node and set the name of the node.
 node (const char *name, const char *content)
 Construct a new xml::node given a name and content.
 node (cdata cdata_info)
 Construct a new xml::node that is of type_cdata.
 node (comment comment_info)
 Construct a new xml::node that is of type_comment.
 node (pi pi_info)
 Construct a new xml::node that is of type_pi.
 node (text text_info)
 Construct a new xml::node that is of type_text.
 node (const node &other)
 Construct a new xml::node by copying another xml::node.
nodeoperator= (const node &other)
 Make this node equal to some other node via assignment.
 ~node ()
 Class destructor.
void set_name (const char *name)
 Set the name of this xml::node.
const char * get_name () const
 Get the name of this xml::node.
void set_content (const char *content)
 Set the content of a node.
const char * get_content () const
 Get the content for this text node.
node_type get_type () const
 Get this node's "type".
xml::attributesget_attributes ()
 Get the list of attributes.
const xml::attributesget_attributes () const
 Get the list of attributes.
const char * get_namespace () const
 Get the namespace of this xml::node.
bool is_text () const
 Find out if this node is a text node or sometiming like a text node, CDATA for example.
void push_back (const node &child)
 Add a child xml::node to this node.
void swap (node &other)
 Swap this node with another one.
size_type size () const
 Returns the number of childer this nodes has.
bool empty () const
 Find out if this node has any children.
iterator begin ()
 Get an iterator that points to the beginning of this node's children.
const_iterator begin () const
 Get a const_iterator that points to the beginning of this node's children.
iterator end ()
 Get an iterator that points one past the last child for this node.
const_iterator end () const
 Get a const_iterator that points one past the last child for this node.
iterator self ()
 Get an iterator that points back at this node.
const_iterator self () const
 Get a const_iterator that points back at this node.
iterator parent ()
 Get an iterator that points at the parent of this node.
const_iterator parent () const
 Get a const_iterator that points at the parent of this node.
iterator find (const char *name)
 Find the first child node that has the given name.
const_iterator find (const char *name) const
 Find the first child node that has the given name.
iterator find (const char *name, const iterator &start)
 Find the first child node, starting with the given iterator, that has the given name.
const_iterator find (const char *name, const const_iterator &start) const
 Find the first child node, starting with the given const_iterator, that has the given name.
nodes_view elements ()
 Returns view of child nodes of type type_element.
const_nodes_view elements () const
 Returns view of child nodes of type type_element.
nodes_view elements (const char *name)
 Returns view of child nodes of type type_element with name name.
const_nodes_view elements (const char *name) const
 Returns view of child nodes of type type_element with name name.
iterator insert (const node &n)
 Insert a new child node.
iterator insert (const iterator &position, const node &n)
 Insert a new child node.
iterator replace (const iterator &old_node, const node &new_node)
 Replace the node pointed to by the given iterator with another node.
iterator erase (const iterator &to_erase)
 Erase the node that is pointed to by the given iterator.
iterator erase (iterator first, const iterator &last)
 Erase all nodes in the given range, from frist to last.
size_type erase (const char *name)
 Erase all children nodes with the given name.
void sort (const char *node_name, const char *attr_name)
 Sort all the children nodes of this node using one of thier attributes.
template<typename T >
void sort (T compare)
 Sort all the children nodes of this node using the given comparison function object.
void node_to_string (std::string &xml) const
 Convert the node and all its children into XML text and set the given string to that text.

Friends

std::ostream & operator<< (std::ostream &stream, const node &n)
 Write a node and all of its children to the given stream.

Detailed Description

The xml::node class is used to hold information about one XML node.

This includes the name of the node, the namespace of the node and attributes for the node. It also has an iterator whereby you can get to the children nodes.

It should be noted that any member function that returns a const char* returns a temporary value. The pointer that is returned will change with ANY operation to the xml::node. If you need the data to stick around a little longer you should put it inside a std::string.


Member Typedef Documentation

typedef std::size_t xml::node::size_type

size type


Member Enumeration Documentation

enum for the different types of XML nodes

Enumerator:
type_element 

XML element such as "<chapter/>".

type_text 

Text node.

type_cdata 

<![CDATA[text]]>

type_pi 

Processing Instruction.

type_comment 

XML comment.

type_entity 

Entity as in &amp;.

type_entity_ref 

Entity ref.

type_xinclude 

<xi:include/> node

type_document 

Document node.

type_document_type 

DOCTYPE node.

type_document_frag 

Document Fragment.

type_notation 

Notation.

type_dtd 

DTD node.

type_dtd_element 

DTD <!ELEMENT> node.

type_dtd_attribute 

DTD <!ATTRLIST> node.

type_dtd_entity 

DTD <!ENTITY>.

type_dtd_namespace 

?


Constructor & Destructor Documentation

xml::node::node (  ) 

Construct a new blank xml::node.

Author:
Peter Jones
xml::node::node ( const char *  name  )  [explicit]

Construct a new xml::node and set the name of the node.

Parameters:
name The name of the new node.
Author:
Peter Jones
xml::node::node ( const char *  name,
const char *  content 
)

Construct a new xml::node given a name and content.

The content will be used to create a new child text node.

Parameters:
name The name of the new element.
content The text that will be used to create a child node.
Author:
Peter Jones
xml::node::node ( cdata  cdata_info  )  [explicit]

Construct a new xml::node that is of type_cdata.

The cdata_info parameter should contain the contents of the CDATA section.

Note:
Sample Use Example:
        xml::node mynode(xml::node::cdata("This is a CDATA section"));
Parameters:
cdata_info A cdata struct that tells xml::node what the content will be.
Author:
Peter Jones
xml::node::node ( comment  comment_info  )  [explicit]

Construct a new xml::node that is of type_comment.

The comment_info parameter should contain the contents of the XML comment.

Note:
Sample Use Example:
        xml::node mynode(xml::node::comment("This is an XML comment"));
Parameters:
comment_info A comment struct that tells xml::node what the comment will be.
Author:
Peter Jones
xml::node::node ( pi  pi_info  )  [explicit]

Construct a new xml::node that is of type_pi.

The pi_info parameter should contain the name of the XML processing instruction (PI), and optionally, the contents of the XML PI.

Note:
Sample Use Example:
        xml::node mynode(xml::node::pi("xslt", "stylesheet=\"test.xsl\""));
Parameters:
pi_info A pi struct that tells xml::node what the name and contents of the XML PI are.
Author:
Peter Jones
xml::node::node ( text  text_info  )  [explicit]

Construct a new xml::node that is of type_text.

The text_info parameter should contain the text.

Note:
Sample Use Example:
        xml::node mynode(xml::node::text("This is XML text"));
Parameters:
text_info A text struct that tells xml::node what the text will be.
Author:
Vaclav Slavik
xml::node::node ( const node other  ) 

Construct a new xml::node by copying another xml::node.

Parameters:
other The other node to copy.
Author:
Peter Jones
xml::node::~node (  ) 

Class destructor.

Author:
Peter Jones

Member Function Documentation

const_iterator xml::node::begin (  )  const

Get a const_iterator that points to the beginning of this node's children.

Returns:
A const_iterator that points to the beginning of the children.
Author:
Peter Jones
iterator xml::node::begin (  ) 

Get an iterator that points to the beginning of this node's children.

Returns:
An iterator that points to the beginning of the children.
Author:
Peter Jones
const_nodes_view xml::node::elements ( const char *  name  )  const

Returns view of child nodes of type type_element with name name.

If no such node can be found, returns empty view.

Example:

        xml::const_nodes_view persons(root.elements("person"));
        for (xml::const_nodes_view::const_iterator i = view.begin();
             i != view.end();
             ++i)
        {
          ...
        }
Parameters:
name Name of the elements to return.
Returns:
View that contains only elements name.
Author:
Vaclav Slavik
Since:
0.6.0
nodes_view xml::node::elements ( const char *  name  ) 

Returns view of child nodes of type type_element with name name.

If no such node can be found, returns empty view.

Example:

        xml::nodes_view persons(root.elements("person"));
        for (xml::nodes_view::iterator i = view.begin(); i != view.end(); ++i)
        {
          ...
        }
Parameters:
name Name of the elements to return.
Returns:
View that contains only elements name.
Author:
Vaclav Slavik
Since:
0.6.0
const_nodes_view xml::node::elements (  )  const

Returns view of child nodes of type type_element.

If no such node can be found, returns empty view.

Example:

        xml::const_nodes_view view(root.elements());
        for (xml::const_nodes_view::const_iterator i = view.begin();
             i != view.end();
             ++i)
        {
          ...
        }
Returns:
View with all child elements or empty view if there aren't any.
Author:
Vaclav Slavik
Since:
0.6.0
See also:
const_nodes_view
nodes_view xml::node::elements (  ) 

Returns view of child nodes of type type_element.

If no such node can be found, returns empty view.

Example:

        xml::nodes_view view(root.elements());
        for (xml::nodes_view::iterator i = view.begin(); i != view.end(); ++i)
        {
          ...
        }
Returns:
View with all child elements or empty view if there aren't any.
Author:
Vaclav Slavik
Since:
0.6.0
See also:
nodes_view
bool xml::node::empty (  )  const

Find out if this node has any children.

This is the same as xml::node::size() == 0 except it is much faster.

Returns:
True if this node DOES NOT have any children.
False if this node does have children.
Author:
Peter Jones
const_iterator xml::node::end (  )  const [inline]

Get a const_iterator that points one past the last child for this node.

Returns:
A "one past the end" const_iterator
Author:
Peter Jones
iterator xml::node::end (  )  [inline]

Get an iterator that points one past the last child for this node.

Returns:
A "one past the end" iterator.
Author:
Peter Jones
size_type xml::node::erase ( const char *  name  ) 

Erase all children nodes with the given name.

This will find all nodes that have the given node name and remove them from this node. This will invalidate any iterators that point to the nodes to be erased, or any pointers or references to those nodes.

Parameters:
name The name of nodes to remove.
Returns:
The number of nodes removed.
Author:
Peter Jones
iterator xml::node::erase ( iterator  first,
const iterator last 
)

Erase all nodes in the given range, from frist to last.

This will invalidate any iterators that point to the nodes to be erased, or any pointers or references to those nodes.

Parameters:
first The first node in the range to be removed.
last An iterator that points one past the last node to erase. Think xml::node::end().
Returns:
An iterator that points to the node after the last one being erased.
Author:
Peter Jones
iterator xml::node::erase ( const iterator to_erase  ) 

Erase the node that is pointed to by the given iterator.

The node and all its children will be removed from this node. This will invalidate any iterators that point to the node to be erased, or any pointers or references to that node.

Parameters:
to_erase An iterator that points to the node to be erased.
Returns:
An iterator that points to the node after the one being erased.
Author:
Peter Jones
Gary A. Passero
const_iterator xml::node::find ( const char *  name,
const const_iterator start 
) const

Find the first child node, starting with the given const_iterator, that has the given name.

If no such node can be found, this function will return the same const_iterator that end() would return.

This function should be given a const_iterator to one of this node's children. The search will begin with that node and continue with all its siblings. This function will not recurse down the tree, it only searches in one level.

Parameters:
name The name of the node you want to find.
start Where to begin the search.
Returns:
A const_iterator that points to the node if found.
An end() const_iterator if the node was not found.
Author:
Peter Jones
See also:
elements(const char*) const
iterator xml::node::find ( const char *  name,
const iterator start 
)

Find the first child node, starting with the given iterator, that has the given name.

If no such node can be found, this function will return the same iterator that end() would return.

This function should be given an iterator to one of this node's children. The search will begin with that node and continue with all its sibliings. This function will not recurse down the tree, it only searches in one level.

Parameters:
name The name of the node you want to find.
start Where to begin the search.
Returns:
An iterator that points to the node if found.
An end() iterator if the node was not found.
Author:
Peter Jones
See also:
elements(const char*)
const_iterator xml::node::find ( const char *  name  )  const

Find the first child node that has the given name.

If no such node can be found, this function will return the same const_iterator that end() would return.

This function is not recursive. That is, it will not search down the tree for the requested node. Instead, it will only search one level deep, only checking the children of this node.

Parameters:
name The name of the node you want to find.
Returns:
A const_iterator that points to the node if found.
An end() const_iterator if the node was not found.
Author:
Peter Jones
See also:
elements(const char*) const, find(const char*, const_iterator) const
iterator xml::node::find ( const char *  name  ) 

Find the first child node that has the given name.

If no such node can be found, this function will return the same iterator that end() would return.

This function is not recursive. That is, it will not search down the tree for the requested node. Instead, it will only search one level deep, only checking the children of this node.

Parameters:
name The name of the node you want to find.
Returns:
An iterator that points to the node if found.
An end() iterator if the node was not found.
Author:
Peter Jones
See also:
elements(const char*), find(const char*, iterator)
const xml::attributes& xml::node::get_attributes (  )  const

Get the list of attributes.

You can use the returned object to get the attributes for this node. Make sure you use a reference to this returned object, to prevent a copy.

Returns:
The xml::attributes object for this node.
Author:
Peter Jones
xml::attributes& xml::node::get_attributes (  ) 

Get the list of attributes.

You can use the returned object to get and set the attributes for this node. Make sure you use a reference to this returned object, to prevent a copy.

Returns:
The xml::attributes object for this node.
Author:
Peter Jones
const char* xml::node::get_content (  )  const

Get the content for this text node.

If this node is not a text node but it has children nodes that are text nodes, the contents of those child nodes will be returned. If there is no content or these conditions do not apply, zero will be returned.

This function may change in the future to return std::string. Feedback is welcome.

Returns:
The content or 0.
Author:
Peter Jones
const char* xml::node::get_name (  )  const

Get the name of this xml::node.

This function may change in the future to return std::string. Feedback is welcome.

Returns:
The name of this node.
Author:
Peter Jones
const char* xml::node::get_namespace (  )  const

Get the namespace of this xml::node.

Returns:
The namespace of this node or NULL if no namespace is associated.
Author:
Vaclav Slavik
Since:
0.6.0
node_type xml::node::get_type (  )  const

Get this node's "type".

You can use that information to know what you can and cannot do with it.

Returns:
The node's type.
Author:
Peter Jones
iterator xml::node::insert ( const iterator position,
const node n 
)

Insert a new child node.

The new node will be inserted before the node pointed to by the given iterator.

Parameters:
position An iterator that points to the location where the new node should be inserted (before it).
n The node to insert as a child of this node.
Returns:
An iterator that points to the newly inserted node.
Author:
Peter Jones
iterator xml::node::insert ( const node n  ) 

Insert a new child node.

The new node will be inserted at the end of the child list. This is similar to the xml::node::push_back member function except that an iterator to the inserted node is returned.

Parameters:
n The node to insert as a child of this node.
Returns:
An iterator that points to the newly inserted node.
Author:
Peter Jones
bool xml::node::is_text (  )  const

Find out if this node is a text node or sometiming like a text node, CDATA for example.

Returns:
True if this node is a text node; false otherwise.
Author:
Peter Jones
void xml::node::node_to_string ( std::string &  xml  )  const

Convert the node and all its children into XML text and set the given string to that text.

Parameters:
xml The string to set the node's XML data to.
Author:
Peter Jones
node& xml::node::operator= ( const node other  ) 

Make this node equal to some other node via assignment.

Parameters:
other The other node to copy.
Returns:
A reference to this node.
Author:
Peter Jones
const_iterator xml::node::parent (  )  const

Get a const_iterator that points at the parent of this node.

If this node does not have a parent, this member function will return an "end" const_iterator.

Returns:
A const_iterator that points to this nodes parent.
If no parent, returns the same const_iterator that xml::node::end() returns.
Author:
Peter Jones
iterator xml::node::parent (  ) 

Get an iterator that points at the parent of this node.

If this node does not have a parent, this member function will return an "end" iterator.

Returns:
An iterator that points to this nodes parent.
If no parent, returns the same iterator that xml::node::end() returns.
Author:
Peter Jones
void xml::node::push_back ( const node child  ) 

Add a child xml::node to this node.

Parameters:
child The child xml::node to add.
Author:
Peter Jones
iterator xml::node::replace ( const iterator old_node,
const node new_node 
)

Replace the node pointed to by the given iterator with another node.

The old node will be removed, including all its children, and replaced with the new node. This will invalidate any iterators that point to the node to be replaced, or any pointers or references to that node.

Parameters:
old_node An iterator that points to the node that should be removed.
new_node The node to put in old_node's place.
Returns:
An iterator that points to the new node.
Author:
Peter Jones
const_iterator xml::node::self (  )  const

Get a const_iterator that points back at this node.

Returns:
A const_iterator that points at this node.
Author:
Peter Jones
iterator xml::node::self (  ) 

Get an iterator that points back at this node.

Returns:
An iterator that points at this node.
Author:
Peter Jones
void xml::node::set_content ( const char *  content  ) 

Set the content of a node.

If this node is an element node, this function will remove all of its children nodes and replace them with one text node set to the given string.

Parameters:
content The content of the text node.
Author:
Peter Jones
void xml::node::set_name ( const char *  name  ) 

Set the name of this xml::node.

Parameters:
name The new name for this xml::node.
Author:
Peter Jones
size_type xml::node::size (  )  const

Returns the number of childer this nodes has.

If you just want to know how if this node has children or not, you should use xml::node::empty() instead.

Returns:
The number of children this node has.
Author:
Peter Jones
template<typename T >
void xml::node::sort ( compare  )  [inline]

Sort all the children nodes of this node using the given comparison function object.

All element type nodes will be considered for sorting.

Parameters:
compare The binary function object to call in order to sort all child nodes.
Author:
Peter Jones
void xml::node::sort ( const char *  node_name,
const char *  attr_name 
)

Sort all the children nodes of this node using one of thier attributes.

Only nodes that are of xml::node::type_element will be sorted, and they must have the given node_name.

The sorting is done by calling std::strcmp on the value of the given attribute.

Parameters:
node_name The name of the nodes to sort.
attr_name The attribute to sort on.
Author:
Peter Jones
void xml::node::swap ( node other  ) 

Swap this node with another one.

Parameters:
other The other node to swap with.
Author:
Peter Jones

Friends And Related Function Documentation

std::ostream& operator<< ( std::ostream &  stream,
const node n 
) [friend]

Write a node and all of its children to the given stream.

Parameters:
stream The stream to write the node as XML.
n The node to write to the stream.
Returns:
The stream.
Author:
Peter Jones

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

Generated on Sun Dec 20 12:42:33 2009 for xmlwrapp by  doxygen 1.6.1