libxml++ 5.6.1

Public Types | Public Member Functions | List of all members
xmlpp::Element Class Reference

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

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

Inheritance diagram for xmlpp::Element:
[legend]

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

## Public Member Functions
| Element (_xmlNode * node)
| ~Element () override
CdataNode * | add_child_cdata (const ustring & content)
| Append a new CDATA node.
CommentNode * | add_child_comment (const ustring & content)
| Append a new comment node.
Element * | add_child_element (const ustring & name, const ustring & ns_prefix=ustring())
| Add a child element to this node.
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.
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.
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.
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.
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.
EntityReference * | add_child_entity_reference (const ustring & name)
| Append a new entity reference node.
ProcessingInstructionNode * | add_child_processing_instruction (const ustring & name, const ustring & content)
| Append a new processing instruction node.
TextNode * | add_child_text (const ustring & content=ustring())
| Append a new text node.
TextNode * | add_child_text (xmlpp::Node * previous_sibling, const ustring & content=ustring())
| Add a new text node after the specified existing child node.
TextNode * | add_child_text_before (xmlpp::Node * next_sibling, const ustring & content=ustring())
| Add a new text node before the specified existing child node.
Attribute * | get_attribute (const ustring & name, const ustring & ns_prefix=ustring())
| Get the attribute with this name, and optionally with this namespace.
const Attribute * | get_attribute (const ustring & name, const ustring & ns_prefix=ustring()) const
| Get the attribute with this name, and optionally with this namespace.
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.
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.
AttributeList | get_attributes ()
| Obtain the list of explicitly set attributes for this element.
const_AttributeList | get_attributes () const
| Obtain the list of explicitly set attributes for this element.
TextNode * | get_first_child_text ()
| Get the first child text content node.
const TextNode * | get_first_child_text () const
| Get the first child text content node.
bool | has_child_text () const
| Discover whether one of the child nodes is a text node.
void | remove_attribute (const ustring & name, const ustring & ns_prefix=ustring())
| Remove the attribute with this name, and optionally with this namespace.
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.
void | set_first_child_text (const ustring & content)
| Set the text of the first text node, adding one if necessary.
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.
Public Member Functions inherited from xmlpp::Node
| Node (_xmlNode * node)
| ~Node () override
| Destructor.
const _xmlNode * | cobj () const noexcept
| Access the underlying libxml implementation.
_xmlNode * | cobj () noexcept
| Access the underlying libxml implementation.
bool | eval_to_boolean (const ustring & xpath, const PrefixNsMap & namespaces, XPathResultType * result_type=nullptr) const
| Evaluate an XPath expression.
bool | eval_to_boolean (const ustring & xpath, XPathResultType * result_type=nullptr) const
| Evaluate an XPath expression.
double | eval_to_number (const ustring & xpath, const PrefixNsMap & namespaces, XPathResultType * result_type=nullptr) const
| Evaluate an XPath expression.
double | eval_to_number (const ustring & xpath, XPathResultType * result_type=nullptr) const
| Evaluate an XPath expression.
ustring | eval_to_string (const ustring & xpath, const PrefixNsMap & namespaces, XPathResultType * result_type=nullptr) const
| Evaluate an XPath expression.
ustring | eval_to_string (const ustring & xpath, XPathResultType * result_type=nullptr) const
| Evaluate an XPath expression.
std::variant< NodeSet, bool, double, ustring > | eval_xpath (const ustring & xpath, const PrefixNsMap & namespaces={})
| Evaluate an XPath expression.
std::variant< const_NodeSet, bool, double, ustring > | eval_xpath (const ustring & xpath, const PrefixNsMap & namespaces={}) const
| Evaluate an XPath expression.
NodeSet | find (const ustring & xpath)
| Find nodes from an XPath expression.
const_NodeSet | find (const ustring & xpath) const
| Find nodes from an XPath expression.
NodeSet | find (const ustring & xpath, const PrefixNsMap & namespaces)
| Find nodes from an XPath expression.
const_NodeSet | find (const ustring & xpath, const PrefixNsMap & namespaces) const
| Find nodes from an XPath expression.
NodeList | get_children (const ustring & name=ustring())
| Obtain the list of child nodes.
const_NodeList | get_children (const ustring & name=ustring()) const
| Obtain the list of child nodes.
Node * | get_first_child (const ustring & name=ustring())
| Get the first child of this node.
const Node * | get_first_child (const ustring & name=ustring()) const
| Get the first child of this node.
int | get_line () const
| Discover at what line number this node occurs in the XML file.
ustring | get_name () const
| Get the name of this node.
std::optional< ustring > | get_name2 () const
| Get the name of this node.
ustring | get_namespace_prefix () const
| Get the namespace prefix of this node.
std::optional< ustring > | get_namespace_prefix2 () const
| Get the namespace prefix of this node.
ustring | get_namespace_uri () const
| Get the namespace URI of this node.
std::optional< ustring > | get_namespace_uri2 () const
| Get the namespace URI of this node.
Node * | get_next_sibling ()
| Get the next sibling for this node.
const Node * | get_next_sibling () const
| Get the next sibling for this node.
Element * | get_parent ()
| Get the parent element for this node.
const Element * | get_parent () const
| Get the parent element for this node.
ustring | get_path () const
| Get the XPath of this node.
std::optional< ustring > | get_path2 () const
| Get the XPath of this node.
Node * | get_previous_sibling ()
| Get the previous sibling for this node.
const Node * | get_previous_sibling () const
| Get the previous sibling for this node .
Node * | import_node (const Node * node, bool recursive=true)
| Import node(s) from another document under this node, without affecting the source node.
void | set_name (const ustring & name)
| Set the name of this node.
void | set_namespace (const ustring & ns_prefix)
| Set the namespace prefix used by the node.
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.
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.
static void | remove_node (Node * node)
| Remove a node and its children.
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.