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

Friends
std::ostream &	operator<< (std::ostream &stream, const node &n)
	Write a node and all of its children to the given stream. 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	<![CDATA[text]]>
type_pi	Processing Instruction.
type_comment	XML comment.
type_entity	Entity as in &.
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]

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() [2/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.

◆ erase() [3/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.

◆ 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]

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*)

◆ find() [4/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

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

◆ insert() [2/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.

◆ 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 "&" 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.

Friends And Related Function Documentation

◆ operator<<

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.

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

xmlwrapp/node.h

Classes

Public Types

Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ size_type

Member Enumeration Documentation

◆ node_type

Constructor & Destructor Documentation

◆ node() [1/8]

◆ node() [2/8]

◆ node() [3/8]

◆ node() [4/8]

◆ node() [5/8]

◆ node() [6/8]

◆ node() [7/8]

◆ node() [8/8]

◆ ~node()

Member Function Documentation

◆ begin() [1/2]

◆ begin() [2/2]

◆ clear()

◆ elements() [1/4]

◆ elements() [2/4]

◆ elements() [3/4]

◆ elements() [4/4]

◆ empty()

◆ end() [1/2]

◆ end() [2/2]

◆ erase() [1/3]

◆ erase() [2/3]

◆ erase() [3/3]

◆ find() [1/4]

◆ find() [2/4]

◆ find() [3/4]

◆ find() [4/4]

◆ get_attributes() [1/2]

◆ get_attributes() [2/2]

◆ get_content()

◆ get_name()

◆ get_namespace()

◆ get_type()

◆ insert() [1/2]

◆ insert() [2/2]

◆ is_text()

◆ move_under()

◆ node_to_string() [1/2]

◆ node_to_string() [2/2]

◆ operator=()

◆ parent() [1/2]

◆ parent() [2/2]

◆ push_back()

◆ replace()

◆ self() [1/2]

◆ self() [2/2]

◆ set_content()

◆ set_name()

◆ set_namespace()

◆ set_text_content()

◆ size()

◆ sort() [1/2]

◆ sort() [2/2]

◆ swap()

Friends And Related Function Documentation

◆ operator<<