Main Page | Namespace List | Class Hierarchy | Alphabetical List | Compound List | File List | Namespace Members | Compound Members

Dv::Xml::Node::Ref Class Reference

A reference to an xml::node object. More...

#include <node.h>

Inheritance diagram for Dv::Xml::Node::Ref:

Inheritance graph
[legend]
Collaboration diagram for Dv::Xml::Node::Ref:

Collaboration graph
[legend]
List of all members.

Public Member Functions

 Ref (xml::node &node)
 Construct a Dv::Xml::Node::Ref out of a (copy of a) xml::node object.

std::string name () const throw (Dv::Xml::Exception)
Dv::Xml::Node::Refname (const std::string &nm) throw (Dv::Xml::Exception)
 Set name of underlying xml::node.

bool nil () const
 Is this a "non-null" Dv::Xml::Node::Ref, i.e.

bool operator! () const
 Is this not a valid Dv::Xml::Node::Ref, i.e.

 operator const xml::node * () const
 Retrieve underlying xml::node for this Dv::Xml::Node::Ref.

Ref end () const throw (Dv::Xml::Exception)
 Return Ref that points past the last child of this node.

Ref operator++ () throw (Dv::Xml::Exception)
 Return next child of parent with same name.

const Dv::Xml::Node::Refoperator * () const
 Dummy dereference operator, const version.

Dv::Xml::Node::Refoperator * ()
 Dummy dereference operator, non-const version.

bool defined (const std::string &name) const throw (Dv::Xml::Exception)
 Check whether this node has an attribute value for given key.

const std::string operator() (const std::string &name) const throw (Dv::Xml::Exception)
 Retrieve attribute value.

AttributeReference operator[] (const std::string &name) throw (Dv::Xml::Exception)
 Set attribute value.

 operator std::string () const throw (Dv::Xml::Exception)
 Retrieve text content.

template<typename T>  operator T () const
 Template user-defined conversion function.

std::string str (bool trim=true) const throw (Dv::Xml::Exception)
 Retrieve text content.

Refoperator= (const std::string &text) throw (Dv::Xml::Exception)
 Set text content.

template<typename T> const std::string operator= (const T &t)
 Set content of node referred to by this reference, after converting the parameter object to a std::string.

Refreplace (const Ref &ref)
 Replace this node by another one.


Protected Member Functions

 Ref (xml::node::iterator it, bool nil=false)
 Constructor.

 Ref (xml::node::const_iterator it, bool nil=false)
 Constructor.

void assert_valid (const std::string &message) const throw (Dv::Xml::Exception)
 Throw an exception if this Dv::Xml::Node::Ref object does not refer to a valid xml::node.


Private Attributes

xml::node::iterator it_
 Refers to xml::node, if valid.

bool nil_
 False iff it_ refers to a valid xml::node.


Friends

class Node
class Document
Dv::Xml::Node::Ref operator/ (const Dv::Xml::Node::Ref &ref, const std::string &name) throw (Dv::Xml::Exception)
 Retrieve child node with matching name.

bool operator== (const Dv::Xml::Node::Ref &n, const Dv::Xml::Node::Ref &m)
 Equality test.

bool operator!= (const Dv::Xml::Node::Ref m, const Dv::Xml::Node::Ref &n)
 Inequality test.

Dv::Xml::Node::Ref operator>> (const Dv::Xml::Node::Ref &ref, const std::string &name) throw (Dv::Xml::Exception)
 Append new child node with given name.

Dv::Xml::Node::Ref operator>> (const Dv::Xml::Node::Ref &ref, const Dv::Xml::Node::Ref &child) throw (Dv::Xml::Exception)
 Append copy of node to children of this node.


Detailed Description

A reference to an xml::node object.

Definition at line 184 of file node.h.


Constructor & Destructor Documentation

Dv::Xml::Node::Ref::Ref xml::node &  node  )  [explicit]
 

Construct a Dv::Xml::Node::Ref out of a (copy of a) xml::node object.

Parameters:
node xml::node which will be reference by the new Dv::Xml::Node::Ref object.

Dv::Xml::Node::Ref::Ref xml::node::iterator  it,
bool  nil = false
[explicit, protected]
 

Constructor.

Parameters:
it iterator, possibly referring to xml::node
nil true iff it does not refer to a valid xml::node.

Dv::Xml::Node::Ref::Ref xml::node::const_iterator  it,
bool  nil = false
[explicit, protected]
 

Constructor.

Parameters:
it const_iterator, possibly referring to xml::node
nil true iff it does not refer to a valid xml::node.


Member Function Documentation

std::string Dv::Xml::Node::Ref::name  )  const throw (Dv::Xml::Exception)
 

Returns:
name of underlying xml::node
Exceptions:
Dv::Xml::Exception if this Dv::Xml::Node::Ref does not refer to a valid xml::node.
See also:
Dv::Xml::Node::Ref::nil

