The adjacency_list class implements a generalized adjacency
list graph structure. The template parameters provide many
configuration options so that you can pick a version of the class that
best meets your needs. An adjacency-list
is basically a two-dimensional structure, where each element of the
first dimension represents a vertex, and each of the vertices contains
a one-dimensional structure that is its edge list. Figure 1 shows an adjacency list
representation of a directed graph.

Figure 1: Adjacency List Representation of a Directed Graph.

The
VertexList template parameter of the adjacency_list
class controls what kind of container is used to represent the outer
two-dimensional container. The OutEdgeList template parameter
controls what kind of container is used to represent the edge
lists. The choices for OutEdgeList and VertexList will
determine the space complexity of the graph structure, and will
determine the time complexity of the various graph operations. The
possible choices and tradeoffs are discussed in Section Choosing
the Edgelist and VertexList.

The Directed template parameter controls whether the graph is
directed, undirected, or directed with access to both the in-edges and
out-edges (which we call bidirectional). The bidirectional graph takes
up twice the space (per edge) of a directed graph since each edge will
appear in both an out-edge and in-edge list. Figure 2 shows an adjacency list
representation of an undirected graph.

Example

Template Parameters

The selector for the container used to represent the
edge-list for each of the vertices.

vecS

VertexList

The selector for the container used to represent the
vertex-list of the graph.

vecS

Directed

A selector to choose whether the graph is directed, undirected, or directed with bidirectional edge access (access to both out-edges and in-edges). The options are directedS, undirectedS, and bidirectionalS.

directedS

VertexProperties

for specifying internal property storage.

no_property

EdgeProperties

for specifying internal property storage.

no_property

GraphProperties

for specifying property storage for the graph object.

no_property

EdgeList

The selector for the container used to represent the
edge-list for the graph.

Where Defined

Vertex and Edge Properties

Properties such as color, distance, weight, and user-defined
properties can be attached to the vertices and edges of the graph
using properties. The property values can be read from and written to
via the property maps provided by the graph. The property maps are
obtained via the get(property, g) function. How to use
properties is described in Section Internal
Properties . The property maps are objects that implement the
interface defined in Section Property Map
Concepts or may be bundled properties,
which have a more succinct syntax. The types of all property values
must be Copy Constructible, Assignable, and Default Constructible.
The property maps obtained from the
adjacency_list class are models of the Lvalue Property
Map concept. If the adjacency_list is const,
then the property map is constant, otherwise the property
map is mutable.

If the VertexList of the graph is vecS, then the
graph has a builtin vertex indices accessed via the property map for
the vertex_index_t property. The indices fall in the range
[0, num_vertices(g)) and are contiguous. When a vertex is
removed the indices are adjusted so that they retain these
properties. Some care must be taken when using these indices to access
exterior property storage. The property map for vertex index is a
model of Readable
Property Map.

Iterator and Descriptor Stability/Invalidation

Some care must be taken when changing the structure of a graph (via
adding or removing edges). Depending on the type of
adjacency_list and on the operation, some of the iterator or
descriptor objects that point into the graph may become invalid. For
example, the following code will result in undefined (bad) behavior:

The reason this is a problem is that we are invoking
remove_vertex(), which when used with an
adjacency_list where VertexList=vecS, invalidates
all iterators and descriptors for the graph (such as vi and
vi_end), thereby causing trouble in subsequent iterations of
the loop.

If we use a different kind of adjacency_list, where
VertexList=listS, then the iterators are not invalidated by
calling remove_vertex unless the iterator is pointing to the
actual vertex that was removed. The following code demonstrates this.

The stability issue also affects vertex and edge descriptors. For
example, suppose you use vector of vertex descriptors to keep track of
the parents (or predecessors) of vertices in a shortest paths tree
(see examples/dijkstra-example.cpp).
You create the parent vector with a call to
dijkstra_shortest_paths(), and then remove a vertex from the
graph. Subsequently you try to use the parent vector, but since all
vertex descriptors have become invalid, the result is incorrect.

Note that in this discussion iterator and descriptor invalidation is
concerned with the invalidation of iterators and descriptors that are
not directly affected by the operation. For example, performing
remove_edge(u, v, g) will always invalidate any edge
descriptor for (u,v) or edge iterator pointing to (u,v),
regardless of the kind adjacency_list. In this discussion
of iterator and descriptor invalidation, we are only concerned with the
affect of remove_edge(u, v, g) on edge descriptors and
iterators that point to other edges (not (u,v)).

