openvrml::node_traverser Class Reference

Traverse the children of each node in a node hierarchy only once. More...

#include <openvrml/node.h>

List of all members.


Public Member Functions

 node_traverser () throw ( std::bad_alloc )
 Construct.
virtual ~node_traverser ()=0 throw ()
 Destroy.
void traverse (node &n)
 Traverse a node.
void traverse (const boost::intrusive_ptr< node > &node)
 Traverse a node.
void traverse (const std::vector< boost::intrusive_ptr< node > > &nodes)
 Traverse a std::vector of nodes.

Protected Member Functions

void halt_traversal () throw ()
 Halt the traversal.
bool halted () const throw ()
 Indicate whether the traversal has been halted.
bool traversed (node &n) const throw ()
 Check whether a node has been traversed.

Private Member Functions

virtual void on_entering (node &n)
 Called for each node in the traversal before traversing the its descendants.
virtual void on_leaving (node &n)
 Called for each node in the traversal after traversing the its descendants.
void do_traversal (node &n)
 Traverse a node.

Private Attributes

std::set< node * > traversed_nodes
 The set of nodes that have already been traversed.
bool halt
 Flag to indicate if the traversal should be halted.

Detailed Description

Traverse the children of each node in a node hierarchy only once.

The node_traverser provides a generalized traversal mechanism that avoids redundantly traversing branches of the node hierarchy. If a node occurs multiple places in a branch, the children of that node will be visited in the traversal only once.

For each node encountered in the traversal, node_traverser does the following:

  1. Call on_entering.
  2. Traverse descendants, if any.
  3. Call on_leaving.

Concrete subclasses of node_traverser implement the on_entering and/or on_leaving member functions in order to perform some operation(s) on each node. The traversal can be ended prematurely by calling halt_traversal.


Constructor & Destructor Documentation

openvrml::node_traverser::node_traverser (  )  throw ( std::bad_alloc )

Construct.

Exceptions:
std::bad_alloc if memory allocation fails.

openvrml::node_traverser::~node_traverser (  )  throw () [pure virtual]

Destroy.


Member Function Documentation

void openvrml::node_traverser::traverse ( node n  ) 

Traverse a node.

No guarantee is made about the state of the node_traverser instance in the event that this method throws.

In addition to std::bad_alloc, this function throws any exception thrown from on_entering or on_leaving.

Parameters:
[in,out] n the root node of the branch to traverse.
Exceptions:
std::bad_alloc if memory allocation fails.

void openvrml::node_traverser::traverse ( const boost::intrusive_ptr< node > &  node  ) 

Traverse a node.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
[in,out] node the root node of the branch to traverse.
Exceptions:
std::bad_alloc if memory allocation fails.

void openvrml::node_traverser::traverse ( const std::vector< boost::intrusive_ptr< node > > &  nodes  ) 

Traverse a std::vector of nodes.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
[in,out] nodes the root nodes of the branch to traverse.

void openvrml::node_traverser::halt_traversal (  )  throw () [protected]

Halt the traversal.

If this method is called during a traversal, no more descendant nodes will be traversed. Note that if halt_traversal is called in the implementation of on_entering, on_leaving will still be called for the current node and any parent nodes (that is, any node for which on_entering has been called). Implementations of on_leaving can call halted to check whether the traversal has been halted.

bool openvrml::node_traverser::halted (  )  const throw () [protected]

Indicate whether the traversal has been halted.

This function is useful in implementations of on_leaving that need to check whether the traversal has been halted.

Returns:
true if the traversal has been halted; false otherwise.

bool openvrml::node_traverser::traversed ( node n  )  const throw () [protected]

Check whether a node has been traversed.

Parameters:
[in] n the node to check.
Returns:
true if n has been traversed; false otherwise.

void openvrml::node_traverser::on_entering ( node n  )  [private, virtual]

Called for each node in the traversal before traversing the its descendants.

Parameters:
[in,out] n the node currently being traversed.

void openvrml::node_traverser::on_leaving ( node n  )  [private, virtual]

Called for each node in the traversal after traversing the its descendants.

Parameters:
[in,out] n the node currently being traversed.

void openvrml::node_traverser::do_traversal ( node n  )  [private]

Traverse a node.

For internal use only.

Parameters:
[in,out] n the node to traverse.
Exceptions:
std::bad_alloc if memory allocation fails.


Member Data Documentation

The set of nodes that have already been traversed.

For internal use only.

Flag to indicate if the traversal should be halted.

For internal use only.