Dv::Xml::Node::Ref& Dv::Xml::Node::Ref::name const std::string &  nm  )  throw (Dv::Xml::Exception)
 

Set name of underlying xml::node.

Parameters:
nm new name of node
Returns:
*this
Exceptions:
Dv::Xml::Exception if this Dv::Xml::Node::Ref does not refer to a valid xml::node.
See also:
Dv::Xml::Node::Ref::nil

bool Dv::Xml::Node::Ref::nil  )  const [inline]
 

Is this a "non-null" Dv::Xml::Node::Ref, i.e.

does it refer to a valid xml::node?

Returns:
true iff this Dv::Xml::Node::Ref does not refer to a valid xml::node.

Definition at line 214 of file node.h.

bool Dv::Xml::Node::Ref::operator!  )  const [inline]
 

Is this not a valid Dv::Xml::Node::Ref, i.e.

does it not refer to a valid xml::node?

Returns:
true iff this Dv::Xml::Node::Ref does not refer to a valid xml::node.
See also:
Dv::Xml::Node::Ref::nil

Definition at line 221 of file node.h.

Dv::Xml::Node::Ref::operator const xml::node *  )  const
 

Retrieve underlying xml::node for this Dv::Xml::Node::Ref.

This function can also be used to check whether this is a nil node.

 Dv::Xml::Node::Ref n(root/"child"/"grandchild");
 if (n) {
   ..
   }
Returns:
pointer to xml::node to which this Dv::Xml::Node::Ref refers, or 0 if it is a "nil" node.
See also:
Dv::Xml::Node::Ref::nil

Ref Dv::Xml::Node::Ref::end  )  const throw (Dv::Xml::Exception)
 

Return Ref that points past the last child of this node.

Returns:
nil Dv::Xml::Node::Ref.
Exceptions:
Dv::Xml::Exception if this Dv::Xml::Node::Ref does not refer to a valid xml::node.

Referenced by Dv::Xml::Node::end().

Ref Dv::Xml::Node::Ref::operator++  )  throw (Dv::Xml::Exception)
 

Return next child of parent with same name.

Returns:
Dv::Xml::Node::Ref referring to next sibling of this node that has the same name.
Exceptions:
Dv::Xml::Exception if this Dv::Xml::Node::Ref does not refer to a valid xml::node.

const Dv::Xml::Node::Ref& Dv::Xml::Node::Ref::operator *  )  const [inline]
 

Dummy dereference operator, const version.

This member function is needed to support forward iterator interface.

Returns:
reference to self.

Definition at line 268 of file node.h.

Dv::Xml::Node::Ref& Dv::Xml::Node::Ref::operator *  )  [inline]
 

Dummy dereference operator, non-const version.

This member function is needed to support forward iterator interface.

Returns:
reference to self.

Definition at line 274 of file node.h.

bool Dv::Xml::Node::Ref::defined const std::string &  name  )  const throw (Dv::Xml::Exception)
 

Check whether this node has an attribute value for given key.

Parameters:
name key of attribute
Returns:
true iff this node has an attribute value of this key.
Exceptions:
Dv::Xml::Exception if this Dv::Xml::Node::Ref does not refer to a valid xml::node.

const std::string Dv::Xml::Node::Ref::operator() const std::string &  name  )  const throw (Dv::Xml::Exception)
 

Retrieve attribute value.

Parameters:
name key of attribute
Returns:
value of attribute
Exceptions:
Dv::Xml::Exception if this node has no attribute for key "name" or this node does not refer to a valid xml::node.

AttributeReference Dv::Xml::Node::Ref::operator[] const std::string &  name  )  throw (Dv::Xml::Exception)
 

Set attribute value.

Parameters:
name key of attribute
Returns:
AttributeReference that can be used to either retrieve the current value of assign a new one. If there is no attribute value, the empty string will be returned (and stored).
Exceptions:
Dv::Xml::Exception if this Dv::Xml::Node::Ref does not refer to a valid xml::node.
See also:
Dv::Xml::Node::AttributeReference
 Dv::Xml::Node::Ref n;
 ..
 n["name"] = "fred";
 std::cout << n["name"] << std::endl;

Dv::Xml::Node::Ref::operator std::string  )  const throw (Dv::Xml::Exception)
 

Retrieve text content.

Note that the resulting string is trimmed, i.e. leading and trailing white space is removed. To prevent trimming: use Dv::Xml::Node::Ref::str(false).

Returns:
text content of text-xml::node children of this Dv::Xml::Node::Ref.
Exceptions:
Dv::Xml::Exception if this Dv::Xml::Node::Ref does not refer to a valid xml::node.
See also:
Dv::Xml::Node::Ref::str

template<typename T>
Dv::Xml::Node::Ref::operator T  )  const [inline]
 

Template user-defined conversion function.

Warning:
This will not work for std::string (and others), unless the "assignment" syntax is used for explicit initializtion, as illustrated by the following example.
 Dv::Xml::Node::Ref n;
 std::string s1(n["a"]); // error
 std::string s2 = n["a"]; // OK
The initialization of s1 is ambiguous: n["a"] may be converted to a (single) paramater for a std::string ctor using at least two instantiations of the user-defined conversion template below:
  • std::string(const char*)
  • std::string(const std::string&)

Definition at line 376 of file node.h.

References Dv::Util::fromstring().

std::string Dv::Xml::Node::Ref::str bool  trim = true  )  const throw (Dv::Xml::Exception)
 

Retrieve text content.

Returns:
text content of text-xml::node children of this Dv::Xml::Node::Ref.
Parameters:
trim if true, remove leading and trailing white space from result.
Exceptions:
Dv::Xml::Exception if this Dv::Xml::Node::Ref does not refer to a valid xml::node.

Ref& Dv::Xml::Node::Ref::operator= const std::string &  text  )  throw (Dv::Xml::Exception)
 

Set text content.

Parameters:
text to be used as content for this node.
Returns:
reference to this node. All children of this node will have been zapped and a new single child xml::node of type text will have been inserted.
Exceptions:
Dv::Xml::Exception if this Dv::Xml::Node::Ref does not refer to a valid xml::node.

template<typename T>
const std::string Dv::Xml::Node::Ref::operator= const T &  t  )  [inline]
 

Set content of node referred to by this reference, after converting the parameter object to a std::string.

The conversion is done using Dv::Util::tostring<T>.

Parameters:
t value to assign, after conversion, to attribute.
Returns:
string representation of t.

Definition at line 409 of file node.h.

Ref& Dv::Xml::Node::Ref::replace const Ref ref  ) 
 

Replace this node by another one.

The replacement will take place in the tree of which this Ref is a part.

Parameters:
ref reference to xml::node of which a copy will replace this node.
Returns:
reference to this Dv::Xml::Node::Ref.
Warning:
the xml::node to which ref refers will be copied.

void Dv::Xml::Node::Ref::assert_valid const std::string &  message  )  const throw (Dv::Xml::Exception) [protected]
 

Throw an exception if this Dv::Xml::Node::Ref object does not refer to a valid xml::node.

Parameters:
message to be used in the generated exception.


Friends And Related Function Documentation

friend class Node [friend]
 

Definition at line 185 of file node.h.

friend class Document [friend]
 

Definition at line 186 of file node.h.

Dv::Xml::Node::Ref operator/ const Dv::Xml::Node::Ref ref,
const std::string &  name
throw (Dv::Xml::Exception) [friend]
 

Retrieve child node with matching name.

Parameters:
ref reference to xml::node of which child is to be found
name to match in returned child node
Returns:
Dv::Xml::Node::Ref referring to first child of this node that has name or nil.
Exceptions:
Dv::Xml::Exception if this Dv::Xml::Node::Ref does not refer to a valid xml::node.
See also:
Dv::Xml::Node::Ref::nil

bool operator== const Dv::Xml::Node::Ref n,
const Dv::Xml::Node::Ref m
[friend]
 

Equality test.

Parameters:
n Dv::Xml::Node::Ref to compare with.
m Dv::Xml::Node::Ref to compare with.
Returns:
true iff both nodes are nil or they refer to the same xml::node.

bool operator!= const Dv::Xml::Node::Ref  m,
const Dv::Xml::Node::Ref n
[friend]
 

Inequality test.

Parameters:
m Dv::Xml::Node::Ref to compare with.
n Dv::Xml::Node::Ref to compare with.
Returns:
true iff the nodes are not equal
See also:
Dv::Xml::Node::Ref::operator==

Definition at line 289 of file node.h.

Dv::Xml::Node::Ref operator>> const Dv::Xml::Node::Ref ref,
const std::string &  name
throw (Dv::Xml::Exception) [friend]
 

Append new child node with given name.

Parameters:
ref to node to which a new child node will be appended.
name for new child node.
Returns:
Dv::Xml::Node::Ref referring to new child of this node that has name.
Exceptions:
Dv::Xml::Exception if ref does not refer to a valid xml::node.

Dv::Xml::Node::Ref operator>> const Dv::Xml::Node::Ref ref,
const Dv::Xml::Node::Ref child
throw (Dv::Xml::Exception) [friend]
 

Append copy of node to children of this node.

Parameters:
ref reference to xml::node to which a child will be added.
child a copy of which will be added to the children of this node.
Returns:
Dv::Xml::Node::Ref referring to the new child of this node.
Exceptions:
Dv::Xml::Exception if either of the parameters does not refer to a valid xml::node.


Member Data Documentation

xml::node::iterator Dv::Xml::Node::Ref::it_ [private]
 

Refers to xml::node, if valid.

Definition at line 440 of file node.h.

bool Dv::Xml::Node::Ref::nil_ [private]
 

False iff it_ refers to a valid xml::node.

Definition at line 442 of file node.h.


The documentation for this class was generated from the following file:
dvxml-0.1.4 [19 September, 2003]