pugi::xml_node Class Reference

Inheritance diagram for pugi::xml_node:

[legend]Collaboration diagram for pugi::xml_node:

[legend]List of all members.

---

Detailed Description

A light-weight wrapper for manipulating nodes in DOM tree.

Note: xml_node does not allocate any memory for the node it wraps; it only wraps a pointer to existing node.

Public Types
typedef xml_node_iterator	iterator
	Node iterator type (for child nodes).
typedef xml_attribute_iterator	attribute_iterator
	Node iterator type (for child nodes).
Public Member Functions
	xml_node ()
	Default ctor.
	operator unspecified_bool_type () const
	Safe bool conversion.
bool	operator! () const
bool	operator== (const xml_node &r) const
	Compare wrapped pointer to the attribute to the pointer that is wrapped by r.
bool	operator!= (const xml_node &r) const
	Compare wrapped pointer to the attribute to the pointer that is wrapped by r.
bool	operator< (const xml_node &r) const
	Compare wrapped pointer to the attribute to the pointer that is wrapped by r.
bool	operator> (const xml_node &r) const
	Compare wrapped pointer to the attribute to the pointer that is wrapped by r.
bool	operator<= (const xml_node &r) const
	Compare wrapped pointer to the attribute to the pointer that is wrapped by r.
bool	operator>= (const xml_node &r) const
	Compare wrapped pointer to the attribute to the pointer that is wrapped by r.
iterator	begin () const
	Access the begin iterator for this node's collection of child nodes.
iterator	end () const
	Access the end iterator for this node's collection of child nodes.
attribute_iterator	attributes_begin () const
	Access the begin iterator for this node's collection of attributes.
attribute_iterator	attributes_end () const
	Access the end iterator for this node's collection of attributes.
bool	empty () const
	Check if node is empty.
xml_node_type	type () const
	Get node type.
const char *	name () const
	Get node name (element name for element nodes, PI target for PI).
const char *	value () const
	Get node value (comment/PI/PCDATA/CDATA contents, depending on node type).
xml_node	child (const char *name) const
	Get child with the specified name.
xml_node	child_w (const char *name) const
	Get child with the name that matches specified pattern.
xml_attribute	attribute (const char *name) const
	Get attribute with the specified name.
xml_attribute	attribute_w (const char *name) const
	Get attribute with the name that matches specified pattern.
xml_node	next_sibling (const char *name) const
	Get first of following sibling nodes with the specified name.
xml_node	next_sibling_w (const char *name) const
	Get first of the following sibling nodes with the name that matches specified pattern.
xml_node	next_sibling () const
	Get following sibling.
xml_node	previous_sibling (const char *name) const
	Get first of preceding sibling nodes with the specified name.
xml_node	previous_sibling_w (const char *name) const
	Get first of the preceding sibling nodes with the name that matches specified pattern.
xml_node	previous_sibling () const
	Get preceding sibling.
xml_node	parent () const
	Get parent node.
xml_node	root () const
	Get root of DOM tree this node belongs to.
const char *	child_value () const
	Get child value of current node; that is, value of the first child node of type PCDATA/CDATA.
const char *	child_value (const char *name) const
	Get child value of child with specified name.
const char *	child_value_w (const char *name) const
	Get child value of child with name that matches the specified pattern.
bool	set_name (const char *rhs)
	Set node name to rhs (for PI/element nodes).
bool	set_value (const char *rhs)
	Set node value to rhs (for PI/PCDATA/CDATA/comment nodes).
xml_attribute	append_attribute (const char *name)
	Add attribute with specified name (for element nodes).
xml_attribute	insert_attribute_after (const char *name, const xml_attribute &attr)
	Insert attribute with specified name after attr (for element nodes).
xml_attribute	insert_attribute_before (const char *name, const xml_attribute &attr)
	Insert attribute with specified name before attr (for element nodes).
xml_attribute	append_copy (const xml_attribute &proto)
	Add a copy of the specified attribute (for element nodes).
xml_attribute	insert_copy_after (const xml_attribute &proto, const xml_attribute &attr)
	Insert a copy of the specified attribute after attr (for element nodes).
