openvrml::node_traverser Class Reference

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

#include <openvrml/node.h>

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.

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_allocif 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]nthe root node of the branch to traverse.
Exceptions
std::bad_allocif 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]nodethe root node of the branch to traverse.
Exceptions
std::bad_allocif 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]nodesthe 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]nthe node to check.
Returns
true if n has been traversed; false otherwise.
void openvrml::node_traverser::on_entering ( node n)
privatevirtual

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

Parameters
[in,out]nthe node currently being traversed.
void openvrml::node_traverser::on_leaving ( node n)
privatevirtual

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

Parameters
[in,out]nthe node currently being traversed.