bfs Class Reference

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

Inheritance diagram for bfs:

Inheritance graph
[legend]
Collaboration diagram for bfs:

Collaboration graph
[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< nodequ
 queue used in BFS.
list< nodebfs_order
 List of nodes in BFS-order.
list< edgetree
 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_iteratorroots
 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:

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):

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!):


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