xml_attribute	insert_copy_before (const xml_attribute &proto, const xml_attribute &attr)
	Insert a copy of the specified attribute before attr (for element nodes).
xml_node	append_child (xml_node_type type=node_element)
	Add child node with specified type (for element nodes).
xml_node	insert_child_after (xml_node_type type, const xml_node &node)
	Insert child node with specified type after node (for element nodes).
xml_node	insert_child_before (xml_node_type type, const xml_node &node)
	Insert child node with specified type before node (for element nodes).
xml_node	append_copy (const xml_node &proto)
	Add a copy of the specified node as a child (for element nodes).
xml_node	insert_copy_after (const xml_node &proto, const xml_node &node)
	Insert a copy of the specified node after node (for element nodes).
xml_node	insert_copy_before (const xml_node &proto, const xml_node &node)
	Insert a copy of the specified node before node (for element nodes).
void	remove_attribute (const xml_attribute &a)
	Remove specified attribute.
void	remove_attribute (const char *name)
	Remove attribute with the specified name, if any.
void	remove_child (const xml_node &n)
	Remove specified child.
void	remove_child (const char *name)
	Remove child with the specified name, if any.
xml_attribute	first_attribute () const
	Get first attribute.
xml_attribute	last_attribute () const
	Get last attribute.
template<typename OutputIterator>
void	all_elements_by_name (const char *name, OutputIterator it) const
	Get all elements from subtree with given name.
template<typename OutputIterator>
void	all_elements_by_name_w (const char *name, OutputIterator it) const
	Get all elements from subtree with name that matches given pattern.
xml_node	first_child () const
	Get first child.
xml_node	last_child () const
	Get last child.
template<typename Predicate>
xml_attribute	find_attribute (Predicate pred) const
	Find attribute using predicate.
template<typename Predicate>
xml_node	find_child (Predicate pred) const
	Find child node using predicate.
template<typename Predicate>
xml_node	find_node (Predicate pred) const
	Find node from subtree using predicate.
xml_node	find_child_by_attribute (const char *name, const char *attr_name, const char *attr_value) const
	Find child node with the specified name that has specified attribute.
xml_node	find_child_by_attribute_w (const char *name, const char *attr_name, const char *attr_value) const
	Find child node with the specified name that has specified attribute (use pattern matching for node name and attribute name/value).
xml_node	find_child_by_attribute (const char *attr_name, const char *attr_value) const
	Find child node that has specified attribute.
xml_node	find_child_by_attribute_w (const char *attr_name, const char *attr_value) const
	Find child node that has specified attribute (use pattern matching for attribute name/value).
std::string	path (char delimiter= '/') const
	Get the absolute node path from root as a text string.
xml_node	first_element_by_path (const char *path, char delimiter= '/') const
	Search for a node by path.
bool	traverse (xml_tree_walker &walker)
	Recursively traverse subtree with xml_tree_walker.
xpath_node	select_single_node (const char *query) const
	Select single node by evaluating XPath query.
xpath_node	select_single_node (const xpath_query &query) const
	Select single node by evaluating XPath query.
xpath_node_set	select_nodes (const char *query) const
	Select node set by evaluating XPath query.
xpath_node_set	select_nodes (const xpath_query &query) const
	Select node set by evaluating XPath query.
unsigned int	document_order () const
void	print (xml_writer &writer, const char *indent="\t", unsigned int flags=format_default, unsigned int depth=0) const
	Print subtree to writer.
void	print (std::ostream &os, const char *indent="\t", unsigned int flags=format_default, unsigned int depth=0) const
	Print subtree to stream.
int	offset_debug () const
	Get node offset in parsed file/string (in bytes) for debugging purposes.
Protected Types
typedef xml_node_struct *xml_node::*	unspecified_bool_type
Protected Member Functions
	xml_node (xml_node_struct *p)
void	precompute_document_order_impl ()
xml_allocator &	get_allocator () const
Protected Attributes
xml_node_struct *	_root
Friends
class	xml_node_iterator

---

Member Typedef Documentation

