Struct GraphBuilder

pub struct GraphBuilder<State> { /* private fields */ }

A builder to create graphs in a type-safe way.

The builder implementation uses different states to allow staged building of graphs. Each individual state enables stage-specific methods on the builder.

Examples

Create a directed graph from a vec of edges:

use graph_builder::prelude::*;

let graph: DirectedCsrGraph<usize> = GraphBuilder::new()
    .edges(vec![(0, 1), (0, 2), (1, 2), (1, 3), (2, 3)])
    .build();

assert_eq!(graph.node_count(), 4);

Create an undirected graph from a vec of edges:

use graph_builder::prelude::*;

let graph: UndirectedCsrGraph<usize> = GraphBuilder::new()
    .edges(vec![(0, 1), (0, 2), (1, 2), (1, 3), (2, 3)])
    .build();

assert_eq!(graph.node_count(), 4);

Implementations

impl GraphBuilder<Uninitialized>

pub fn new() -> Self

Creates a new builder

pub fn csr_layout(self, csr_layout: CsrLayout) -> Self

Sets the CsrLayout to use during CSR construction.

Examples

Store the neighbors sorted:

use graph_builder::prelude::*;

let graph: UndirectedCsrGraph<usize> = GraphBuilder::new()
    .csr_layout(CsrLayout::Sorted)
    .edges(vec![(0, 7), (0, 3), (0, 3), (0, 1)])
    .build();

assert_eq!(graph.neighbors(0).copied().collect::<Vec<_>>(), &[1, 3, 3, 7]);

Store the neighbors sorted and deduplicated:

use graph_builder::prelude::*;

let graph: UndirectedCsrGraph<usize> = GraphBuilder::new()
    .csr_layout(CsrLayout::Deduplicated)
    .edges(vec![(0, 7), (0, 3), (0, 3), (0, 1)])
    .build();

assert_eq!(graph.neighbors(0).copied().collect::<Vec<_>>(), &[1, 3, 7]);

pub fn edges<NI, Edges>( self, edges: Edges, ) -> GraphBuilder<FromEdges<NI, Edges>>

where NI: Idx, Edges: IntoIterator<Item = (NI, NI)>,

Create a graph from the given edge tuples.

Example

use graph_builder::prelude::*;

let graph: DirectedCsrGraph<usize> = GraphBuilder::new()
    .edges(vec![(0, 1), (0, 2), (1, 2), (1, 3), (2, 3)])
    .build();

assert_eq!(graph.node_count(), 4);
assert_eq!(graph.edge_count(), 5);

pub fn edges_with_values<NI, Edges, EV>( self, edges: Edges, ) -> GraphBuilder<FromEdgesWithValues<NI, Edges, EV>>

where NI: Idx, Edges: IntoIterator<Item = (NI, NI, EV)>,

Create a graph from the given edge triplets.

Example

use graph_builder::prelude::*;

let graph: DirectedCsrGraph<usize, (), f32> = GraphBuilder::new()
    .edges_with_values(vec![(0, 1, 0.1), (0, 2, 0.2), (1, 2, 0.3), (1, 3, 0.4), (2, 3, 0.5)])
    .build();

assert_eq!(graph.node_count(), 4);
assert_eq!(graph.edge_count(), 5);

pub fn gdl_str<NI, S>(self, gdl: S) -> GraphBuilder<FromGdlString<NI>>

where NI: Idx, S: Into<String>,

Available on crate feature gdl only.

Creates a graph using Graph Definition Language (GDL).

Creating graphs from GDL is recommended for small graphs only, e.g., during testing. The graph construction is not parallelized.

See GDL on crates.io for more information on how to define graphs using GDL.

Example

use graph_builder::prelude::*;

let g: UndirectedCsrGraph<usize> = GraphBuilder::new()
    .gdl_str::<usize, _>("(a)-->(),(a)-->()")
    .build()
    .unwrap();

assert_eq!(g.node_count(), 3);
assert_eq!(g.edge_count(), 2);

One can also create weighted graphs using GDL. There needs to be exactly one edge property with the same type as specified for the edge value. The property key is not relevant.

use graph_builder::prelude::*;

let g: UndirectedCsrGraph<usize, (), f32> = GraphBuilder::new()
    .csr_layout(CsrLayout::Sorted)
    .gdl_str::<usize, _>("(a)-[{f: 0.42}]->(),(a)-[{f: 13.37}]->()")
    .build()
    .unwrap();

assert_eq!(g.node_count(), 3);
assert_eq!(g.edge_count(), 2);

let mut neighbors = g.neighbors_with_values(0);
assert_eq!(neighbors.next(), Some(&Target::new(1, 0.42)));
assert_eq!(neighbors.next(), Some(&Target::new(2, 13.37)));
assert_eq!(neighbors.next(), None);

