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)
 
Returns:
name of underlying xml::node
Exceptions:
Dv::Xml::Exception if this Dv::Xml::Node::Ref does not refer to a valid xml::node.

Node::Refname (const std::string &nm) throw (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.
bool equals (const Node::Ref &m) const
 Equality test.
 operator const xml::node * () const
 Retrieve underlying xml::node for this Dv::Xml::Node::Ref.
 operator xml::node * ()
Node::Ref find (const std::string &name) const throw (Exception)
 Retrieve child node (of this node) with matching name.
Ref end () const throw (Exception)
 Return Ref that points past the last child of this node.
Ref operator++ () throw (Exception)
 Return next child of parent with same name.
const Node::Refoperator * () const
 Dummy dereference operator, const version.
Node::Refoperator * ()
 Dummy dereference operator, non-const version.
Node::Ref add (const std::string &name, const std::string &contents) throw (Dv::Xml::Exception)
 Append a new text node to the list of children of this node.
Node::Ref add (const char *name) throw (Exception)
 Append a new node to the list of children of this node.
Node::Ref add (const std::string &name) throw (Exception)
 Append a new node to the list of children of this node.
Node::Ref add (const Node::Ref &child) throw (Exception)
 Append copy of node to children of this node.
bool defined (const std::string &name) const throw (Exception)
 Check whether this node has an attribute value for given key.
const std::string operator() (const std::string &name) const throw (Exception)
 Retrieve attribute value.
AttributeReference operator[] (const std::string &name) throw (Exception)
 Set attribute value.
 operator std::string () const throw (Exception)
 Retrieve text content.
template<typename T>
 operator T () const
 Template user-defined conversion function.
std::string str (bool trim=true) const throw (Exception)
 Retrieve text content.
Refoperator= (const std::string &text) throw (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

Detailed Description

A reference to an xml::node object.

Definition at line 181 of file node.h.


Constructor & Destructor Documentation

Dv::Xml::Node::Ref::Ref ( xml::node &  node  ) 

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

Referenced by add().

Node::Ref& Dv::Xml::Node::Ref::name ( const std::string &  nm  )  throw (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 211 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 218 of file node.h.

bool Dv::Xml::Node::Ref::equals ( const Node::Ref m  )  const

Equality test.

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

Referenced by Dv::Xml::operator!=(), and Dv::Xml::operator==().

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

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

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

Retrieve child node (of this node) with matching name.

Parameters:
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

Referenced by Dv::Xml::operator/().

Ref Dv::Xml::Node::Ref::end (  )  const throw (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 (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 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 270 of file node.h.

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 276 of file node.h.

Node::Ref Dv::Xml::Node::Ref::add ( const std::string &  name,
const std::string &  contents 
) throw (Dv::Xml::Exception)

Append a new text node to the list of children of this node.

Parameters:
name of the new node
contents of the new node
Returns:
Dv::Xml::Node::Ref referring to the new child of this node.
Exceptions:
Dv::Xml::Exception if the target does not refer to a valid xml::node.

Referenced by Dv::Xml::operator>>().

Node::Ref Dv::Xml::Node::Ref::add ( const char *  name  )  throw (Exception)

Append a new node to the list of children of this node.

Parameters:
name of the new node
Returns:
Dv::Xml::Node::Ref referring to the new child of this node.
Exceptions:
Dv::Xml::Exception if the target does not refer to a valid xml::node.

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

Append a new node to the list of children of this node.

Parameters:
name of the new node
Returns:
Dv::Xml::Node::Ref referring to the new child of this node.
Exceptions:
Dv::Xml::Exception if the target does not refer to a valid xml::node.

Definition at line 302 of file node.h.

References name().

Node::Ref Dv::Xml::Node::Ref::add ( const Node::Ref child  )  throw (Exception)

Append copy of node to children of this node.

Parameters:
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.

bool Dv::Xml::Node::Ref::defined ( const std::string &  name  )  const throw (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 (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 (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 (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-xmlnode 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 (Exception)

Retrieve text content.

Returns:
text content of text-xmlnode 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 (Exception)

Set text content.

Parameters:
text to be used as content for this node.
Warning:
Note that the text parameter must be legal XML (see test-node-5 in the distrbution).
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.
See also:
Dv::Xml::to_html

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 411 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 182 of file node.h.

friend class Document [friend]

Definition at line 183 of file node.h.


Member Data Documentation

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

Refers to xml::node, if valid.

Definition at line 442 of file node.h.

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

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

Definition at line 444 of file node.h.


The documentation for this class was generated from the following file:
dvxml-0.1.7 [ 7 January, 2008]