graph/quickbook/reference/depth_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 Depth-First Search]
    template <class Graph, class P, class T, class R>
    void
    depth_first_search(Graph& g,
                       bgl_named_params<P,T,R>& params = ``/defaults/``)

    template <class Graph, class Visitor, class ColorMap>
    void
    depth_first_search(Graph& g,
                        Visitor vis,
                        ColorMap color,
                        typename graph_traits<Graph>::vertex_descriptor s)

The `depth_first_search()` function performs a depth-first traversal of the vertices
in a directed graph. When possible, a depth-first traversal chooses a vertex adjacent
to the current vertex to visit next. If all adjacent vertices have already been
discovered, or there are no adjacent vertices, then the algorithm backtracks to the
last vertex that had undiscovered neighbors. Once all reachable vertices have been
visited, the algorithm selects from any remaining undiscovered vertices and continues
the traversal. The algorithm finishes when all vertices have been visited. Depth-first
search is useful for categorizing edges in a graph, and for imposing an ordering on the
vertices. Section /Depth-First Search/ describes the various properties of DFS and
walks through an example.

Similar to BFS, color markers are used to keep track of which vertices have been
discovered. White marks vertices that have yet to be discovered, gray marks a
vertex that is discovered but still has vertices adjacent to it that are undiscovered.
A black vertex is discovered vertex that is not adjacent to any white vertices.

The `depth_first_search()` function invokes user-defined actions at certain event-points
within the algorithm. This provides a mechanism for adapting the generic DFS algorithm
to the many situations in which it can be used. In the pseudo-code below, the event
points for DFS are indicated in by the triangles and labels on the right. The user-defined
actions must be provided in the form of a visitor object, that is, an object whose type
meets the requirements for a [DFSVisitor]. In the pseudo-code we show the algorithm
computing predecessors /p/, discovery time /d/ and finish time /t/. By default, the
`depth_first_search()` function does not compute these properties, however there are
pre-defined visitors such as [predecessor_recorder] and [time_stamper] that
can be used to do this.

[pre
DFS(G)
    for each vertex u in V              initialize vertex u
        color\[u\] := WHITE
        p\[u\] = u
    end for

    time := 0
    if there is a starting vertex s
        call DFS-VISIT(G, s)            start vertex /s/

    for each vertex u in V
        if color\[u\] = WHITE             start vertex /u/
        call DFS-VISIT(G, u)
    end for

    return (p,d_time,f_time)

DFS-VISIT(G, u)
    color\[u\] := GRAY                    discover vertex /u/
    d_time\[u\] := time := time + 1

    for each v in Adj\[u\]                examine edge /(u,v)/
        if (color\[v\] = WHITE)           /(u,v)/ is a tree edge
            p\[v\] = u
            call DFS-VISIT(G, v)
        else if (color\[v\] = GRAY)       /(u,v)/ is a back edge
            ...
        else if (color\[v\] = BLACK)      /(u,v)/ is a cross or forward edge
            ...
    end for

    color\[u\] := BLACK                   finish vertex /u/
    f_time\[u\] := time := time + 1
]

[heading Where Defined]
`boost/graph/depth_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`]
        [
            This specifies the vertex that the depth-first search should originate from. Note
            that this can also be given as a named parameter.
        ]
    ]
]

[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
            [DFSVisitor]. The `vis` object must be model the [DFSVisitor] concept.

            *Default* `bfs_visitor<null_visitor>`.
        ]
    ]
    [
        [in] [`root_vertex(vertex_descriptor s)`]
        [
            This specifies the vertex that the depth-first search should originate from.

            *Default* `*vertices(g).first`
        ]
    ]
    [
        [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).
        ]
    ]
]

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

[heading Example]

[endsect]