Home | Documentation | Download | Platforms | Projects | Mailing Lists | Version History

- Main Page
- Classes
- Files
- Related Pages

- Alphabetical List
- Class List
- Class Hierarchy
- Class Members

# bfs Class Reference

Breadth-First-Search (BFS) algorithm. More...

Inheritance diagram for bfs:

[legend]
Collaboration diagram for bfs:

[legend]

List of all members.

## Public Types

typedef list< edge > ::const_iterator | tree_edges_iterator
| Iterator for tree-edges.
typedef list< node > ::const_iterator | bfs_iterator
| Iterator for nodes in BFS-order.
typedef list< edge > ::const_iterator | non_tree_edges_iterator
| Iterator for non-tree-edges.
typedef list < bfs_iterator > ::const_iterator | roots_iterator
| Iterator for roots of trees in BFS-forest.

## Public Member Functions

| bfs ()
| Constructor.
virtual | ~bfs ()
| Destructor.
int | run (graph &G)
| Applies algorithm to graph g.
virtual int | check (graph &G)
| Checks whether the preconditions for BFS are satisfied.
virtual void | reset ()
| Resets algorithm.
void | start_node (const node &n)
| Sets start-node for BFS.
node | start_node () const
| Returns start-node for BFS.
void | scan_whole_graph (bool set)
| Enables or disables scanning of the whole graph.
bool | scan_whole_graph () const
| Returns whether the whole graph will be scanned.
void | calc_level (bool set)
| Enables or disables the calculation of level-numbers for each node.
bool | calc_level () const
| Returns whether level-numbers will be calculated.
void | store_non_tree_edges (bool set)
| Enables or disables the storing of non-tree-edges.
bool | store_non_tree_edges () const
| Returns whether the storing of non-tree-edges is enabled.
void | store_preds (bool set)
| Enables or disables the storing of predecessors.
bool | store_preds () const
| Returns whether the storing of predecessors is enabled.
bool | reached (const node &n) const
| Checks whether node n was reached in BFS.
int | bfs_num (const node &n) const
| BFS-number of n.
int | operator[] (const node &n) const
| BFS-number of n.
int | level (const node &n) const
| Level-number of node n.
node | father (const node &n) const
| Father of node n in BFS-forest.
tree_edges_iterator | tree_edges_begin () const
| Iterate through all tree-edges of last BFS.
tree_edges_iterator | tree_edges_end () const
| End-iterator for iteration through all tree-edges picked of last BFS.
bfs_iterator | begin () const
| Iterate through all (reached) nodes in BFS-Order.
bfs_iterator | end () const
| End-iterator for iteration through all (reached) nodes in BFS-Order.
non_tree_edges_iterator | non_tree_edges_begin () const
| Iterate through all non-tree-edges (if enabled).
non_tree_edges_iterator | non_tree_edges_end () const
| End-iterator for iteration through all non-tree-edges (if enabled).
roots_iterator | roots_begin () const
| Iterator pointing towards the first root in the BFS-forest.
roots_iterator | roots_end () const
| Iterator pointing to the end of all roots.
int | number_of_reached_nodes () const
| Number of nodes reached in last BFS.
virtual void | init_handler (graph &G)
| Called at the start of BFS.
virtual void | end_handler (graph &G)
| Called right before the end of BFS.
virtual void | popped_node_handler (graph &G, node &n)
| Called after the node n was taken out of the queue.
virtual void | finished_node_handler (graph &G, node &n)
| Called when finished with the node n.
virtual void | unused_node_handler (graph &G, node &n, node &f)
| Called when an unused node n was discovered.
virtual void | used_node_handler (graph &G, node &n, node &f)
| Called when an used node n was found.
virtual void | new_start_handler (graph &G, node &n)
| Called when BFS is started with start-node n.

## Protected Attributes

int | act_bfs_num
| BFS number that will be assigned next.
deque< node > | qu
| queue used in BFS.
list< node > | bfs_order
| List of nodes in BFS-order.
list< edge > | tree
| List of all edges of the BFS-tree.
node_map< int > | bfs_number
| Stores BFS-number of nodes.
int | reached_nodes
| Number of nodes reached so far.
list< bfs_iterator > | roots
| List of all roots of the BFS-tree.
bool | whole_graph
| Stores whether whole graph will be scanned.
node | start
| Stores start node.
node_map< int > * | level_number
| Stores level number of each node (if enabled).
list< edge > * | non_tree
| List of non-tree edges (if enabled).
node_map< node > * | preds
| Stores father of each node (if enabled).