typedef xml_node_iterator pugi::xml_node::iterator

Node iterator type (for child nodes). See also: xml_node_iterator

typedef xml_attribute_iterator pugi::xml_node::attribute_iterator

Node iterator type (for child nodes). See also: xml_attribute_iterator

---

Constructor & Destructor Documentation

pugi::xml_node::xml_node (   )

Default ctor. Constructs an empty node.

---

Member Function Documentation

pugi::xml_node::operator unspecified_bool_type (   )  const

Safe bool conversion. Allows xml_node to be used in a context where boolean variable is expected, such as 'if (node)'.

bool pugi::xml_node::operator== (  const xml_node &  r  )  const

Compare wrapped pointer to the attribute to the pointer that is wrapped by r. Parameters: r  - value to compare to Returns: comparison result

bool pugi::xml_node::operator!= (  const xml_node &  r  )  const

Compare wrapped pointer to the attribute to the pointer that is wrapped by r. Parameters: r  - value to compare to Returns: comparison result

bool pugi::xml_node::operator< (  const xml_node &  r  )  const

Compare wrapped pointer to the attribute to the pointer that is wrapped by r. Parameters: r  - value to compare to Returns: comparison result

bool pugi::xml_node::operator> (  const xml_node &  r  )  const

Compare wrapped pointer to the attribute to the pointer that is wrapped by r. Parameters: r  - value to compare to Returns: comparison result

bool pugi::xml_node::operator<= (  const xml_node &  r  )  const

Compare wrapped pointer to the attribute to the pointer that is wrapped by r. Parameters: r  - value to compare to Returns: comparison result

bool pugi::xml_node::operator>= (  const xml_node &  r  )  const

Compare wrapped pointer to the attribute to the pointer that is wrapped by r. Parameters: r  - value to compare to Returns: comparison result

iterator pugi::xml_node::begin (   )  const

Access the begin iterator for this node's collection of child nodes. Returns: iterator that points to the first child node, or past-the-end iterator if node is empty or has no children

iterator pugi::xml_node::end (   )  const

Access the end iterator for this node's collection of child nodes. Returns: past-the-end iterator for child list

attribute_iterator pugi::xml_node::attributes_begin (   )  const

Access the begin iterator for this node's collection of attributes. Returns: iterator that points to the first attribute, or past-the-end iterator if node is empty or has no attributes

attribute_iterator pugi::xml_node::attributes_end (   )  const

Access the end iterator for this node's collection of attributes. Returns: past-the-end iterator for attribute list

bool pugi::xml_node::empty (   )  const

Check if node is empty. Returns: true if node is empty, false otherwise

xml_node_type pugi::xml_node::type (   )  const

Get node type. Returns: node type; node_null for empty nodes

const char* pugi::xml_node::name (   )  const

Get node name (element name for element nodes, PI target for PI). Returns: node name, if any; "" otherwise

const char* pugi::xml_node::value (   )  const

Get node value (comment/PI/PCDATA/CDATA contents, depending on node type). Returns: node value, if any; "" otherwise

xml_node pugi::xml_node::child (  const char *  name  )  const

Get child with the specified name. Parameters: name  - child name Returns: child with the specified name, if any; empty node otherwise

xml_node pugi::xml_node::child_w (  const char *  name  )  const

Get child with the name that matches specified pattern. Parameters: name  - child name pattern Returns: child with the name that matches pattern, if any; empty node otherwise

xml_attribute pugi::xml_node::attribute (  const char *  name  )  const

Get attribute with the specified name. Parameters: name  - attribute name Returns: attribute with the specified name, if any; empty attribute otherwise

xml_attribute pugi::xml_node::attribute_w (  const char *  name  )  const

Get attribute with the name that matches specified pattern. Parameters: name  - attribute name pattern Returns: attribute with the name that matches pattern, if any; empty attribute otherwise

xml_node pugi::xml_node::next_sibling (  const char *  name  )  const

Get first of following sibling nodes with the specified name. Parameters: name  - sibling name Returns: node with the specified name, if any; empty node otherwise

