...one of the most highly
regarded and expertly designed C++ library projects in the
world.

— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards

// named parameter versiontemplate <class Graph, class P, class T, class R> void breadth_first_search(Graph& G, typename graph_traits<Graph>::vertex_descriptor s, const bgl_named_params<P, T, R>& params);// non-named parameter versiontemplate <class Graph, class Buffer, class BFSVisitor, class ColorMap> void breadth_first_search(const Graph& g, typename graph_traits<Graph>::vertex_descriptor s, Buffer& Q, BFSVisitor vis, ColorMap color);

The `breadth_first_search()` function performs a breadth-first
traversal [49] of a directed
or undirected graph. A breadth-first traversal visits vertices that
are closer to the source before visiting vertices that are further
away. In this context ``distance'' is defined as the number of edges
in the shortest path from the source vertex. The
`breadth_first_search()` function can be used to compute the
shortest path from the source to all reachable vertices and the
resulting shortest-path distances. For more definitions related to BFS
see section
Breadth-First Search.

BFS uses two data structures to to implement the traversal: a color
marker for each vertex and a queue. White vertices are undiscovered
while gray vertices are discovered but have undiscovered adjacent
vertices. Black vertices are discovered and are adjacent to only other
black or gray vertices. The algorithm proceeds by removing a vertex
u from the queue and examining each out-edge *(u,v)*. If an
adjacent vertex *v* is not already discovered, it is colored gray and
placed in the queue. After all of the out-edges are examined, vertex
*u* is colored black and the process is repeated. Pseudo-code for the
BFS algorithm is a listed below.

BFS( |
initialize vertex |

`boost/graph/breadth_first_search.hpp`

A directed or undirected graph. The graph type must be a model of Vertex List Graph and Incidence Graph.IN:

Python: The parameter is namedgraph.

The source vertex where the search is started.

Python: The parameter is namedroot_vertex.

A visitor object that is invoked inside the algorithm at the event-points specified by the BFS Visitor concept. The visitor object is passed by value [1].UTIL/OUT:

Default:bfs_visitor<null_visitor>

Python: The parameter should be an object that derives from theBFSVisitortype of the graph.

This is used by the algorithm to keep track of its progress through the graph. The user need not initialize the color map before callingIN:breadth_first_search()since the algorithm initializes the color of every vertex to white at the start of the algorihtm. If you need to perform multiple breadth-first searches on a graph (for example, if there are some disconnected components) then use thebreadth_first_visit()function and do your own color initialization.The type

ColorMapmust be a model of Read/Write Property Map and its key type must be the graph's vertex descriptor type and the value type of the color map must model ColorValue.

Default:an iterator_property_map created from astd::vectorofdefault_color_typeof sizenum_vertices(g)and using thei_mapfor the index map.

Python: The color map must be avertex_color_mapfor the graph.

This maps each vertex to an integer in the rangeUTIL:[0, num_vertices(g)). This parameter is only necessary when the default color property map is used. The typeVertexIndexMapmust be a model of Readable Property Map. The value type of the map must be an integer type. The vertex descriptor type of the graph needs to be usable as the key type of the map.

Default:get(vertex_index, g). Note: if you use this default, make sure your graph has an internalvertex_indexproperty. For example,adjacenty_listwithVertexList=listSdoes not have an internalvertex_indexproperty.

Python: Unsupported parameter.

The queue used to determine the order in which vertices will be discovered. If a FIFO queue is used, then the traversal will be according to the usual BFS ordering. Other types of queues can be used, but the traversal order will be different. For example Dijkstra's algorithm can be implemented using a priority queue. The typeBuffermust be a model of Buffer.

Thevalue_typeof the buffer must be thevertex_descriptortype for the graph.

Default:boost::queue

Python: The buffer must derive from the Buffer type for the graph.

The time complexity is *O(E + V)*.

is invoked on every vertex before the start of the search.`vis.initialize_vertex(v, g)`r is invoked in each vertex as it is removed from the queue.`vis.examine_vertex(u, g)`is invoked on every out-edge of each vertex immediately after the vertex is removed from the queue.`vis.examine_edge(e, g)`is invoked (in addition to`vis.tree_edge(e, g)``examine_edge()`) if the edge is a tree edge. The target vertex of edge`e`is discovered at this time.is invoked the first time the algorithm encounters vertex`vis.discover_vertex(u, g)`*u*. All vertices closer to the source vertex have been discovered, and vertices further from the source have not yet been discovered.is invoked (in addition to`vis.non_tree_edge(e, g)``examine_edge()`) if the edge is not a tree edge.is invoked (in addition to`vis.gray_target(e, g)``non_tree_edge()`) if the target vertex is colored gray at the time of examination. The color gray indicates that the vertex is currently in the queue.is invoked (in addition to`vis.black_target(e, g)``non_tree_edge()`) if the target vertex is colored black at the time of examination. The color black indicates that the vertex is no longer in the queue.is invoked after all of the out edges of`vis.finish_vertex(u, g)`*u*have been examined and all of the adjacent vertices have been discovered.

The example in `example/bfs-example.cpp`
demonstrates using the BGL Breadth-first search algorithm on the graph
from Figure
5. The file
`example/bfs-example2.cpp`
contains the same example, except that the `adacency_list`
class used has `VertexList` and `EdgeList` set
to `listS`.

[1]
Since the visitor parameter is passed by value, if your visitor
contains state then any changes to the state during the algorithm
will be made to a copy of the visitor object, not the visitor object
passed in. Therefore you may want the visitor to hold this state by
pointer or reference.

Copyright © 2000-2001 | Jeremy Siek, Indiana University (jsiek@osl.iu.edu) |