Represents a reference to a single XML element. More...

#include <element.hpp>

Public Member Functions
	Element (const Element &e)
	Construct a new reference to an element. More...

	Element (const QName &qname)
	Construct an element, creating a dummy ElementTree to contain it. More...

	Element (const QName &qname, kv_list attribs)
	C++11: construct an element, creating a dummy ElementTree to contain it. More...

	~Element ()
	Destroy the reference to the element, deallocating the underlying tree if this was the last reference.

bool	ancestorOf (const Element &e) const
	Return true if this is an ancestor of some element.

void	append (Element &e)
	Append an element to this element. More...

AttrMap	attrib () const
	Return the element's attribute dictionary.

ChildIterator	begin () const
	Produce a ChildIterator pointing at the first child.

Nullable< Element >	child () const
	Return the first, if any exist. More...

Nullable< Element >	child (const QName &qn) const
	Return the first child matching a name, if any exist. More...

vector< Element >	children (const QName &qn) const
	Return children matching a name. More...

vector< Element >	children () const
	Return all children. More...

Element	copy ()
	Copy this element and all elements below it to a new document, returning a reference to the newly copied element.

ChildIterator	end () const
	Produce a ChildIterator pointing past the final child.

Element	ensurechild (const QName &qn)
	Like child(), except appends the element if it was missing. More...

void	ensurens (const string &uri)
	Ensure a namespace is in scope for this element, or is defined on this element. More...

Nullable< Element >	find (const XPath &expr) const
	Execute an XPath expression rooted on this element. More...

vector< Element >	findall (const XPath &expr) const
	Return all Elements matching the expression. More...

string	findtext (const XPath &expr, const string &default_="") const
	Return the text part of the first matching element. More...

string	get (const QName &qname, const string &default_="") const
	Fetch the value of an attribute. More...

Nullable< Element >	getnext () const
	Return the next sibling element, if any.

Nullable< Element >	getparent () const
	Return the parent element, if this element is not the document root.

Nullable< Element >	getprev () const
	Return the previous sibling element, if any.

ElementTree	getroottree () const
	Return the ElementTree this element belongs to.

void	graft ()
	Remove this element from its parent, moving any child nodes to the element's old place in the DOM tree. More...

void	insert (size_t i, Element &e)
	Insert an element as a child of this element at a specific position. More...

string	ns () const
	Return the element's namespace URI, or the empty string if it has none.

void	ns (const string &ns)
	Set the element's namespace URI, or the empty string to remove any existing namespace.

bool	operator!= (const Element &other) const
	Return false if the identity of this Element is equal to another Element, i.e. More...

Element &	operator= (const Element &)
	Replace this element reference with an element. More...

bool	operator== (const Element &other) const
	Return true if the identity of this element is equal to another Element, i.e. More...

Element	operator[] (size_t i)
	Return a child element. More...

QName	qname () const
	Return the element's QName.

void	qname (const QName &qname)
	Set the element's QName.

void	remove (Element &e)
	Remove a child element. More...

void	remove ()
	Remove this element from its parent, if any. More...

vector< Element >	removeall (const XPath &expr)
	Like XPath::findall, except remove each discovered element before returning it.

size_t	size () const
	Return the number of children this element has.

string	tag () const
	Return the element's tag name.

void	tag (const string &tag)
	Set the element's tag name.

string	tail () const
	Return the element's tail part, or the empty string. More...

void	tail (const string &s)
	Set the element's tail part. More...

string	text () const
	Return the element's text part, or the empty string. More...

void	text (const string &s)
	Set the element's text part. More...

Detailed Description

Represents a reference to a single XML element.

Constructor & Destructor Documentation

etree::Element::Element ( const Element & e )

Construct a new reference to an element.

Parameters

e	Element to copy reference to.

etree::Element::Element ( const QName & qname )

Construct an element, creating a dummy ElementTree to contain it.

Due to the need to have a dummy document to contain orphaned elements, it is better to use SubElement() when possible.

Parameters

qname New element name.

etree::Element::Element	(	const QName &	qname,
		kv_list	attribs
	)

C++11: construct an element, creating a dummy ElementTree to contain it.

Due to the need to have a dummy document to contain orphaned elements, it is better to use SubElement() when possible.

Parameters

qname	New element name.
attribs	List of attribute name-value pairs from initialization list.

Member Function Documentation

void etree::Element::append ( Element & e )

Append an element to this element.

This unlinks an element from its parent document and tree location, relinks it to this element's document, and inserts it as the last child of this element.

Note: All existing Element objects automatically update to the new location.

Parameters

