Element nodes have attributes as well as child nodes. More...

#include <libxml++/nodes/element.h>

Inheritance diagram for xmlpp::Element:

Public Types
using	AttributeList = std::list< Attribute * >

using	const_AttributeList = std::list< const Attribute * >

Public Types inherited from xmlpp::Node
using	const_NodeList = std::list< const Node * >

using	const_NodeSet = std::vector< const Node * >

using	NodeList = std::list< Node * >

using	NodeSet = std::vector< Node * >

using	PrefixNsMap = std::map< ustring, ustring >
	A map of namespace prefixes to namespace URIs. More...

Public Member Functions
	Element (_xmlNode * node)

	~Element () override

CdataNode *	add_child_cdata (const ustring & content)
	Append a new CDATA node. More...

CommentNode *	add_child_comment (const ustring & content)
	Append a new comment node. More...

Element *	add_child_element (const ustring & name, const ustring & ns_prefix=ustring())
	Add a child element to this node. More...

Element *	add_child_element (xmlpp::Node * previous_sibling, const ustring & name, const ustring & ns_prefix=ustring())
	Add a child element to this node after the specified existing child node. More...

Element *	add_child_element_before (xmlpp::Node * next_sibling, const ustring & name, const ustring & ns_prefix=ustring())
	Add a child element to this node before the specified existing child node. More...

Element *	add_child_element_before_with_new_ns (xmlpp::Node * next_sibling, const ustring & name, const ustring & ns_uri, const ustring & ns_prefix=ustring())
	Add a child element to this node before the specified existing child node. More...

Element *	add_child_element_with_new_ns (const ustring & name, const ustring & ns_uri, const ustring & ns_prefix=ustring())
	Add a child element to this node. More...

Element *	add_child_element_with_new_ns (xmlpp::Node * previous_sibling, const ustring & name, const ustring & ns_uri, const ustring & ns_prefix=ustring())
	Add a child element to this node after the specified existing child node. More...

EntityReference *	add_child_entity_reference (const ustring & name)
	Append a new entity reference node. More...

ProcessingInstructionNode *	add_child_processing_instruction (const ustring & name, const ustring & content)
	Append a new processing instruction node. More...

TextNode *	add_child_text (const ustring & content=ustring())
	Append a new text node. More...

TextNode *	add_child_text (xmlpp::Node * previous_sibling, const ustring & content=ustring())
	Add a new text node after the specified existing child node. More...

TextNode *	add_child_text_before (xmlpp::Node * next_sibling, const ustring & content=ustring())
	Add a new text node before the specified existing child node. More...

Attribute *	get_attribute (const ustring & name, const ustring & ns_prefix=ustring())
	Get the attribute with this name, and optionally with this namespace. More...

const Attribute *	get_attribute (const ustring & name, const ustring & ns_prefix=ustring()) const
	Get the attribute with this name, and optionally with this namespace. More...

ustring	get_attribute_value (const ustring & name, const ustring & ns_prefix=ustring()) const
	Get the value of the attribute with this name, and optionally with this namespace. More...

std::optional< ustring >	get_attribute_value2 (const ustring & name, const ustring & ns_prefix={}) const
	Get the value of the attribute with this name, and optionally with this namespace. More...

AttributeList	get_attributes ()
	Obtain the list of explicitly set attributes for this element. More...

const_AttributeList	get_attributes () const
	Obtain the list of explicitly set attributes for this element. More...

TextNode *	get_first_child_text ()
	Get the first child text content node. More...

const TextNode *	get_first_child_text () const
	Get the first child text content node. More...

bool	has_child_text () const
	Discover whether one of the child nodes is a text node. More...

void	remove_attribute (const ustring & name, const ustring & ns_prefix=ustring())
	Remove the attribute with this name, and optionally with this namespace. More...

Attribute *	set_attribute (const ustring & name, const ustring & value, const ustring & ns_prefix=ustring())
	Set the value of the attribute with this name, and optionally with this namespace. More...

void	set_first_child_text (const ustring & content)
	Set the text of the first text node, adding one if necessary. More...

void	set_namespace_declaration (const ustring & ns_uri, const ustring & ns_prefix=ustring())
	Add a namespace declaration to this node which will apply to this node and all children. More...

Public Member Functions inherited from xmlpp::Node
	Node (_xmlNode * node)

	~Node () override
	Destructor. More...

const _xmlNode *	cobj () const noexcept
	Access the underlying libxml implementation. More...

_xmlNode *	cobj () noexcept
	Access the underlying libxml implementation. More...

bool	eval_to_boolean (const ustring & xpath, const PrefixNsMap & namespaces, XPathResultType * result_type=nullptr) const
	Evaluate an XPath expression. More...

bool	eval_to_boolean (const ustring & xpath, XPathResultType * result_type=nullptr) const
	Evaluate an XPath expression. More...

double	eval_to_number (const ustring & xpath, const PrefixNsMap & namespaces, XPathResultType * result_type=nullptr) const
	Evaluate an XPath expression. More...

double	eval_to_number (const ustring & xpath, XPathResultType * result_type=nullptr) const
	Evaluate an XPath expression. More...

ustring	eval_to_string (const ustring & xpath, const PrefixNsMap & namespaces, XPathResultType * result_type=nullptr) const
	Evaluate an XPath expression. More...

ustring	eval_to_string (const ustring & xpath, XPathResultType * result_type=nullptr) const
	Evaluate an XPath expression. More...

std::variant< NodeSet, bool, double, ustring >	eval_xpath (const ustring & xpath, const PrefixNsMap & namespaces={})
	Evaluate an XPath expression. More...

std::variant< const_NodeSet, bool, double, ustring >	eval_xpath (const ustring & xpath, const PrefixNsMap & namespaces={}) const
	Evaluate an XPath expression. More...

NodeSet	find (const ustring & xpath)
	Find nodes from an XPath expression. More...

const_NodeSet	find (const ustring & xpath) const
	Find nodes from an XPath expression. More...

NodeSet	find (const ustring & xpath, const PrefixNsMap & namespaces)
	Find nodes from an XPath expression. More...

const_NodeSet	find (const ustring & xpath, const PrefixNsMap & namespaces) const
	Find nodes from an XPath expression. More...

NodeList	get_children (const ustring & name=ustring())
	Obtain the list of child nodes. More...

const_NodeList	get_children (const ustring & name=ustring()) const
	Obtain the list of child nodes. More...

Node *	get_first_child (const ustring & name=ustring())
	Get the first child of this node. More...

const Node *	get_first_child (const ustring & name=ustring()) const
	Get the first child of this node. More...

int	get_line () const
	Discover at what line number this node occurs in the XML file. More...

ustring	get_name () const
	Get the name of this node. More...

std::optional< ustring >	get_name2 () const
	Get the name of this node. More...

ustring	get_namespace_prefix () const
	Get the namespace prefix of this node. More...

std::optional< ustring >	get_namespace_prefix2 () const
	Get the namespace prefix of this node. More...

ustring	get_namespace_uri () const
	Get the namespace URI of this node. More...

std::optional< ustring >	get_namespace_uri2 () const
	Get the namespace URI of this node. More...

Node *	get_next_sibling ()
	Get the next sibling for this node. More...

const Node *	get_next_sibling () const
	Get the next sibling for this node. More...

Element *	get_parent ()
	Get the parent element for this node. More...

const Element *	get_parent () const
	Get the parent element for this node. More...

ustring	get_path () const
	Get the XPath of this node. More...

std::optional< ustring >	get_path2 () const
	Get the XPath of this node. More...

Node *	get_previous_sibling ()
	Get the previous sibling for this node. More...

const Node *	get_previous_sibling () const
	Get the previous sibling for this node . More...

