# [−][src]Struct random_graphs::Graph

`pub struct Graph<N, E, Ty = Directed, Ix = u32> { /* fields omitted */ }`

`Graph<N, E, Ty, Ix>` is a graph datastructure using an adjacency list representation.

`Graph` is parameterized over:

• Associated data `N` for nodes and `E` for edges, called weights. The associated data can be of arbitrary type.
• Edge type `Ty` that determines whether the graph edges are directed or undirected.
• Index type `Ix`, which determines the maximum size of the graph.

The `Graph` is a regular Rust collection and is `Send` and `Sync` (as long as associated data `N` and `E` are).

The graph uses O(|V| + |E|) space, and allows fast node and edge insert, efficient graph search and graph algorithms. It implements O(e') edge lookup and edge and node removals, where e' is some local measure of edge count. Based on the graph datastructure used in rustc.

Here's an example of building a graph with directed edges, and below an illustration of how it could be rendered with graphviz (see `Dot`):

```use petgraph::Graph;

let mut deps = Graph::<&str, &str>::new();
deps.extend_with_edges(&[
(pg, fb), (pg, qc),
(qc, rand), (rand, libc), (qc, libc),
]);```

### Graph Indices

The graph maintains indices for nodes and edges, and node and edge weights may be accessed mutably. Indices range in a compact interval, for example for n nodes indices are 0 to n - 1 inclusive.

`NodeIndex` and `EdgeIndex` are types that act as references to nodes and edges, but these are only stable across certain operations:

• Removing nodes or edges may shift other indices. Removing a node will force the last node to shift its index to take its place. Similarly, removing an edge shifts the index of the last edge.
• Adding nodes or edges keeps indices stable.

The `Ix` parameter is `u32` by default. The goal is that you can ignore this parameter completely unless you need a very big graph -- then you can use `usize`.

• The fact that the node and edge indices in the graph each are numbered in compact intervals (from 0 to n - 1 for n nodes) simplifies some graph algorithms.

• You can select graph index integer type after the size of the graph. A smaller size may have better performance.

• Using indices allows mutation while traversing the graph, see `Dfs`, and `.neighbors(a).detach()`.

• You can create several graphs using the equal node indices but with differing weights or differing edges.

• Indices don't allow as much compile time checking as references.

## Methods

### `impl<N, E> Graph<N, E, Directed, u32>`[src]

#### `pub fn new() -> Graph<N, E, Directed, u32>`[src]

Create a new `Graph` with directed edges.

This is a convenience method. Use `Graph::with_capacity` or `Graph::default` for a constructor that is generic in all the type parameters of `Graph`.

### `impl<N, E> Graph<N, E, Undirected, u32>`[src]

#### `pub fn new_undirected() -> Graph<N, E, Undirected, u32>`[src]

Create a new `Graph` with undirected edges.

This is a convenience method. Use `Graph::with_capacity` or `Graph::default` for a constructor that is generic in all the type parameters of `Graph`.

### `impl<N, E, Ty, Ix> Graph<N, E, Ty, Ix> where    Ix: IndexType,    Ty: EdgeType, `[src]

#### `pub fn with_capacity(nodes: usize, edges: usize) -> Graph<N, E, Ty, Ix>`[src]

Create a new `Graph` with estimated capacity.

#### `pub fn node_count(&self) -> usize`[src]

Return the number of nodes (vertices) in the graph.

Computes in O(1) time.

#### `pub fn edge_count(&self) -> usize`[src]

Return the number of edges in the graph.

Computes in O(1) time.

#### `pub fn is_directed(&self) -> bool`[src]

Whether the graph has directed edges or not.

#### `pub fn add_node(&mut self, weight: N) -> NodeIndex<Ix>`[src]

Add a node (also called vertex) with associated data `weight` to the graph.

Computes in O(1) time.

Return the index of the new node.

Panics if the Graph is at the maximum number of nodes for its index type (N/A if usize).

#### `pub fn node_weight(&self, a: NodeIndex<Ix>) -> Option<&N>`[src]

Access the weight for node `a`.

Also available with indexing syntax: `&graph[a]`.

#### `pub fn node_weight_mut(&mut self, a: NodeIndex<Ix>) -> Option<&mut N>`[src]

Access the weight for node `a`, mutably.

Also available with indexing syntax: `&mut graph[a]`.

#### `pub fn add_edge(    &mut self,     a: NodeIndex<Ix>,     b: NodeIndex<Ix>,     weight: E) -> EdgeIndex<Ix>`[src]

Add an edge from `a` to `b` to the graph, with its associated data `weight`.

Return the index of the new edge.

Computes in O(1) time.

Panics if any of the nodes don't exist.
Panics if the Graph is at the maximum number of edges for its index type (N/A if usize).

Note: `Graph` allows adding parallel (“duplicate”) edges. If you want to avoid this, use `.update_edge(a, b, weight)` instead.

#### `pub fn update_edge(    &mut self,     a: NodeIndex<Ix>,     b: NodeIndex<Ix>,     weight: E) -> EdgeIndex<Ix>`[src]

Add or update an edge from `a` to `b`. If the edge already exists, its weight is updated.

Return the index of the affected edge.

Computes in O(e') time, where e' is the number of edges connected to `a` (and `b`, if the graph edges are undirected).

Panics if any of the nodes don't exist.

#### `pub fn edge_weight(&self, e: EdgeIndex<Ix>) -> Option<&E>`[src]

Access the weight for edge `e`.

Also available with indexing syntax: `&graph[e]`.

#### `pub fn edge_weight_mut(&mut self, e: EdgeIndex<Ix>) -> Option<&mut E>`[src]

Access the weight for edge `e`, mutably.

Also available with indexing syntax: `&mut graph[e]`.

#### `pub fn edge_endpoints(    &self,     e: EdgeIndex<Ix>) -> Option<(NodeIndex<Ix>, NodeIndex<Ix>)>`[src]

Access the source and target nodes for `e`.

#### `pub fn remove_node(&mut self, a: NodeIndex<Ix>) -> Option<N>`[src]

Remove `a` from the graph if it exists, and return its weight. If it doesn't exist in the graph, return `None`.

Apart from `a`, this invalidates the last node index in the graph (that node will adopt the removed node index). Edge indices are invalidated as they would be following the removal of each edge with an endpoint in `a`.

Computes in O(e') time, where e' is the number of affected edges, including n calls to `.remove_edge()` where n is the number of edges with an endpoint in `a`, and including the edges with an endpoint in the displaced node.

#### `pub fn remove_edge(&mut self, e: EdgeIndex<Ix>) -> Option<E>`[src]

Remove an edge and return its edge weight, or `None` if it didn't exist.

Apart from `e`, this invalidates the last edge index in the graph (that edge will adopt the removed edge index).

Computes in O(e') time, where e' is the size of four particular edge lists, for the vertices of `e` and the vertices of another affected edge.

#### `pub fn neighbors(&self, a: NodeIndex<Ix>) -> Neighbors<E, Ix>`[src]

Return an iterator of all nodes with an edge starting from `a`.

• `Directed`: Outgoing edges from `a`.
• `Undirected`: All edges from or to `a`.

Produces an empty iterator if the node doesn't exist.
Iterator element type is `NodeIndex<Ix>`.

Use `.neighbors(a).detach()` to get a neighbor walker that does not borrow from the graph.

#### `pub fn neighbors_directed(    &self,     a: NodeIndex<Ix>,     dir: Direction) -> Neighbors<E, Ix>`[src]

Return an iterator of all neighbors that have an edge between them and `a`, in the specified direction. If the graph's edges are undirected, this is equivalent to .neighbors(a).

• `Directed`, `Outgoing`: All edges from `a`.
• `Directed`, `Incoming`: All edges to `a`.
• `Undirected`: All edges from or to `a`.

Produces an empty iterator if the node doesn't exist.
Iterator element type is `NodeIndex<Ix>`.

For a `Directed` graph, neighbors are listed in reverse order of their addition to the graph, so the most recently added edge's neighbor is listed first. The order in an `Undirected` graph is arbitrary.

Use `.neighbors_directed(a, dir).detach()` to get a neighbor walker that does not borrow from the graph.

#### `pub fn neighbors_undirected(&self, a: NodeIndex<Ix>) -> Neighbors<E, Ix>`[src]

Return an iterator of all neighbors that have an edge between them and `a`, in either direction. If the graph's edges are undirected, this is equivalent to .neighbors(a).

• `Directed` and `Undirected`: All edges from or to `a`.

Produces an empty iterator if the node doesn't exist.
Iterator element type is `NodeIndex<Ix>`.

Use `.neighbors_undirected(a).detach()` to get a neighbor walker that does not borrow from the graph.

#### `pub fn edges(&self, a: NodeIndex<Ix>) -> Edges<E, Ty, Ix>`[src]

Return an iterator of all edges of `a`.

• `Directed`: Outgoing edges from `a`.
• `Undirected`: All edges connected to `a`.

Produces an empty iterator if the node doesn't exist.
Iterator element type is `EdgeReference<E, Ix>`.

#### `pub fn edges_directed(    &self,     a: NodeIndex<Ix>,     dir: Direction) -> Edges<E, Ty, Ix>`[src]

Return an iterator of all edges of `a`, in the specified direction.

• `Directed`, `Outgoing`: All edges from `a`.
• `Directed`, `Incoming`: All edges to `a`.
• `Undirected`, `Outgoing`: All edges connected to `a`, with `a` being the source of each edge.
• `Undirected`, `Incoming`: All edges connected to `a`, with `a` being the target of each edge.

Produces an empty iterator if the node `a` doesn't exist.
Iterator element type is `EdgeReference<E, Ix>`.

#### `pub fn edges_connecting(    &self,     a: NodeIndex<Ix>,     b: NodeIndex<Ix>) -> EdgesConnecting<E, Ty, Ix>`[src]

Return an iterator over all the edges connecting `a` and `b`.

• `Directed`: Outgoing edges from `a`.
• `Undirected`: All edges connected to `a`.

Iterator element type is `EdgeReference<E, Ix>`.

#### `pub fn contains_edge(&self, a: NodeIndex<Ix>, b: NodeIndex<Ix>) -> bool`[src]

Lookup if there is an edge from `a` to `b`.

Computes in O(e') time, where e' is the number of edges connected to `a` (and `b`, if the graph edges are undirected).

#### `pub fn find_edge(    &self,     a: NodeIndex<Ix>,     b: NodeIndex<Ix>) -> Option<EdgeIndex<Ix>>`[src]

Lookup an edge from `a` to `b`.

Computes in O(e') time, where e' is the number of edges connected to `a` (and `b`, if the graph edges are undirected).

#### `pub fn find_edge_undirected(    &self,     a: NodeIndex<Ix>,     b: NodeIndex<Ix>) -> Option<(EdgeIndex<Ix>, Direction)>`[src]

Lookup an edge between `a` and `b`, in either direction.

If the graph is undirected, then this is equivalent to `.find_edge()`.

Return the edge index and its directionality, with `Outgoing` meaning from `a` to `b` and `Incoming` the reverse, or `None` if the edge does not exist.

#### `pub fn externals(&self, dir: Direction) -> Externals<N, Ty, Ix>`[src]

Return an iterator over either the nodes without edges to them (`Incoming`) or from them (`Outgoing`).

An internal node has both incoming and outgoing edges. The nodes in `.externals(Incoming)` are the source nodes and `.externals(Outgoing)` are the sinks of the graph.

For a graph with undirected edges, both the sinks and the sources are just the nodes without edges.

The whole iteration computes in O(|V|) time.

#### `pub fn node_indices(&self) -> NodeIndices<Ix>`[src]

Return an iterator over the node indices of the graph.

For example, in a rare case where a graph algorithm were not applicable, the following code will iterate through all nodes to find a specific index:

`let index = g.node_indices().find(|i| g[*i] == "book").unwrap();`

#### `pub fn node_weights_mut(&mut self) -> NodeWeightsMut<N, Ix>`[src]

The order in which weights are yielded matches the order of their node indices.

#### `pub fn edge_indices(&self) -> EdgeIndices<Ix>`[src]

Return an iterator over the edge indices of the graph

#### `pub fn edge_references(&self) -> EdgeReferences<E, Ix>`[src]

Create an iterator over all edges, in indexed order.

Iterator element type is `EdgeReference<E, Ix>`.

#### `pub fn edge_weights_mut(&mut self) -> EdgeWeightsMut<E, Ix>`[src]

The order in which weights are yielded matches the order of their edge indices.

#### `pub fn raw_nodes(&self) -> &[Node<N, Ix>]`[src]

Access the internal node array.

#### `pub fn raw_edges(&self) -> &[Edge<E, Ix>]`[src]

Access the internal edge array.

#### `pub fn into_nodes_edges(self) -> (Vec<Node<N, Ix>>, Vec<Edge<E, Ix>>)`[src]

Convert the graph into a vector of Nodes and a vector of Edges

#### `pub fn first_edge(    &self,     a: NodeIndex<Ix>,     dir: Direction) -> Option<EdgeIndex<Ix>>`[src]

Accessor for data structure internals: the first edge in the given direction.

#### `pub fn next_edge(    &self,     e: EdgeIndex<Ix>,     dir: Direction) -> Option<EdgeIndex<Ix>>`[src]

Accessor for data structure internals: the next edge for the given direction.

#### `pub fn index_twice_mut<T, U>(    &mut self,     i: T,     j: U) -> (&mut <Graph<N, E, Ty, Ix> as Index<T>>::Output, &mut <Graph<N, E, Ty, Ix> as Index<U>>::Output) where    T: GraphIndex,    U: GraphIndex,    Graph<N, E, Ty, Ix>: IndexMut<T>,    Graph<N, E, Ty, Ix>: IndexMut<U>, `[src]

Index the `Graph` by two indices, any combination of node or edge indices is fine.

Panics if the indices are equal or if they are out of bounds.

```use petgraph::{Graph, Incoming};
use petgraph::visit::Dfs;

let mut gr = Graph::new();

// walk the graph and sum incoming edges into the node weight
let mut dfs = Dfs::new(&gr, a);
while let Some(node) = dfs.next(&gr) {
// use a walker -- a detached neighbors iterator
let mut edges = gr.neighbors_directed(node, Incoming).detach();
while let Some(edge) = edges.next_edge(&gr) {
let (nw, ew) = gr.index_twice_mut(node, edge);
*nw += *ew;
}
}

// check the result
assert_eq!(gr[a], 0.);
assert_eq!(gr[b], 4.);
assert_eq!(gr[c], 2.);```

#### `pub fn reverse(&mut self)`[src]

Reverse the direction of all edges

#### `pub fn clear(&mut self)`[src]

Remove all nodes and edges

Remove all edges

#### `pub fn capacity(&self) -> (usize, usize)`[src]

Return the current node and edge capacity of the graph.

#### `pub fn reserve_nodes(&mut self, additional: usize)`[src]

Reserves capacity for at least `additional` more nodes to be inserted in the graph. Graph may reserve more space to avoid frequent reallocations.

Panics if the new capacity overflows `usize`.

#### `pub fn reserve_edges(&mut self, additional: usize)`[src]

Reserves capacity for at least `additional` more edges to be inserted in the graph. Graph may reserve more space to avoid frequent reallocations.

Panics if the new capacity overflows `usize`.

#### `pub fn reserve_exact_nodes(&mut self, additional: usize)`[src]

Reserves the minimum capacity for exactly `additional` more nodes to be inserted in the graph. Does nothing if the capacity is already sufficient.

Prefer `reserve_nodes` if future insertions are expected.

Panics if the new capacity overflows `usize`.

#### `pub fn reserve_exact_edges(&mut self, additional: usize)`[src]

Reserves the minimum capacity for exactly `additional` more edges to be inserted in the graph. Does nothing if the capacity is already sufficient.

Prefer `reserve_edges` if future insertions are expected.

Panics if the new capacity overflows `usize`.

#### `pub fn shrink_to_fit_nodes(&mut self)`[src]

Shrinks the capacity of the underlying nodes collection as much as possible.

#### `pub fn shrink_to_fit_edges(&mut self)`[src]

Shrinks the capacity of the underlying edges collection as much as possible.

#### `pub fn shrink_to_fit(&mut self)`[src]

Shrinks the capacity of the graph as much as possible.

#### `pub fn retain_nodes<F>(&mut self, visit: F) where    F: FnMut(Frozen<Graph<N, E, Ty, Ix>>, NodeIndex<Ix>) -> bool, `[src]

Keep all nodes that return `true` from the `visit` closure, remove the others.

`visit` is provided a proxy reference to the graph, so that the graph can be walked and associated data modified.

The order nodes are visited is not specified.

#### `pub fn retain_edges<F>(&mut self, visit: F) where    F: FnMut(Frozen<Graph<N, E, Ty, Ix>>, EdgeIndex<Ix>) -> bool, `[src]

Keep all edges that return `true` from the `visit` closure, remove the others.

`visit` is provided a proxy reference to the graph, so that the graph can be walked and associated data modified.

The order edges are visited is not specified.

#### `pub fn from_edges<I>(iterable: I) -> Graph<N, E, Ty, Ix> where    I: IntoIterator,    N: Default,    <I as IntoIterator>::Item: IntoWeightedEdge<E>,    <<I as IntoIterator>::Item as IntoWeightedEdge<E>>::NodeId: Into<NodeIndex<Ix>>, `[src]

Create a new `Graph` from an iterable of edges.

Node weights `N` are set to default values. Edge weights `E` may either be specified in the list, or they are filled with default values.

Nodes are inserted automatically to match the edges.

```use petgraph::Graph;

let gr = Graph::<(), i32>::from_edges(&[
(0, 1), (0, 2), (0, 3),
(1, 2), (1, 3),
(2, 3),
]);```

#### `pub fn extend_with_edges<I>(&mut self, iterable: I) where    I: IntoIterator,    N: Default,    <I as IntoIterator>::Item: IntoWeightedEdge<E>,    <<I as IntoIterator>::Item as IntoWeightedEdge<E>>::NodeId: Into<NodeIndex<Ix>>, `[src]

Extend the graph from an iterable of edges.

Node weights `N` are set to default values. Edge weights `E` may either be specified in the list, or they are filled with default values.

Nodes are inserted automatically to match the edges.

#### `pub fn map<'a, F, G, N2, E2>(    &'a self,     node_map: F,     edge_map: G) -> Graph<N2, E2, Ty, Ix> where    F: FnMut(NodeIndex<Ix>, &'a N) -> N2,    G: FnMut(EdgeIndex<Ix>, &'a E) -> E2, `[src]

Create a new `Graph` by mapping node and edge weights to new values.

The resulting graph has the same structure and the same graph indices as `self`.

#### `pub fn filter_map<'a, F, G, N2, E2>(    &'a self,     node_map: F,     edge_map: G) -> Graph<N2, E2, Ty, Ix> where    F: FnMut(NodeIndex<Ix>, &'a N) -> Option<N2>,    G: FnMut(EdgeIndex<Ix>, &'a E) -> Option<E2>, `[src]

Create a new `Graph` by mapping nodes and edges. A node or edge may be mapped to `None` to exclude it from the resulting graph.

Nodes are mapped first with the `node_map` closure, then `edge_map` is called for the edges that have not had any endpoint removed.

The resulting graph has the structure of a subgraph of the original graph. If no nodes are removed, the resulting graph has compatible node indices; if neither nodes nor edges are removed, the result has the same graph indices as `self`.

#### `pub fn into_edge_type<NewTy>(self) -> Graph<N, E, NewTy, Ix> where    NewTy: EdgeType, `[src]

Convert the graph into either undirected or directed. No edge adjustments are done, so you may want to go over the result to remove or add edges.

Computes in O(1) time.

## Trait Implementations

### `impl<N, E, Ty, Ix> Clone for Graph<N, E, Ty, Ix> where    E: Clone,    Ix: IndexType,    N: Clone, `[src]

The resulting cloned graph has the same graph indices as `self`.

### `impl<N, E, Ty, Ix> Default for Graph<N, E, Ty, Ix> where    Ix: IndexType,    Ty: EdgeType, `[src]

Create a new empty `Graph`.

### `impl<N, E, Ty, Ix> From<StableGraph<N, E, Ty, Ix>> for Graph<N, E, Ty, Ix> where    Ix: IndexType,    Ty: EdgeType, `[src]

Convert a `StableGraph` into a `Graph`

Computes in O(|V| + |E|) time.

This translates the stable graph into a graph with node and edge indices in a compact interval without holes (like `Graph`s always are).

Only if the stable graph had no vacancies after deletions (if node bound was equal to node count, and the same for edges), would the resulting graph have the same node and edge indices as the input.

### `impl<N, E, Ty, Ix> GetAdjacencyMatrix for Graph<N, E, Ty, Ix> where    Ix: IndexType,    Ty: EdgeType, `[src]

The adjacency matrix for Graph is a bitmap that's computed by `.adjacency_matrix()`.

node identifier

edge identifier

### `impl<N, E, Ty, Ix> GraphProp for Graph<N, E, Ty, Ix> where    Ix: IndexType,    Ty: EdgeType, `[src]

#### `type EdgeType = Ty`

The kind edges in the graph.

### `impl<N, E, Ty, Ix> Index<EdgeIndex<Ix>> for Graph<N, E, Ty, Ix> where    Ix: IndexType,    Ty: EdgeType, `[src]

Index the `Graph` by `EdgeIndex` to access edge weights.

Panics if the edge doesn't exist.

#### `type Output = E`

The returned type after indexing.

### `impl<N, E, Ty, Ix> Index<NodeIndex<Ix>> for Graph<N, E, Ty, Ix> where    Ix: IndexType,    Ty: EdgeType, `[src]

Index the `Graph` by `NodeIndex` to access node weights.

Panics if the node doesn't exist.

#### `type Output = N`

The returned type after indexing.

### `impl<N, E, Ty, Ix> IndexMut<EdgeIndex<Ix>> for Graph<N, E, Ty, Ix> where    Ix: IndexType,    Ty: EdgeType, `[src]

Index the `Graph` by `EdgeIndex` to access edge weights.

Panics if the edge doesn't exist.

### `impl<N, E, Ty, Ix> IndexMut<NodeIndex<Ix>> for Graph<N, E, Ty, Ix> where    Ix: IndexType,    Ty: EdgeType, `[src]

Index the `Graph` by `NodeIndex` to access node weights.

Panics if the node doesn't exist.

### `impl<N, E, Ty, Ix> Visitable for Graph<N, E, Ty, Ix> where    Ix: IndexType,    Ty: EdgeType, `[src]

#### `type Map = FixedBitSet`

The associated map type

## Blanket Implementations

### `impl<T> ToOwned for T where    T: Clone, `[src]

#### `type Owned = T`

The resulting type after obtaining ownership.

### `impl<T, U> TryFrom<U> for T where    U: Into<T>, `[src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

### `impl<T, U> TryInto<U> for T where    U: TryFrom<T>, `[src]

#### `type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.