pugi::xml_node Class Reference

Inheritance diagram for pugi::xml_node:

Inheritance graph
[legend]
Collaboration diagram for pugi::xml_node:

Collaboration graph
[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.


Generated on Sun Nov 8 22:15:19 2009 for pugixml by  doxygen 1.4.6-NO