Node *	import_node (const Node * node, bool recursive=true)
	Import node(s) from another document under this node, without affecting the source node. More...

void	set_name (const ustring & name)
	Set the name of this node. More...

void	set_namespace (const ustring & ns_prefix)
	Set the namespace prefix used by the node. More...

Public Member Functions inherited from xmlpp::NonCopyable
	NonCopyable (const NonCopyable &)=delete

	NonCopyable (NonCopyable &&)=delete

NonCopyable &	operator= (const NonCopyable &)=delete

NonCopyable &	operator= (NonCopyable &&)=delete

Additional Inherited Members
Static Public Member Functions inherited from xmlpp::Node
static void	create_wrapper (_xmlNode * node)
	Construct the correct C++ instance for a given libxml C struct instance. More...

static void	free_wrappers (_xmlNode * node)
	Delete the C++ instance for a given libxml C struct instance, and also recursively destroy the C++ instances for any children. More...

static void	remove_node (Node * node)
	Remove a node and its children. More...

Protected Member Functions inherited from xmlpp::NonCopyable
	NonCopyable () noexcept

virtual	~NonCopyable ()

Detailed Description

Element nodes have attributes as well as child nodes.

This will be instantiated by the parser.

Member Typedef Documentation

◆ AttributeList

using xmlpp::Element::AttributeList = std::list<Attribute*>

◆ const_AttributeList

using xmlpp::Element::const_AttributeList = std::list<const Attribute*>

Constructor & Destructor Documentation

◆ Element()

xmlpp::Element::Element ( _xmlNode * node )

explicit

◆ ~Element()

xmlpp::Element::~Element ( )

override

Member Function Documentation

◆ add_child_cdata()

CdataNode* xmlpp::Element::add_child_cdata ( const ustring & content )

Append a new CDATA node.

Parameters

content The raw text.

Returns: The new CDATA node.

Exceptions

xmlpp::internal_error

◆ add_child_comment()

CommentNode* xmlpp::Element::add_child_comment ( const ustring & content )

Append a new comment node.

Parameters

content The text. This should be unescaped - see ContentNode::set_content().

Returns: The new comment node.

Exceptions

xmlpp::internal_error

◆ add_child_element() [1/2]

Element* xmlpp::Element::add_child_element	(	const ustring &	name,
		const ustring &	ns_prefix = `ustring()`
	)

Add a child element to this node.

Since libxml++ 3.0:: Replaces Node::add_child()

Parameters

name	The new node name
ns_prefix	The namespace prefix. If the prefix has not been declared then this method will throw an exception.

Returns: The newly-created element

Exceptions

xmlpp::exception	If a namespace prefix is specified, but has not been declared.
xmlpp::internal_error	If this node is not an element node, or the child node cannot be created.

◆ add_child_element() [2/2]

Element* xmlpp::Element::add_child_element	(	xmlpp::Node *	previous_sibling,
		const ustring &	name,
		const ustring &	ns_prefix = `ustring()`
	)

Add a child element to this node after the specified existing child node.

Since libxml++ 3.0:: Replaces Node::add_child()

Parameters

previous_sibling	An existing child node.
name	The new node name
ns_prefix	The namespace prefix. If the prefix has not been declared then this method will throw an exception.

Returns: The newly-created element

Exceptions

xmlpp::exception	If a namespace prefix is specified, but has not been declared.
xmlpp::internal_error	If this node is not an element node, or the child node cannot be created.

◆ add_child_element_before()

Element* xmlpp::Element::add_child_element_before	(	xmlpp::Node *	next_sibling,
		const ustring &	name,
		const ustring &	ns_prefix = `ustring()`
	)

Add a child element to this node before the specified existing child node.

Since libxml++ 3.0:: Replaces Node::add_child_before()

Parameters

next_sibling	An existing child node.
name	The new node name
ns_prefix	The namespace prefix. If the prefix has not been declared then this method will throw an exception.

