# `breadth_first_search`

      template <class VertexListGraph, class P, class T, class R>
      void breadth_first_search(VertexListGraph& G,
        typename graph_traits<VertexListGraph>::vertex_descriptor s,
        const bgl_named_params<P, T, R>& params);

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(G, s)
      for each vertex u in V[G]
        color[u] := WHITE
        d[u] := infinity
        p[u] := u
      end for
      color[s] := GRAY
      d[s] := 0
      ENQUEUE(Q, s)
      while (Q != Ø)
        u := DEQUEUE(Q)
        for each vertex v in Adj[u]
          if (color[v] = WHITE)
            color[v] := GRAY
            d[v] := d[u] + 1
            p[v] := u
            ENQUEUE(Q, v)
          else
            if (color[v] = GRAY)
              ...
            else
              ...
        end for
        color[u] := BLACK
      end while
      return (d, p)
    initialize vertex u

    discover vertex s

    examine vertex u
    examine edge (u,v)
    (u,v) is a tree edge

    discover vertex v
    (u,v) is a non-tree edge

    (u,v) has a gray target

    (u,v) has a black target

    finish vertex u

The `breadth_first_search()` function can be extended with user-defined actions that will be called a certain event points. The actions must be provided in the form of a visitor object, that is, an object who's type meets the requirements for a BFS Visitor. In the above pseudo-code, the event points are the labels on the right. Also a description of each event point is given below. By default, the `breadth_first_search()` function does not carry out any actions, not even recording distances or predecessors. However these can be easily added using the `distance_recorder` and `predecessor_recorder` event visitors.

### Where Defined

`boost/graph/breadth_first_search.hpp`

### Parameters

IN: `VertexListGraph& g`

> A directed or undirected graph. The graph type must be a model of Vertex List Graph.

IN: `vertex_descriptor s`

> The source vertex where the search is started.

### Named Parameters

IN: `visitor(BFSVisitor vis)`

> A visitor object that is invoked inside the algorithm at the event-points specified by the BFS Visitor concept.
> Default: `bfs_visitor<null_visitor>`

UTIL/OUT: `color_map(ColorMap color)`

> This is used by the algorithm to keep track of its progress through the graph. The type `ColorMap` must 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 a `std::vector` of `default_color_type` of size `num_vertices(g)` and using the `i_map` for the index map.

IN: `vertex_index_map(VertexIndexMap i_map)`

> This maps each vertex to an integer in the range `[0, num_vertices(g))`. This parameter is only necessary when the default color property map is used. The type `VertexIndexMap` must 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)`

UTIL: `buffer(Buffer& Q)`

> 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 type `Buffer` must be a model of Buffer.
> Default: `boost::queue`

### Complexity

The time complexity is O(E + V).

### Visitor Event Points

- `vis.initialize_vertex(v, g)` is invoked on every vertex before the start of the search.
- `vis.examine_vertex(u, g)`r is invoked in each vertex as it is removed from the queue.
- `vis.examine_edge(e, g)` is invoked on every out-edge of each vertex immediately after the vertex is removed from the queue.
- `vis.tree_edge(e, g)` is invoked (in addition to `examine_edge()`) if the edge is a tree edge. The target vertex of edge `e` is discovered at this time.
- `vis.discover_vertex(u, g)` is invoked the first time the algorithm encounters vertex u. All vertices closer to the source vertex have been discovered, and vertices further from the source have not yet been discovered.
- `vis.non_tree_edge(e, g)` is invoked (in addition to `examine_edge()`) if the edge is not a tree edge.
- `vis.gray_target(e, g)` is invoked (in addition to `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.
- `vis.black_target(e, g)` is invoked (in addition to `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.
- `vis.finish_vertex(u, g)` is invoked after all of the out edges of u have been examined and all of the adjacent vertices have been discovered.

### Example

The example in `examples/bfs_basics.cpp` demonstrates using the BGL Breadth-first search algorithm on the graph from Figure 5.

### See Also

`bfs_visitor` and `depth_first_search()`

Copyright © 2000 | Jeremy Siek, Univ.of Notre Dame (jsiek@lsc.nd.edu)