e	Element to append as a child.

Nullable< Element > etree::Element::child ( ) const

Return the first, if any exist.

Returns: Element, if any, otherwise an empty nullable.

Nullable< Element > etree::Element::child ( const QName & qn ) const

Return the first child matching a name, if any exist.

Parameters

qn	Name of the child to locate.

Returns: Element, if any, otherwise an empty nullable.

std::vector< Element > etree::Element::children ( const QName & qn ) const

Return children matching a name.

Parameters

qn	Name of the children to locate.

Returns: Vector of elements.

std::vector< Element > etree::Element::children ( ) const

Return all children.

Returns: Vector of elements.

Element etree::Element::ensurechild ( const QName & qn )

Like child(), except appends the element if it was missing.

Parameters

qn	Name of the child to create or locate.

Returns: The element.

void etree::Element::ensurens ( const string & uri )

Ensure a namespace is in scope for this element, or is defined on this element.

Consider calling this if you're going to be defining lots of subelements or attributes on this element belonging to the namespace.

Parameters

uri	The namespace URI.

Nullable< Element > etree::Element::find ( const XPath & expr ) const

Execute an XPath expression rooted on this element.

Parameters

expr	Expression to element.

Returns: Vector of matching elements.

std::vector< Element > etree::Element::findall ( const XPath & expr ) const

Return all Elements matching the expression.

Parameters

expr	XPath expression to match.

Returns: Matching elements.

string etree::Element::findtext	(	const XPath &	expr,
		const string &	default_ = `""`
	)		const

Return the text part of the first matching element.

Parameters

expr	XPath expression to match.
default_	String to return if text is not found.

Returns: Text part of the first matching element, or the empty string.

string etree::Element::get	(	const QName &	qname,
		const string &	default_ = `""`
	)		const

Fetch the value of an attribute.

Parameters

qname	Attribute name to fetch.
default_	Default value if attribute is missing.

Returns: String attribute value, or the default.

void etree::Element::graft ( )

Remove this element from its parent, moving any child nodes to the element's old place in the DOM tree.

You cannot graft the root node.

auto elem = etree::fromstring(
    "<root>"
        "<tag1/> Hello"
        "<tag2>"
            "<tag3/>"
        "</tag2> there"
    "</root>"
);
elem.child("tag2")->graft();
assert(etree::tostring(elem) == (
    "<root>"
        "<tag1/> Hello"
        "<tag3/> there"
    "</root>"
));

void etree::Element::insert	(	size_t	i,
		Element &	e
	)

Insert an element as a child of this element at a specific position.

This unlinks an element from its parent document and tree location, relinks it to this element's document, and inserts it as the specified child of this element.

Note: All existing Element objects automatically update to the new location.

Parameters

i	Index to insert element at (0..size()-1). If the index is greater than size(), behaves like append().
e	Element to append as a child.

bool etree::Element::operator!= ( const Element & other ) const

Return false if the identity of this Element is equal to another Element, i.e.

both refer to the same DOM node.

Element & etree::Element::operator= ( const Element & e )

Replace this element reference with an element.

Note the underlying DOM node is not modified, only the reference is updated.

bool etree::Element::operator== ( const Element & other ) const

Return true if the identity of this element is equal to another Element, i.e.

both refer to the same DOM node.

Element etree::Element::operator[] ( size_t i )

Return a child element.

Valid indices are 0..size().

void etree::Element::remove ( Element & e )

Remove a child element.

The child is moved to an empty document of its own. For this reason, calling remove() followed by insert() or append() is suboptimal; you should call insert() or append() directly.

Parameters

e Element

void etree::Element::remove ( )

Remove this element from its parent, if any.

The element is moved to an empty document of its own. For this reason, calling remove() followed by insert() or append() is suboptimal; you should call insert() or append() directly.

string etree::Element::tail ( ) const

Return the element's tail part, or the empty string.

The tail part is any text or CDATA nodes contained immediately following the element's end tag, but before the next sibling.

1 <who>person<child>123</child>known</who>me

In this example, who's tail part is the string "me", and child's tail part is the string "known".

void etree::Element::tail ( const string & s )

Set the element's tail part.

Parameters

s	New tail part.

string etree::Element::text ( ) const

Return the element's text part, or the empty string.

The text part is any text or CDATA nodes contained immediately underneath the element in the DOM tree, but before the first child element.

1 <who>person<child>123</child>known</who>me

In this example, who's text part is the string "person".

void etree::Element::text ( const string & s )

Set the element's text part.

Parameters

s	New text part.

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

element.hpp
element.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation