Home | Download | Screen shots | Discussion | Documentation
--- | --- | --- | --- | ---

# 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

std::set< openvrml::node * > openvrml::node_traverser::traversed_nodes`[private]`

The set of `nodes` that have already been traversed.

For internal use only.

bool openvrml::node_traverser::halt`[private]`

Flag to indicate if the traversal should be halted.

For internal use only.