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 DFS Visitor. In the pseudo-code
we show the algorithm computing predecessors p, discover 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.

Where Defined

Parameters

Named Parameters

IN: visitor(DFSVisitor vis)

A visitor object that is invoked inside the algorithm at the
event-points specified by the DFS
Visitor concept. The visitor object is passed by value [1]. Default:dfs_visitor<null_visitor>Python: The parameter should be an object that derives from
the DFSVisitor type of
the graph.

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.Python: The color map must be a vertex_color_map for
the graph.

This specifies the vertex that the depth-first search should
originate from. The type is the type of a vertex descriptor for the
given graph.Default:*vertices(g).first

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).
Note: if you use this default, make sure your graph has
an internal vertex_index property. For example,
adjacenty_list with VertexList=listS does
not have an internal vertex_index property.Python: Unsupported parameter.

Visitor Event Points

vis.initialize_vertex(s, g) is invoked on every
vertex of the graph before the start of the graph search.

vis.start_vertex(s, g) is invoked on the source
vertex once before the start of the search.

vis.discover_vertex(u, g) is invoked when a vertex
is encountered for the first time.

vis.examine_edge(e, g) is invoked on every out-edge
of each vertex after it is discovered.

vis.tree_edge(e, g) is invoked on each edge as it
becomes a member of the edges that form the search tree. If you
wish to record predecessors, do so at this event point.

vis.back_edge(e, g) is invoked on the back edges in
the graph.

vis.forward_or_cross_edge(e, g) is invoked on
forward or cross edges in the graph. In an undirected graph this
method is never called.

vis.finish_vertex(u, g) is invoked on a vertex after
all of its out edges have been added to the search tree and all of
the adjacent vertices have been discovered (but before their
out-edges have been examined).

Example

See Also

Notes

[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.