xml_node pugi::xml_node::next_sibling_w (  const char *  name  )  const

Get first of the following sibling nodes with the name that matches specified pattern. Parameters: name  - sibling name pattern Returns: node with the name that matches pattern, if any; empty node otherwise

xml_node pugi::xml_node::next_sibling (   )  const

Get following sibling. Returns: following sibling node, if any; empty node otherwise

xml_node pugi::xml_node::previous_sibling (  const char *  name  )  const

Get first of preceding sibling nodes with the specified name. Parameters: name  - sibling name Returns: node with the specified name, if any; empty node otherwise

xml_node pugi::xml_node::previous_sibling_w (  const char *  name  )  const

Get first of the preceding sibling nodes with the name that matches specified pattern. Parameters: name  - sibling name pattern Returns: node with the name that matches pattern, if any; empty node otherwise

xml_node pugi::xml_node::previous_sibling (   )  const

Get preceding sibling. Returns: preceding sibling node, if any; empty node otherwise

xml_node pugi::xml_node::parent (   )  const

Get parent node. Returns: parent node if any; empty node otherwise

xml_node pugi::xml_node::root (   )  const

Get root of DOM tree this node belongs to. Returns: tree root

const char* pugi::xml_node::child_value (   )  const

Get child value of current node; that is, value of the first child node of type PCDATA/CDATA. Returns: child value of current node, if any; "" otherwise

const char* pugi::xml_node::child_value (  const char *  name  )  const

Get child value of child with specified name. See also: child_value node.child_value(name) is equivalent to node.child(name).child_value() Parameters: name  - child name Returns: child value of specified child node, if any; "" otherwise

const char* pugi::xml_node::child_value_w (  const char *  name  )  const

Get child value of child with name that matches the specified pattern. See also: child_value node.child_value_w(name) is equivalent to node.child_w(name).child_value() Parameters: name  - child name pattern Returns: child value of specified child node, if any; "" otherwise

bool pugi::xml_node::set_name (  const char *  rhs  )

Set node name to rhs (for PI/element nodes). See also: name Parameters: rhs  - new node name Returns: success flag (call fails if node is of the wrong type or there is not enough memory)

bool pugi::xml_node::set_value (  const char *  rhs  )

Set node value to rhs (for PI/PCDATA/CDATA/comment nodes). See also: value Parameters: rhs  - new node value Returns: success flag (call fails if node is of the wrong type or there is not enough memory)

xml_attribute pugi::xml_node::append_attribute (  const char *  name  )

Add attribute with specified name (for element nodes). Parameters: name  - attribute name Returns: added attribute, or empty attribute if there was an error (wrong node type)

xml_attribute pugi::xml_node::insert_attribute_after (  const char *  name, const xml_attribute &  attr )

Insert attribute with specified name after attr (for element nodes). Parameters: name  - attribute name attr  - attribute to insert a new one after Returns: inserted attribute, or empty attribute if there was an error (wrong node type, or attr does not belong to node)

xml_attribute pugi::xml_node::insert_attribute_before (  const char *  name, const xml_attribute &  attr )

Insert attribute with specified name before attr (for element nodes). Parameters: name  - attribute name attr  - attribute to insert a new one before Returns: inserted attribute, or empty attribute if there was an error (wrong node type, or attr does not belong to node)

xml_attribute pugi::xml_node::append_copy (  const xml_attribute &  proto  )

Add a copy of the specified attribute (for element nodes). Parameters: proto  - attribute prototype which is to be copied Returns: inserted attribute, or empty attribute if there was an error (wrong node type)

xml_attribute pugi::xml_node::insert_copy_after (  const xml_attribute &  proto, const xml_attribute &  attr )

Insert a copy of the specified attribute after attr (for element nodes). Parameters: proto  - attribute prototype which is to be copied attr  - attribute to insert a new one after Returns: inserted attribute, or empty attribute if there was an error (wrong node type, or attr does not belong to node)

xml_attribute pugi::xml_node::insert_copy_before (  const xml_attribute &  proto, const xml_attribute &  attr )