pub fn gdl_graph<NI>( self, gdl_graph: &Graph, ) -> GraphBuilder<FromGdlGraph<'_, NI>>

where NI: Idx,

Available on crate feature gdl only.

Creates a graph from an already constructed GDL graph.

Creating graphs from GDL is recommended for small graphs only, e.g., during testing. The graph construction is not parallelized.

See GDL on crates.io for more information on how to define graphs using GDL.

Example

use graph_builder::prelude::*;

let gdl_graph = "(a)-->(),(a)-->()".parse::<::gdl::Graph>().unwrap();

let g: DirectedCsrGraph<usize> = GraphBuilder::new()
    .gdl_graph::<usize>(&gdl_graph)
    .build()
    .unwrap();

assert_eq!(g.node_count(), 3);
assert_eq!(g.edge_count(), 2);

let id_a = gdl_graph.get_node("a").unwrap().id();

assert_eq!(g.out_neighbors(id_a).len(), 2);

pub fn file_format<Format, Path, NI>( self, _format: Format, ) -> GraphBuilder<FromInput<NI, Path, Format>>

where Path: AsRef<StdPath>, NI: Idx, Format: InputCapabilities<NI>, Format::GraphInput: TryFrom<InputPath<Path>>,

Creates a graph by reading it from the given file format.

Examples

Read a directed graph from an edge list file:

use std::path::PathBuf;

use graph_builder::prelude::*;

let path = [env!("CARGO_MANIFEST_DIR"), "resources", "example.el"]
    .iter()
    .collect::<PathBuf>();

let graph: DirectedCsrGraph<usize> = GraphBuilder::new()
    .file_format(EdgeListInput::default())
    .path(path)
    .build()
    .expect("loading failed");

assert_eq!(graph.node_count(), 4);
assert_eq!(graph.edge_count(), 5);

impl<NI, Edges> GraphBuilder<FromEdges<NI, Edges>>

where NI: Idx, Edges: IntoIterator<Item = (NI, NI)>,

pub fn node_values<NV, I>( self, node_values: I, ) -> GraphBuilder<FromEdgeListAndNodeValues<NI, NV, ()>>

where I: IntoIterator<Item = NV>,

pub fn build<Graph>(self) -> Graph

where Graph: From<(EdgeList<NI, ()>, CsrLayout)>,

Build the graph from the given vec of edges.

impl<NI, Edges, EV> GraphBuilder<FromEdgesWithValues<NI, Edges, EV>>

where NI: Idx, EV: Sync, Edges: IntoIterator<Item = (NI, NI, EV)>,

pub fn node_values<NV, I>( self, node_values: I, ) -> GraphBuilder<FromEdgeListAndNodeValues<NI, NV, EV>>

where I: IntoIterator<Item = NV>,

pub fn build<Graph>(self) -> Graph

where Graph: From<(EdgeList<NI, EV>, CsrLayout)>,

Build the graph from the given vec of edges.

impl<NI: Idx, NV, EV> GraphBuilder<FromEdgeListAndNodeValues<NI, NV, EV>>

pub fn build<Graph>(self) -> Graph

where Graph: From<(NodeValues<NV>, EdgeList<NI, EV>, CsrLayout)>,

impl<NI> GraphBuilder<FromGdlString<NI>>

where NI: Idx,

pub fn build<Graph>(self) -> Result<Graph, Error>

where Graph: From<(Graph, CsrLayout)>,

Available on crate feature gdl only.

Builds the graph from the given GDL string.

impl<'a, NI> GraphBuilder<FromGdlGraph<'a, NI>>

where NI: Idx,

pub fn build<Graph>(self) -> Result<Graph, Error>

where Graph: From<(&'a Graph, CsrLayout)>,

Available on crate feature gdl only.

Build the graph from the given GDL graph.

impl<NI, Path, Format> GraphBuilder<FromInput<NI, Path, Format>>

where Path: AsRef<Path>, NI: Idx, Format: InputCapabilities<NI>, Format::GraphInput: TryFrom<InputPath<Path>>,

pub fn path(self, path: Path) -> GraphBuilder<FromPath<NI, Path, Format>>

Set the location where the graph is stored.

impl<NI, Path, Format> GraphBuilder<FromPath<NI, Path, Format>>

where Path: AsRef<Path>, NI: Idx, Format: InputCapabilities<NI>, Format::GraphInput: TryFrom<InputPath<Path>>, Error: From<<Format::GraphInput as TryFrom<InputPath<Path>>>::Error>,

pub fn build<Graph>(self) -> Result<Graph, Error>

where Graph: TryFrom<(Format::GraphInput, CsrLayout)>, Error: From<Graph::Error>,

Build the graph from the given input format and path.

Trait Implementations

impl Default for GraphBuilder<Uninitialized>

fn default() -> Self

Returns the “default value” for a type.