In general, if you want your vertex and edge descriptors to be stable
(never invalidated) then use listS or setS for the
VertexList and OutEdgeList template parameters of
adjacency_list. If you are not as concerned about descriptor
and iterator stability, and are more concerned about memory
consumption and graph traversal speed, use vecS for the
VertexList and/or OutEdgeList template parameters.

The following table summarizes which operations cause descriptors and
iterators to become invalid. In the table, EL is an
abbreviation for OutEdgeList and VL means
VertexList. The Adj Iter category includes the
out_edge_iterator, in_edge_iterator, and
adjacency_iterator types. A more detailed description of
descriptor and iterator invalidation is given in the documentation for
each operation.

Associated Types

The type for the vertex descriptors associated with the
adjacency_list.
graph_traits<adjacency_list>::edge_descriptor
andadjacency_list_traits<OutEdgeList, VertexList, Directed, EdgeList>::edge_descriptor

The type for the edge descriptors associated with the
adjacency_list.
graph_traits<adjacency_list>::vertex_iterator

The type for the iterators returned by vertices().
When VertexList=vecS then the vertex_iterator models
RandomAccessIterator. Otherwise
the vertex_iterator models BidirectionalIterator.
graph_traits<adjacency_list>::edge_iterator

The type for the iterators returned by edges().
The edge_iterator models BidirectionalIterator.
graph_traits<adjacency_list>::out_edge_iterator

The type for the iterators returned by out_edges().
When OutEdgeList=vecS then the out_edge_iterator models
RandomAccessIterator. When OutEdgeList=slistS then the
out_edge_iterator models
ForwardIterator. Otherwise the out_edge_iterator models
BidirectionalIterator.
graph_traits<adjacency_list>::adjacency_iterator

The type for the iterators returned by adjacent_vertices().
The adjacency_iterator models the same iterator concept
as out_edge_iterator.
adjacency_list::inv_adjacency_iterator

The type for the iterators returned by inv_adjacent_vertices().
The inv_adjacency_iterator models the same iterator concept
as out_edge_iterator.
graph_traits<adjacency_list>::directed_category
andadjacency_list_traits<OutEdgeList, VertexList, Directed, EdgeList>::directed_category

This describes whether the graph class allows the insertion of
parallel edges (edges with the same source and target). The two tags
are allow_parallel_edge_tag and
disallow_parallel_edge_tag. The
setS and hash_setS variants disallow
parallel edges while the others allow parallel edges.
graph_traits<adjacency_list>::vertices_size_type
andadjacency_list_traits<OutEdgeList, VertexList, Directed_list, EdgeList>::vertices_size_type

The type used for dealing with the number of vertices in the graph.
graph_traits<adjacency_list>::edges_size_type
andadjacency_list_traits<OutEdgeList, VertexList, Directed_list, EdgeList>::edges_size_type

The type used for dealing with the number of edges in the graph.
graph_traits<adjacency_list>::degree_size_type

The type used for dealing with the number of edges incident to a vertex
in the graph.
property_map<adjacency_list, Property>::type
andproperty_map<adjacency_list, Property>::const_type

The property map type for vertex or edge properties in the graph. The
specific property is specified by the Property template argument,
and must match one of the properties specified in the
VertexProperties or EdgeProperties for the graph.
graph_property<adjacency_list, Property>::type

The property value type for the graph property specified by the
Property tag.
adjacency_list::out_edge_list_selector

Creates a graph object with n vertices and with the edges
specified in the edge list given by the range [first, last).
The EdgeIterator and EdgePropertyIterator must be a
model of InputIterator.
The value type of the EdgeIterator must be a
std::pair, where the type in the pair is an integer type. The
integers will correspond to vertices, and they must all fall in the
range of [0, n). The value_type of the
ep_iter should be EdgeProperties.

void clear()

Remove all of the edges and vertices from the graph.

void swap(adjacency_list& x)

Swap the vertices, edges, and properties of this graph with the
vertices, edges, and properties of graph x.

Returns an iterator-range providing access to the vertices in graph
g to which u is adjacent. (inv is for
inverse.) For example, if v -> u is an edge in the graph,
then v will be in this iterator range. This function is only
available for bidirectional and undirected adjacency_list's.

Returns an iterator-range providing access to the out-edges of vertex
u in graph g. If the graph is undirected, this
iterator-range provides access to all edges incident on vertex
u. For both directed and undirected graphs, for an out-edge
e, source(e, g) == u and target(e, g) == v
where v is a vertex adjacent to u.

Returns an iterator-range providing access to the in-edges of vertex
v in graph g. This operation is only available if
bidirectionalS was specified for the Directed
template parameter. For an in-edge e, target(e, g) == v
and source(e, g) == u for some vertex u that is
adjacent to v, whether the graph is directed or undirected.

Returns a pair of out-edge iterators that give the range for
all the parallel edges from u to v. This
function only works when the OutEdgeList for the
adjacency_list is a container that sorts the
out edges according to target vertex, and allows for
parallel edges. The multisetS selector chooses
such a container.

Structure Modification

Adds edge (u,v) to the graph and returns the edge descriptor
for the new edge. For graphs that do not allow parallel edges, if the
edge is already in the graph then a duplicate will not be added and
the bool flag will be false. When the flag is
false, the
returned edge descriptor points to the already existing edge.

The placement of the new edge in the out-edge list is in general
unspecified, though ordering of the out-edge list can be accomplished
through the choice of OutEdgeList.
If the VertexList selector is
vecS, and if either vertex descriptor u or
v (which are integers) has a value greater than the current
number of vertices in the graph, the graph is enlarged so that the
number of vertices is std::max(u,v) + 1.

If the OutEdgeList selector is vecS then this operation
will invalidate any out_edge_iterator for vertex
u. This also applies if the OutEdgeList is a user-defined
container that invalidates its iterators when push(container,
x) is invoked (see Section Customizing the
Adjacency List Storage). If the graph is also bidirectional then
any in_edge_iterator for v is also invalidated. If
instead the graph is undirected then any out_edge_iterator
for v is also invalidated. If instead the graph is directed,
then add_edge() also invalidates any edge_iterator.

This operation causes any outstanding edge descriptors or iterators
that point to edge (u,v) to become invalid. In addition, if
the OutEdgeList selector is vecS then this operation
will invalidate any iterators that point into the edge-list for vertex
u and also for vertex v in the undirected and
bidirectional case. Also, for directed graphs this invalidates any
edge_iterator.

void remove_edge(edge_descriptor e, adjacency_list& g)

Removes the edge e from the graph. This differs from the
remove_edge(u, v, g) function in the case of a
multigraph. This remove_edge(e, g) function removes a single
edge, whereas the remove_edge(u, v, g) function removes all
edges (u,v).

This operation invalidates any outstanding edge descriptors and
iterators for the same edge pointed to by descriptor e. In
addition, this operation will invalidate any iterators that point into
the edge-list for the target(e, g). Also, for directed
graphs this invalidates any edge_iterator for the graph.

void remove_edge(out_edge_iterator iter, adjacency_list& g)

This has the same effect as remove_edge(*iter, g). The
difference is that this function has constant time complexity
in the case of directed graphs, whereas remove_edge(e, g)
has time complexity O(E/V).

Adds a vertex to the graph with the specified properties. Returns the
vertex descriptor for the new vertex.

void clear_vertex(vertex_descriptor u, adjacency_list& g)

Removes all edges to and from vertex u. The vertex still appears
in the vertex set of the graph.

The affect on descriptor and iterator stability is the
same as that of invoking remove_edge() for all of
the edges that have u as the source or target.

void clear_out_edges(vertex_descriptor u, adjacency_list& g)

Removes all out-edges from vertex u. The vertex still appears
in the vertex set of the graph.

The affect on descriptor and iterator stability is the
same as that of invoking remove_edge() for all of
the edges that have u as the source.

This operation is not applicable to undirected graphs
(use clear_vertex() instead).

void clear_in_edges(vertex_descriptor u, adjacency_list& g)

Removes all in-edges from vertex u. The vertex still appears
in the vertex set of the graph.

The affect on descriptor and iterator stability is the
same as that of invoking remove_edge() for all of
the edges that have u as the target.

This operation is only applicable to bidirectional graphs.

void remove_vertex(vertex_descriptor u, adjacency_list& g)

Remove vertex u from the vertex set of the graph. It is assumed
that there are no edges to or from vertex u when it is removed.
One way to make sure of this is to invoke clear_vertex()
beforehand.

If the VertexList template parameter of the
adjacency_list was vecS, then all vertex
descriptors, edge descriptors, and iterators for the graph are
invalidated by this operation. The builtin
vertex_index_t property for each vertex is renumbered so that
after the operation the vertex indices still form a contiguous range
[0, num_vertices(g)). If you are using external property
storage based on the builtin vertex index, then the external storage
will need to be adjusted. Another option is to not use the builtin
vertex index, and instead use a property to add your own vertex index
property. If you need to make frequent use of the
remove_vertex() function the listS selector is a
much better choice for the VertexList template parameter.

This sets the property value for x to
value. x is either a vertex or edge descriptor.
Value must be convertible to
typename property_traits<property_map<adjacency_list, PropertyTag>::type&gt::value_type