graph/quickbook/concepts/mutable_graph.qbk

[/
 / Copyright (C) 2007-2009 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 Mutable Graph]
A MutableGraph can be changed via the addition or removal of edges and vertices.

[h4 Refinement Of]
[Graph]

[h4 Valid Expressions]
[table
    [[Expression] [Description]]
    [
        [`add_edge(u,v,g)`]
        [
            Add a new vertex to the graph. The `vertex_descriptor` for the new vertex is returned.

            *Returns* `vertex_descriptor`
        ]
    ]
    [
        [`clear_vertex(v,g)`]
        [
            Removes all edges incident (both in-edges and out-edges for directed graphs) to the
            vertex `v`.

            *Returns* `void`

            *Precondition* `u` is a valid `vertex_descriptor` in `g`.

            *Postcondition* `u` does not appear as a source or target of any edge in `g`.
        ]
    ]
    [
        [`clear_out_edges(v,g)`]
        [
            Removes all edges out-edges of the vertex `v`. For undirected graphs this is functionally
            equivalent to `clear_vertex(v,g)`.

            *Returns* `void`

            *Precondition* `u` is a valid `vertex_descriptor` in `g`.

            *Postcondition* `u` does not appear as a source of any edge in `g`.
        ]
    ]
    [
        [`clear_in_edges(v,g)`]
        [
            Removes all edges in-edges of the vertex `v`. For undirected graphs this is functionally
            equivalent to `clear_vertex(v,g)`.

            *Returns* `void`

            *Precondition* `u` is a valid `vertex_descriptor` in `g`.

            *Postcondition* `u` does not appear as a target of any edge in `g`.
        ]
    ]
    [
        [`remove_vertex(v,g)`]
        [
            Remove the vertex `v` from the vertex set of the graph. Note that undefined behavior may
            result if there are edges remaining in the graph who's target is `u`. The `clear_vertex(v,g)`
            function should be called first to ensure the preconditions.

            *Returns* `vertex_descriptor`

            *Precondition* `u` is a valid `vertex_descriptor` in `g` and does not appear as the source
            or target of any edge in `g`.

            *Postcondition* `u` is not longer in the vertex set of `g`, nor is `u` a valid descriptor.
        ]
    ]
    [
        [`add_edge(u,v,g)`]
        [
            Inserts the edge /(u,v)/ into the graph, and returns an edge descriptor pointing to the new edge.
            If the graph disallows parallel edges, and the edge /(u,v)/ is already in the graph, then the boolean
            flag returned is false and the returned edge descriptor points to the already existing edge. Note
            that for undirected graphs, /(u,v)/ is the same edge as /(v,u)/, so after a call to the function
            `add_edge(u,v,g)`, this implies that edge /(u,v)/ will appear in the out-edges of `u` and /(u,v)/
            (or equivalently /(v,u)/) will appear in the out-edges of `v`. Put another way, `v` will be adjacent
            to `u` and `u` will be adjacent to `v`.

            *Returns* `vertex_descriptor`

            *Precondition* `u` and `v` are valid vertex descriptors in `g`.

            *Postcondition* The returned `edge_descriptor` points to a valid edge in `g`.
        ]
    ]
    [
        [`remove_edge(u,v,g)`]
        [
            Remove the edge (u,v) from the graph. If the graph allows parallel edges this remove all occurrences
            of /(u,v)/.

            *Returns* `void`

            *Precondition* `u` and `v` are valid vertex descriptors in `g`.

            *Postcondition* The edge /(u,v)/ is no longer in the edge set of `g`.
        ]
    ]
    [
        [`remove_edge(e,g)`]
        [
            Remove the edge `e` from the graph.

            *Returns* `void`

            *Precondition* `e` is an edge in the graph.

            *Postcondition* The edge `e` is no longer in the edge set of `g`.
        ]
    ]
    [
        [`remove_edge(ei,g)`]
        [
            Remove the edge pointed to by the edge iterator `ei` from the graph. This expression is only required
            when `g` also models [IncidenceGraph].

            *Returns* `void`

            *Precondition* `*ei` is an edge in the graph.

            *Postcondition* The edge `*ei` is no longer in the edge set of `g`.
        ]
    ]
    [
        [`remove_edge_if(pred,g)`]
        [
            Remove all edges from the graph `g` for which the predicate `pred` returns true.

            *Returns* `void`
        ]
    ]
    [
        [`remove_out_edge_if(v,pred,g)`]
        [
            Remove all out-edges of the vertex `v` for which the predicate `pred` returns true.

            *Returns* `void`
        ]
    ]
    [
        [`remove_in_edge_if(v,pred,g)`]
        [
            Remove all in-edges of the vertex `v` for which the predicate `pred` returns true.

            *Returns* `void`
        ]
    ]
]

[h4 Complexity Guarantees]
* Vertex insertion is guaranteed to be amortized constant time.
* Clearing  avertex is /O(E + V)/.
* Vertex removal is /O(E + V)/.
* Edge insertion must be either amortized constant time of it can be /O(log(E/V))/ if the insertion checks
to prevent the addition of parallel edges (which is a "feature" of some graph types).
* Edge removal is guaranteed to be /O(E)/.

[h4 Models]
* [undirected_graph]
* [directed_graph]
* [adjacency_list]

[endsect]