graph/quickbook/reference/breadth_first_search.qbk

[/
 / Copyright (c) 2007 Andrew Sutton
 /
 / Distributed under the Boost Software License, Version 1.0. (See accompanying
 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 /]

[section Breadth-First Search]
    template <class Graph, class P, class T, class R>
    void
    breadth_first_search(Graph& g,
                        typename graph_traits<Graph>::vertex_descriptor s,
                        bgl_named_params<P,T,R>& params = ``/defaults/``)

    template <class Graph, class Buffer, class Visitor, class P, class T, class R>
    void
    breadth_first_search(Graph& g,
                        typename graph_traits<Graph>::vertex_descriptor s,
                        Buffer& q,
                        Visitor vis,
                        bgl_named_params<P,T,R>& params = ``/defaults/``)

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.

[pre
BFS(G, s)
    for each vertex u in V\[G\]           initialize vertex u
        color\[u\] := WHITE
        d\[u\] := infinity
        p\[u\] := u
    end for

    color\[s\] := GRAY
    d\[s\] := 0
    ENQUEUE(Q, s)                       discover vertex s

    while not EMPTY(Q)
        u := DEQUEUE(Q)                 examine vertex u
        for each vertex v in adj\[u\]     examine edge /(u,v)/
            if(color\[v\] = WHITE)        /(u,v)/ is a tree edge
                color\[v\] := GRAY
                d\[v\] := d\[u\] + 1
                p\[v\] := u
                ENQUEUE(Q, v)           discover vertex v
            else                        /(u,v)/ is a non-tree edge
                if (color\[v\] = GRAY)    /(u,v)/ has a gray target
                ...
                else                    /(u,v)/ has a black target
                ...
            end if
        end for
        color\[u\] := BLACK               finsih vertex u
    end while
    return (d, p)
]

[heading Where Defined]
`boost/graph/breadth_first_search.hpp`

[heading Parameters]
[table
    [[Type] [Parameter] [Description]]
    [
        [in] [`Graph& g`]
        [
            A directed or undirected graph. The graph type must be a model of [VertexListGraph]
            and [IncidenceGraph].
        ]
    ]
    [
        [in] [`vertex_descriptor s`]
        [
            The source vertex where the search is started. This must be a valid vertex descriptor of
            `g`.
        ]
    ]
]

[heading Named Parameters]
[table
    [[Type] [Parameter] [Description]]
    [
        [in] [`visitor(Visitor vis)`]
        [
            A visitor object that is inovked inside the algorithm at event points specified by the
            [BFSVisitor]. The `vis` object must be model the [BFSVisitor] concept.

            *Default* `bfs_visitor<null_visitor>`.
        ]
    ]
    [
        [in] [`vertex_index_map(VeretxIndexMap index_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 ReadablePropertyMap. 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
            that your graph has an interior `vertex_index` property. For example
            `adjacency_list` with `VertexList=listS` does not have an interior
            `vertex_index` property.
        ]
    ]
    [
        [util] [`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 ReadWritePropertyMap 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` create from a `std::vector` of
            `default_color_type` of size `num_vertices(g)` and using `index_map` as
            the index map (to access colors for a vertex).
        ]
    ]
    [
        [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 [NoConcept Buffer].

            The `value_type` of the buffer must be the vertex_descriptor type for the graph.

            *Default* `boost::queue`
        ]
    ]
]

[heading Complexity]
The time complexity is /O(E + V)/.

[heading Example]

[endsect]