Returns: The newly-created element

Exceptions

xmlpp::exception	If a namespace prefix is specified, but has not been declared.
xmlpp::internal_error	If this node is not an element node, or the child node cannot be created.

◆ add_child_element_before_with_new_ns()

Element* xmlpp::Element::add_child_element_before_with_new_ns	(	xmlpp::Node *	next_sibling,
		const ustring &	name,
		const ustring &	ns_uri,
		const ustring &	ns_prefix = `ustring()`
	)

Add a child element to this node before the specified existing child node.

Since libxml++ 3.0:: Replaces Node::add_child_before_with_new_ns()

Parameters

next_sibling	An existing child node.
name	The new node name.
ns_uri	The namespace to associate with the prefix, or to use as the default namespace if no prefix is specified.
ns_prefix	The prefix of the node's namespace. If no prefix is specified then the namespace URI will be the default namespace.

Returns: The newly-created element.

Exceptions

xmlpp::internal_error If this node is not an element node, or the child node or the namespace node cannot be created.

◆ add_child_element_with_new_ns() [1/2]

Element* xmlpp::Element::add_child_element_with_new_ns	(	const ustring &	name,
		const ustring &	ns_uri,
		const ustring &	ns_prefix = `ustring()`
	)

Add a child element to this node.

Since libxml++ 3.0:: Replaces Node::add_child_with_new_ns()

Parameters

name	The new node name.
ns_uri	The namespace to associate with the prefix, or to use as the default namespace if no prefix is specified.
ns_prefix	The prefix of the node's namespace. If no prefix is specified then the namespace URI will be the default namespace.

Returns: The newly-created element.

Exceptions

xmlpp::internal_error If this node is not an element node, or the child node or the namespace node cannot be created.

◆ add_child_element_with_new_ns() [2/2]

Element* xmlpp::Element::add_child_element_with_new_ns	(	xmlpp::Node *	previous_sibling,
		const ustring &	name,
		const ustring &	ns_uri,
		const ustring &	ns_prefix = `ustring()`
	)

Add a child element to this node after the specified existing child node.

Since libxml++ 3.0:: Replaces Node::add_child_with_new_ns()

Parameters

previous_sibling	An existing child node.
name	The new node name.
ns_uri	The namespace to associate with the prefix, or to use as the default namespace if no prefix is specified.
ns_prefix	The prefix of the node's namespace. If no prefix is specified then the namespace URI will be the default namespace.

Returns: The newly-created element.

Exceptions

xmlpp::internal_error If this node is not an element node, or the child node or the namespace node cannot be created.

◆ add_child_entity_reference()

EntityReference* xmlpp::Element::add_child_entity_reference ( const ustring & name )

Append a new entity reference node.

The reference can be either an entity reference ("name" or "&name;") or a character reference ("#dec", "#xhex", "&#dec;", or "&#xhex;").

'&' and ';' are optional. If they exist, they are stripped from the stored copy of the name. Node::get_name() returns the name without '&' and ';'. If the Document is written to an XML file, '&' and ';' are written.

Since libxml++ 2.36:

Parameters

name	The name of the entity.

Returns: The new entity reference node.

Exceptions

xmlpp::internal_error

◆ add_child_processing_instruction()

ProcessingInstructionNode* xmlpp::Element::add_child_processing_instruction	(	const ustring &	name,
		const ustring &	content
	)

Append a new processing instruction node.

Since libxml++ 2.36:

Parameters

name	The name of the application to which the instruction is directed.
content	The content of the instruction. This should be unescaped - see ContentNode::set_content().

Returns: The new processing instruction node.

Exceptions

xmlpp::internal_error

◆ add_child_text() [1/2]

TextNode* xmlpp::Element::add_child_text ( const ustring & content = ustring() )

Append a new text node.

Parameters

content The text. This should be unescaped - see ContentNode::set_content().