## Detailed Description

Breadth-First-Search (BFS) algorithm.

Date

Revision

Encapsulates the BFS algorithm together with all data produced by it. There are a few parameters, which on the one hand influence the behaviour of BFS (e.g. bfs::start_node) and on the other hand toggle the storing of extra information, such as the level-number of each node. In detail these are:

- bfs::start_node (default: an arbitrary node will be chosen)
- bfs::scan_whole_graph states whether BFS will be continued in the unused part of the graph, if not all nodes were touched at the end of BFS started at the start-node. (default: disabled)
- bfs::calc_level toggle storing of level-numbers for each node, i.e. its distance from the start-node. (default: disabled)
- bfs::store_preds toggle storing the predecessor of each node, i.e. the father in the BFS-tree. (default: disabled)
- bfs::store_non_tree_edges toggle storing of all non_tree_edges (tree_edges are always stored) in a list and thus enable or disable iteration through all non_tree_edges. (default: disabled)

Please note that the algorithm always starts with the given start-node (if none was given, the first node is chosen and stored, thus after BFS the root of the tree is always accesible via bfs::start_node) and continues until no more unused nodes are reachable from already used ones. Thus if the graph isn't connected not all nodes will be reached. If bfs::scan_whole_graph isn't set the BFS stops here. If it is set, the BFS will be continued with the next unused node and so on until all nodes were used.

For further customization a few virtual functions, so called handler, are called at crucial stages of the algorithm. In this basic implementation all of these handler are empty. So if one wants to add only a few lines of code (e.g. some new numbering) he is likely to take this class as base-class and override the handler where neccessary. In detail these are (please look at the source code to see where they are called):

- bfs::init_handler
- bfs::end_handler
- bfs::popped_node_handler
- bfs::finished_node_handler
- bfs::unused_node_handler
- bfs::used_node_handler
- bfs::new_start_handler

Please note: We do not claim that the set of handlers provided is sufficient in any way. So if you believe that some new handler is needed urgently please let us know.

There is a lot of information stored during BFS (e.g. nodes in bfs-order, list of non-tree edges). Some of it can be obtained directly by using the corresponding member-function (e.g. bfs::bfs_num), but all information that can be thought of as a list (e.g. nodes in bfs-order) can be accessed through iterators. In detail these are (of course depending on what options are chosen!):

- bfs::bfs_iterator
- bfs::tree_edges_iterator
- bfs::non_tree_edges_iterator
- bfs::roots_iterator

## Member Function Documentation

int bfs::run | ( | graph & | g | ) | `[virtual]`

Applies algorithm to graph g.

Parameters:

  | g | graph

Return values:

  | algorithm::GTL_OK | on success
  | algorithm::GTL_ERROR | otherwise

Implements algorithm.

virtual int bfs::check | ( | graph & | G | ) | `[inline, virtual]`

Checks whether the preconditions for BFS are satisfied.

Currently there aren't any restricitions for the BFS algorithm.

Parameters:

  | G | graph.

Return values:

  | algorithm::GTL_OK | if algorithm can be applied
  | algorithm::GTL_ERROR | otherwise.

Implements algorithm.

virtual void bfs::reset | ( |  | ) | `[virtual]`

Resets algorithm.

Prepares the algorithm to be applied to another graph. Please note: The options an algorithm may support do not get reset by this. It is just to reset internally used datastructures.

Implements algorithm.

void bfs::start_node | ( | const node & | n | ) | `[inline]`

Sets start-node for BFS.

The default start-node is the invalid node (node::node()), in this case an arbitrary node is chosen and stored when BFS is run.

Parameters:

  | n | start-node.

node bfs::start_node | ( |  | ) | const`[inline]`

Returns start-node for BFS.

Returns:
  start-node.

void bfs::scan_whole_graph | ( | bool | set | ) | `[inline]`

Enables or disables scanning of the whole graph.

If enabled and the BFS started at the given start-node stops without having touched all nodes, it will be continued with the next unused node, and so on until all nodes were used. This makes sure that for every node bfs::bfs_num is defined.

If this feature is disabled, you are able to check what nodes can be reached, when starting a BFS at the start-node, because for those not reached bfs::bfs_num will be 0.

Parameters:

  | set | if true enable scanning the whole graph.

See also:
  bfs::roots_begin, bfs::roots_end

bool bfs::scan_whole_graph | ( |  | ) | const`[inline]`

