openvrml::node_traverser Class Referenceabstract

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

#include <openvrml/node.h>

Inherits noncopyable.

Public Member Functions

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

Protected Member Functions

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

Private Member Functions

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

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.