Returns: The new text node.

Exceptions

xmlpp::internal_error

◆ add_child_text() [2/2]

TextNode* xmlpp::Element::add_child_text	(	xmlpp::Node *	previous_sibling,
		const ustring &	content = `ustring()`
	)

Add a new text node after the specified existing child node.

Since libxml++ 2.24:

Parameters

previous_sibling	An existing child node.
content	The text. This should be unescaped - see ContentNode::set_content().

Returns: The new text node.

Exceptions

xmlpp::internal_error

◆ add_child_text_before()

TextNode* xmlpp::Element::add_child_text_before	(	xmlpp::Node *	next_sibling,
		const ustring &	content = `ustring()`
	)

Add a new text node before the specified existing child node.

Since libxml++ 2.24:

Parameters

next_sibling	An existing child node.
content	The text. This should be unescaped - see ContentNode::set_content().

Returns: The new text node.

Exceptions

xmlpp::internal_error

◆ get_attribute() [1/2]

Attribute* xmlpp::Element::get_attribute	(	const ustring &	name,
		const ustring &	ns_prefix = `ustring()`
	)

Get the attribute with this name, and optionally with this namespace.

Parameters

name	The name of the attribute that will be retrieved.
ns_prefix	Namespace prefix.

Returns: The attribute, or nullptr if no suitable Attribute was found. Is either an AttributeNode*, pointing to an explicitly set attribute, or an AttributeDeclaration*, pointing to the declaration of an attribute with a default value.

◆ get_attribute() [2/2]

const Attribute* xmlpp::Element::get_attribute	(	const ustring &	name,
		const ustring &	ns_prefix = `ustring()`
	)		const

Get the attribute with this name, and optionally with this namespace.

Parameters

name	The name of the attribute that will be retrieved.
ns_prefix	Namespace prefix.

Returns: The attribute, or nullptr if no suitable Attribute was found. Is either an AttributeNode*, pointing to an explicitly set attribute, or an AttributeDeclaration*, pointing to the declaration of an attribute with a default value.

◆ get_attribute_value()

ustring xmlpp::Element::get_attribute_value	(	const ustring &	name,
		const ustring &	ns_prefix = `ustring()`
	)		const

Get the value of the attribute with this name, and optionally with this namespace.

For finer control, you might use get_attribute() and use the methods of the Attribute class.

Parameters

name	The name of the attribute whose value will be retrieved.
ns_prefix	Namespace prefix.

Returns: The text value of the attribute, or an empty string if no such attribute was found.

Deprecated:: 5.6: Use get_attribute_value2() instead.

◆ get_attribute_value2()

std::optional<ustring> xmlpp::Element::get_attribute_value2	(	const ustring &	name,
		const ustring &	ns_prefix = `{}`
	)		const

Get the value of the attribute with this name, and optionally with this namespace.

For finer control, you might use get_attribute() and use the methods of the Attribute class.

Parameters

name	The name of the attribute whose value will be retrieved.
ns_prefix	Namespace prefix.

Returns: The text value of the attribute, or no value if no such attribute was found.

Since libxml++ 5.6:

◆ get_attributes() [1/2]

AttributeList xmlpp::Element::get_attributes ( )

Obtain the list of explicitly set attributes for this element.

Returns: The list of explicitly set attributes.

◆ get_attributes() [2/2]

const_AttributeList xmlpp::Element::get_attributes ( ) const

Obtain the list of explicitly set attributes for this element.

Returns: The list of explicitly set attributes.

◆ get_first_child_text() [1/2]

TextNode* xmlpp::Element::get_first_child_text ( )

Get the first child text content node.

This is a convenience method, meant as an alternative to iterating over all the child nodes to find the first suitable node and then getting the text directly.

Returns: The first text node, if any.

Since libxml++ 3.0:: Replaces get_child_text().

◆ get_first_child_text() [2/2]

const TextNode* xmlpp::Element::get_first_child_text ( ) const

Get the first child text content node.

This is a convenience method, meant as an alternative to iterating over all the child nodes to find the first suitable node and then getting the text directly.

Returns: The first text node, if any.

Since libxml++ 3.0:: Replaces get_child_text().

◆ has_child_text()

bool xmlpp::Element::has_child_text ( ) const

Discover whether one of the child nodes is a text node.

This is a convenience method, meant as an alternative to iterating over all the child nodes and examining them directly.

Returns: Whether this node has a child text node.

◆ remove_attribute()

void xmlpp::Element::remove_attribute	(	const ustring &	name,
		const ustring &	ns_prefix = `ustring()`
	)

Remove the attribute with this name, and optionally with this namespace.

Parameters

name	The name of the attribute to be removed
ns_prefix	Namespace prefix. If specified, the attribute will be removed only if the attribute has this namespace.

◆ set_attribute()

Attribute* xmlpp::Element::set_attribute	(	const ustring &	name,
		const ustring &	value,
		const ustring &	ns_prefix = `ustring()`
	)

Set the value of the attribute with this name, and optionally with this namespace.

A matching attribute will be added if no matching attribute already exists. For finer control, you might want to use get_attribute() and use the methods of the Attribute class.

Parameters

name	The name of the attribute whose value will change.
value	The new value for the attribute
ns_prefix	Namespace prefix. If the prefix has not been declared then this method will throw an exception.

Returns: The attribute that was changed, or nullptr is no suitable Attribute was found.

Exceptions

xmlpp::exception

◆ set_first_child_text()

void xmlpp::Element::set_first_child_text ( const ustring & content )

Set the text of the first text node, adding one if necessary.

This is a convenience method, meant as an alternative to iterating over all the child nodes to find the first suitable node and then setting the text directly.

Parameters

content The text. This should be unescaped - see ContentNode::set_content().

Exceptions

xmlpp::internal_error

Since libxml++ 3.0:: Replaces set_child_text().

◆ set_namespace_declaration()

void xmlpp::Element::set_namespace_declaration	(	const ustring &	ns_uri,
		const ustring &	ns_prefix = `ustring()`
	)

Add a namespace declaration to this node which will apply to this node and all children.

If the added namespace prefix is equal to the prefix associated to the node, the associated namespace of the node itself is updated, but child nodes are not updated. If you use this method on a node after children have been added, it may be necessary to save the XML document and reparse it to get correct namespaces on all nodes.

Parameters

ns_uri	The namespace to associate with the prefix, or to use as the default namespace if no prefix is specified.
ns_prefix	The namespace prefix. If no prefix is specified then the namespace URI will be the default namespace.

Exceptions

xmlpp::exception If a new namespace node cannot be created, e.g. because a namespace with the same prefix but another URI already exists.

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ AttributeList

◆ const_AttributeList

Constructor & Destructor Documentation

◆ Element()

◆ ~Element()

Member Function Documentation

◆ add_child_cdata()

◆ add_child_comment()

◆ add_child_element() [1/2]

◆ add_child_element() [2/2]

◆ add_child_element_before()

◆ add_child_element_before_with_new_ns()

◆ add_child_element_with_new_ns() [1/2]

◆ add_child_element_with_new_ns() [2/2]

◆ add_child_entity_reference()

◆ add_child_processing_instruction()

◆ add_child_text() [1/2]

◆ add_child_text() [2/2]

◆ add_child_text_before()

◆ get_attribute() [1/2]

◆ get_attribute() [2/2]

◆ get_attribute_value()

◆ get_attribute_value2()

◆ get_attributes() [1/2]

◆ get_attributes() [2/2]

◆ get_first_child_text() [1/2]

◆ get_first_child_text() [2/2]

◆ has_child_text()

◆ remove_attribute()

◆ set_attribute()

◆ set_first_child_text()

◆ set_namespace_declaration()