xmlwrapp Lightweight C++ XML parsing library

Classes | Public Types | Public Member Functions | List of all members
xml::node Class Reference

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

`#include <node.h>`

## 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 More...

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

## 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

## ◆ size_type

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

size type

## Member Enumeration Documentation

## ◆ node_type

enum xml::node::node_type

enum for the different types of XML nodes

Enumerator
type_element | XML element such as "<chapter/>".
type_text | Text node.
type_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

## ◆ node() [1/8]

xml::node::node | ( |  | ) |

Construct a new blank xml::node.

## ◆ node() [2/8]

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.

## ◆ node() [3/8]

xml::node::node | ( | const char * | name,
|  | const char * | content
| ) |  |

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

The content, if it's not an empty string, 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.

## ◆ node() [4/8]

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.

## ◆ node() [5/8]

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.

## ◆ node() [6/8]

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.

## ◆ node() [7/8]

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.

## ◆ node() [8/8]

xml::node::node | ( | const node & | other | ) |

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

Parameters

  other | The other node to copy.

## ◆ ~node()

xml::node::~node | ( |  | ) |

Class destructor.

## Member Function Documentation

## ◆ begin() [1/2]

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.

## ◆ begin() [2/2]

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.

## ◆ clear()

void xml::node::clear | ( |  | ) |

Erases all children nodes.

Since
  0.7.0

## ◆ elements() [1/4]

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.

Since
  0.6.0

See also
  nodes_view

## ◆ elements() [2/4]

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.

Since
  0.6.0

See also
  const_nodes_view

## ◆ elements() [3/4]

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 view(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.

Since
  0.6.0

## ◆ elements() [4/4]

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 view(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.

Since
  0.6.0

## ◆ empty()

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.

## ◆ end() [1/2]

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.

## ◆ end() [2/2]

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

## ◆ erase() [1/3]

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.

## ◆ erase() [2/3]

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.

## ◆ erase() [3/3]

iterator xml::node::erase | ( | iterator | first,
|  | const iterator & | last
| ) |  |

Erase all nodes in the given range, from first 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.

## ◆ find() [1/4]

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.

See also
  elements(const char*), find(const char*, iterator)

## ◆ find() [2/4]

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.

See also
  elements(const char*) const, find(const char*, const_iterator) const

## ◆ find() [3/4]

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.

See also
  elements(const char*) const

## ◆ find() [4/4]

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.

See also
  elements(const char*)

## ◆ get_attributes() [1/2]

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.

## ◆ get_attributes() [2/2]

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.

## ◆ get_content()

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.

## ◆ get_name()

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.

## ◆ get_namespace()

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.

Since
  0.6.0

## ◆ get_type()

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.

## ◆ insert() [1/2]

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.

## ◆ insert() [2/2]

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.

## ◆ is_text()

bool xml::node::is_text | ( |  | ) | const

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

Returns
  True if this node is a text node; false otherwise.

## ◆ move_under()

void xml::node::move_under | ( | node & | new_parent | ) |

Move this node under another parent.

This node will become the last child of new_parent. Notice that this node must not be an ancestor of new_parent, in particular it shouldn't be the document root.

Currently this method can only be used to move nodes inside the same document.

All iterators pointing to this node are invalidated after the move.

Parameters

  new_parent | The new parent for the node.

Since
  0.8.0

## ◆ node_to_string() [1/2]

std::string xml::node::node_to_string | ( |  | ) | const

Convert the node and all its children into XML text and return the string containing them.

Since
  0.8.0

## ◆ node_to_string() [2/2]

void xml::node::node_to_string | ( | std::string & | xml | ) | const
| inline

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.

## ◆ operator=()

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.

## ◆ parent() [1/2]

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.

## ◆ parent() [2/2]

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.

## ◆ push_back()

void xml::node::push_back | ( | const node & | child | ) |

Add a child xml::node to this node.

Parameters

  child | The child xml::node to add.

## ◆ replace()

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.

## ◆ self() [1/2]

iterator xml::node::self | ( |  | ) |

Get an iterator that points back at this node.

Returns
  An iterator that points at this node.

## ◆ self() [2/2]

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.

## ◆ set_content()

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.

Note
  content is supposed to be a piece of XML CDATA, so it allows entity references, but XML special chars need to be escaped first. In particular, the '&' character must be escaped as "&amp;" unless it's part of entity reference. Not escaping content may result in truncation of data. Use set_text_content() if content may contain special characters.

See also
  set_text_content()

## ◆ set_name()

void xml::node::set_name | ( | const char * | name | ) |

Set the name of this xml::node.

Parameters

  name | The new name for this xml::node.

## ◆ set_namespace()

void xml::node::set_namespace | ( | const std::string & | href | ) |

Set the default namespace of this xml::node.

If the default namespace is already set on this node, it is changed.

Example:

// n is <foo/>
n.set_namespace("http://example.com")
// n is <foo xmlns="http://example.com"/>

Since
  0.8.0

## ◆ set_text_content()

void xml::node::set_text_content | ( | const char * | content | ) |

Set the content of a node to given text.

In contrast to set_content(), content is raw text, so unescaped XML special chars are allowed and entity references are not supported.

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 text.

See also
  set_content()

Since
  0.7.0

## ◆ size()

size_type xml::node::size | ( |  | ) | const

Returns the number of children 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.

## ◆ sort() [1/2]

void xml::node::sort | ( | const char * | node_name,
|  | const char * | attr_name
| ) |  |

Sort all the children nodes of this node using one of their 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.

## ◆ sort() [2/2]

template<typename T >

void xml::node::sort | ( | T | 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.

## ◆ swap()

void xml::node::swap | ( | node & | other | ) |

Swap this node with another one.

Parameters

  other | The other node to swap with.

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

- xmlwrapp/node.h

xml::nodes_view::const_iterator
The const_iterator provides a way to access nodes in the view similar to a standard C++ container.
Definition: nodes_view.h:142
xml::node::cdata
Helper struct for creating a xml::node of type_cdata.
Definition: node.h:124
xml::const_nodes_view
This class implements a read-only view of XML nodes.
Definition: nodes_view.h:253
xml::node::pi
Helper struct for creating a xml::node of type_pi.
Definition: node.h:150
xml::node::comment
Helper struct for creating a xml::node of type_comment.
Definition: node.h:137
xml::nodes_view::iterator
The iterator provides a way to access nodes in the view similar to a standard C++ container.
Definition: nodes_view.h:99
xml::node::text
Helper struct for creating a xml::node of type_text.
Definition: node.h:164
xml::node
The xml::node class is used to hold information about one XML node.
Definition: node.h:89
xml::nodes_view
This class implements a view of XML nodes.
Definition: nodes_view.h:79