Insert a copy of the specified attribute before attr (for element nodes). Parameters: proto  - attribute prototype which is to be copied attr  - attribute to insert a new one before Returns: inserted attribute, or empty attribute if there was an error (wrong node type, or attr does not belong to node)

xml_node pugi::xml_node::append_child (  xml_node_type  type = node_element  )

Add child node with specified type (for element nodes). Parameters: type  - node type Returns: added node, or empty node if there was an error (wrong node type)

xml_node pugi::xml_node::insert_child_after (  xml_node_type  type, const xml_node &  node )

Insert child node with specified type after node (for element nodes). Parameters: type  - node type node  - node to insert a new one after Returns: inserted node, or empty node if there was an error (wrong node type, or node is not a child of this node)

xml_node pugi::xml_node::insert_child_before (  xml_node_type  type, const xml_node &  node )

Insert child node with specified type before node (for element nodes). Parameters: type  - node type node  - node to insert a new one before Returns: inserted node, or empty node if there was an error (wrong node type, or node is not a child of this node)

xml_node pugi::xml_node::append_copy (  const xml_node &  proto  )

Add a copy of the specified node as a child (for element nodes). Parameters: proto  - node prototype which is to be copied Returns: inserted node, or empty node if there was an error (wrong node type)

xml_node pugi::xml_node::insert_copy_after (  const xml_node &  proto, const xml_node &  node )

Insert a copy of the specified node after node (for element nodes). Parameters: proto  - node prototype which is to be copied node  - node to insert a new one after Returns: inserted node, or empty node if there was an error (wrong node type, or node is not a child of this node)

xml_node pugi::xml_node::insert_copy_before (  const xml_node &  proto, const xml_node &  node )

Insert a copy of the specified node before node (for element nodes). Parameters: proto  - node prototype which is to be copied node  - node to insert a new one before Returns: inserted node, or empty node if there was an error (wrong node type, or node is not a child of this node)

void pugi::xml_node::remove_attribute (  const xml_attribute &  a  )

Remove specified attribute. Parameters: a  - attribute to be removed

void pugi::xml_node::remove_attribute (  const char *  name  )

Remove attribute with the specified name, if any. Parameters: name  - attribute name

void pugi::xml_node::remove_child (  const xml_node &  n  )

Remove specified child. Parameters: n  - child node to be removed

void pugi::xml_node::remove_child (  const char *  name  )

Remove child with the specified name, if any. Parameters: name  - child name

xml_attribute pugi::xml_node::first_attribute (   )  const

Get first attribute. Returns: first attribute, if any; empty attribute otherwise

xml_attribute pugi::xml_node::last_attribute (   )  const

Get last attribute. Returns: last attribute, if any; empty attribute otherwise

template<typename OutputIterator> void pugi::xml_node::all_elements_by_name (  const char *  name, OutputIterator  it )  const [inline]

Get all elements from subtree with given name. Parameters: name  - node name it  - output iterator (for example, std::back_insert_iterator (result of std::back_inserter))

template<typename OutputIterator> void pugi::xml_node::all_elements_by_name_w (  const char *  name, OutputIterator  it )  const [inline]

Get all elements from subtree with name that matches given pattern. Parameters: name  - node name pattern it  - output iterator (for example, std::back_insert_iterator (result of std::back_inserter))

xml_node pugi::xml_node::first_child (   )  const

Get first child. Returns: first child, if any; empty node otherwise

xml_node pugi::xml_node::last_child (   )  const

Get last child. Returns: last child, if any; empty node otherwise

template<typename Predicate> xml_attribute pugi::xml_node::find_attribute (  Predicate  pred  )  const [inline]

Find attribute using predicate. Parameters: pred  - predicate, that takes xml_attribute and returns bool Returns: first attribute for which predicate returned true, or empty attribute

template<typename Predicate> xml_node pugi::xml_node::find_child (  Predicate  pred  )  const [inline]

Find child node using predicate. Parameters: pred  - predicate, that takes xml_node and returns bool Returns: first child node for which predicate returned true, or empty node

template<typename Predicate> xml_node pugi::xml_node::find_node (  Predicate  pred  )  const [inline]