Returns whether the whole graph will be scanned.

Return values:

  | true | iff the whole graph will be scanned.

See also:
  bfs::roots_begin, bfs::roots_end

void bfs::calc_level | ( | bool | set | ) |

Enables or disables the calculation of level-numbers for each node.

If enabled each node gets a level-number, i.e. its distance from the start-node.

Parameters:

  | set | if true level-number will be calculated.

See also:
  bfs::level

bool bfs::calc_level | ( |  | ) | const`[inline]`

Returns whether level-numbers will be calculated.

Return values:

  | true | iff level-numbers will be calculated.

See also:
  bfs::level

void bfs::store_non_tree_edges | ( | bool | set | ) |

Enables or disables the storing of non-tree-edges.

If enabled all non-tree-edges will be stored in the order they occured.

Parameters:

  | set | if true non-tree-edges will be stored.

See also:
  bfs::non_tree_edges_begin, bfs::non_tree_edges_end

bool bfs::store_non_tree_edges | ( |  | ) | const`[inline]`

Returns whether the storing of non-tree-edges is enabled.

Return values:

  | true | iff the storing of non-tree-edges is enabled.

See also:
  bfs::non_tree_edges_begin, bfs::non_tree_edges_end

void bfs::store_preds | ( | bool | set | ) |

Enables or disables the storing of predecessors.

If enabled for every node the predecessor in the BFS-forest will be stored.

Parameters:

  | set | if true predecessors will be stored.

See also:
  bfs::father

bool bfs::store_preds | ( |  | ) | const`[inline]`

Returns whether the storing of predecessors is enabled.

Return values:

  | true | iff the storing of predecessors is enabled.

See also:
  bfs::father

bool bfs::reached | ( | const node & | n | ) | const`[inline]`

Checks whether node n was reached in BFS.

Parameters:

  | n | node.

Return values:

  | true | iff n was reached.

int bfs::bfs_num | ( | const node & | n | ) | const`[inline]`

BFS-number of n.

Please note that BFS-number 0 means that this node wasn't reached.

Parameters:

  | n | node.

Returns:
  BFS-number of n.

int bfs::operator[] | ( | const node & | n | ) | const`[inline]`

BFS-number of n.

Please note that BFS-number 0 means that this node wasn't reached.

Parameters:

  | n | node.

Returns:
  BFS-number of n.

int bfs::level | ( | const node & | n | ) | const`[inline]`

Level-number of node n.

Please note that this requires that this option was enabled during last run.

Parameters:

  | n | node.

Returns:
  level-number of n.

See also:
  bfs::calc_level

node bfs::father | ( | const node & | n | ) | const`[inline]`

Father of node n in BFS-forest.

If n is a root in the forest or wasn't reached the return value is the invalid node node::node().

Please note that this requires that this option was enabled during last run.

Parameters:

  | n | node.

Returns:
  Father of n.

See also:
  bfs::store_preds

tree_edges_iterator bfs::tree_edges_begin | ( |  | ) | const`[inline]`

Iterate through all tree-edges of last BFS.

Please note that this edges not always form a tree. In case the graph is not (strongly) connected and the whole graph was scanned, they form a forest.

Returns:
  Start for iteration through all tree-edges.

tree_edges_iterator bfs::tree_edges_end | ( |  | ) | const`[inline]`

End-iterator for iteration through all tree-edges picked of last BFS.

Returns:
  End for iteration through all tree-edges.

bfs_iterator bfs::begin | ( |  | ) | const`[inline]`

Iterate through all (reached) nodes in BFS-Order.

Returns:
  Start for iteration through all nodes in BFS-order.

bfs_iterator bfs::end | ( |  | ) | const`[inline]`

End-iterator for iteration through all (reached) nodes in BFS-Order.

Returns:
  End for iteration through all (reached) nodes

non_tree_edges_iterator bfs::non_tree_edges_begin | ( |  | ) | const`[inline]`

Iterate through all non-tree-edges (if enabled).

Returns:
  Start for iteration through all non-tree-edges.

See also:
  bfs::store_non_tree_edges

non_tree_edges_iterator bfs::non_tree_edges_end | ( |  | ) | const`[inline]`

End-iterator for iteration through all non-tree-edges (if enabled).

Returns:
  End for iteration through all non-tree-edges.

See also:
  bfs::store_non_tree_edges

roots_iterator bfs::roots_begin | ( |  | ) | const`[inline]`

Iterator pointing towards the first root in the BFS-forest.

Please note that instead of pointing directly towards the node (i.e. `*it` is of type `node`) the iterator points towards a bfs-iterator, which represents the root (i.e. `*it` is of type `bfs_iterator`).

Using this technique makes it possible not only to obtain all the roots in the forest, but also the whole trees associated with each one. This can be achieved because a `root_iterator` specifies the exact position of the root in the BFS-ordering and by definition of BFS all the descendents of the root, i.e. the whole tree below, will come later in BFS, such that by incrementing the `bfs_iterator` a `roots_iterator` refers to, one can traverse the whole tree with this given root.

Of course if the root isn't the last node in the BFS-forest all following trees also will be traversed. But since the first node of such a tree, that will be discovered, is its root, the successor of the `roots_iterator` can be used as end-iterator.

Returns:
  Start for iteration through all roots in BFS-forest.

See also:
  bfs::scan_whole_graph

roots_iterator bfs::roots_end | ( |  | ) | const`[inline]`

Iterator pointing to the end of all roots.

Returns:
  End for iteration through all roots in BFS-forest.

See also:
  bfs::scan_whole_graph

int bfs::number_of_reached_nodes | ( |  | ) | const`[inline]`

Number of nodes reached in last BFS.

Returns:
  Number of reached nodes.

See also:
  bfs::scan_whole_graph

virtual void bfs::init_handler | ( | graph & | G | ) | `[inline, virtual]`

Called at the start of BFS.

Parameters:

  | G | graph for which BFS was invoked.

virtual void bfs::end_handler | ( | graph & | G | ) | `[inline, virtual]`

Called right before the end of BFS.

Parameters:

  | G | graph for which BFS was invoked.

virtual void bfs::popped_node_handler | ( | graph & | G,
|  | node & | n |
| ) |  |  | `[inline, virtual]`

Called after the node n was taken out of the queue.

Parameters:

  | G | graph for which BFS was invoked.
  | n | node taken out of the queue.

virtual void bfs::finished_node_handler | ( | graph & | G,
|  | node & | n |
| ) |  |  | `[inline, virtual]`

Called when finished with the node n.

A node is finished after all its neighbors have been visited.

Parameters:

  | G | graph for which BFS was invoked.
  | n | finished node.

virtual void bfs::unused_node_handler | ( | graph & | G,
|  | node & | n,
|  | node & | f |
| ) |  |  | `[inline, virtual]`

Called when an unused node n was discovered.

This means that the actual node's f neighbor n was not previously discovered.

Parameters:

  | G | graph for which BFS was invoked.
  | n | unused node.
  | f | actual node.

virtual void bfs::used_node_handler | ( | graph & | G,
|  | node & | n,
|  | node & | f |
| ) |  |  | `[inline, virtual]`

Called when an used node n was found.

This means that the actual node's (f) neighbor n has already been discovered.

Parameters:

  | G | graph for which BFS was invoked.
  | n | used node.
  | f | actual node.

virtual void bfs::new_start_handler | ( | graph & | G,
|  | node & | n |
| ) |  |  | `[inline, virtual]`

Called when BFS is started with start-node n.

This is particularly useful when BFS was invoked with the `scan_whole_graph` option.

Parameters:

  | G | graph for which BFS was invoked.
  | n | start-node.

See also:
  bfs::scan_whole_graph

## Member Data Documentation

list<node> bfs::bfs_order `[protected]`

List of nodes in BFS-order.

See also:
  bfs::begin, bfs::end

list<edge> bfs::tree `[protected]`

List of all edges of the BFS-tree.

See also:
  bfs::tree_edges_begin, bfs::tree_edges_end

list<bfs_iterator> bfs::roots `[protected]`

List of all roots of the BFS-tree.

See also:
  bfs::roots_begin, bfs::roots_end

bool bfs::whole_graph `[protected]`

Stores whether whole graph will be scanned.

See also:
  bfs::scan_whole_graph

node bfs::start `[protected]`

Stores start node.

See also:
  bfs:start_node

node_map<int>* bfs::level_number `[protected]`

Stores level number of each node (if enabled).

See also:
  bfs::calc_level

list<edge>* bfs::non_tree `[protected]`

List of non-tree edges (if enabled).

See also:
  bfs::store_non_tree_edges

node_map<node>* bfs::preds `[protected]`

Stores father of each node (if enabled).

See also:
  bfs::store_preds

University of Passau - FMI - Theoretical Computer Science

Design © 2002, 2003 Marcus Raitner, University of Passau