Find node from subtree using predicate. Parameters: pred  - predicate, that takes xml_node and returns bool Returns: first node from subtree for which predicate returned true, or empty node

xml_node pugi::xml_node::find_child_by_attribute (  const char *  name, const char *  attr_name, const char *  attr_value )  const

Find child node with the specified name that has specified attribute. Parameters: name  - child node name attr_name  - attribute name of child node attr_value  - attribute value of child node Returns: first matching child node, or empty node

xml_node pugi::xml_node::find_child_by_attribute_w (  const char *  name, const char *  attr_name, const char *  attr_value )  const

Find child node with the specified name that has specified attribute (use pattern matching for node name and attribute name/value). Parameters: name  - pattern for child node name attr_name  - pattern for attribute name of child node attr_value  - pattern for attribute value of child node Returns: first matching child node, or empty node

xml_node pugi::xml_node::find_child_by_attribute (  const char *  attr_name, const char *  attr_value )  const

Find child node that has specified attribute. Parameters: attr_name  - attribute name of child node attr_value  - attribute value of child node Returns: first matching child node, or empty node

xml_node pugi::xml_node::find_child_by_attribute_w (  const char *  attr_name, const char *  attr_value )  const

Find child node that has specified attribute (use pattern matching for attribute name/value). Parameters: attr_name  - pattern for attribute name of child node attr_value  - pattern for attribute value of child node Returns: first matching child node, or empty node

std::string pugi::xml_node::path (  char  delimiter = '/'  )  const

Get the absolute node path from root as a text string. Parameters: delimiter  - delimiter character to insert between element names Returns: path string (e.g. '/bookstore/book/author').

xml_node pugi::xml_node::first_element_by_path (  const char *  path, char  delimiter = '/' )  const

Search for a node by path. Parameters: path  - path string; e.g. './foo/bar' (relative to node), '/foo/bar' (relative to root), '../foo/bar'. delimiter  - delimiter character to use while tokenizing path Returns: matching node, if any; empty node otherwise

bool pugi::xml_node::traverse (  xml_tree_walker &  walker  )

Recursively traverse subtree with xml_tree_walker. See also: xml_tree_walker::begin xml_tree_walker::for_each xml_tree_walker::end Parameters: walker  - tree walker to traverse subtree with Returns: traversal result

xpath_node pugi::xml_node::select_single_node (  const char *  query  )  const

Select single node by evaluating XPath query. Parameters: query  - query string Returns: first node from the resulting node set by document order, or empty node if none found

xpath_node pugi::xml_node::select_single_node (  const xpath_query &  query  )  const

Select single node by evaluating XPath query. Parameters: query  - compiled query Returns: first node from the resulting node set by document order, or empty node if none found

xpath_node_set pugi::xml_node::select_nodes (  const char *  query  )  const

Select node set by evaluating XPath query. Parameters: query  - query string Returns: resulting node set

xpath_node_set pugi::xml_node::select_nodes (  const xpath_query &  query  )  const

Select node set by evaluating XPath query. Parameters: query  - compiled query Returns: resulting node set

void pugi::xml_node::print (  xml_writer &  writer, const char *  indent = "\t", unsigned int  flags = format_default, unsigned int  depth = 0 )  const

Print subtree to writer. Parameters: writer  - writer object indent  - indentation string flags  - formatting flags depth  - starting depth (used for indentation)

void pugi::xml_node::print (  std::ostream &  os, const char *  indent = "\t", unsigned int  flags = format_default, unsigned int  depth = 0 )  const

Print subtree to stream. Parameters: os  - output stream indent  - indentation string flags  - formatting flags depth  - starting depth (used for indentation) Deprecated: Use print() with xml_writer_stream instead

int pugi::xml_node::offset_debug (   )  const

Get node offset in parsed file/string (in bytes) for debugging purposes. Returns: offset in bytes to start of node data, or -1 in case of error Note: This will return -1 if node information changed to the extent that it's no longer possible to calculate offset, for example if element node name has significantly changed; this is guaranteed to return correct offset only for nodes that have not changed since parsing.

---