First approach for bevy_graph

benches/Cargo.toml

@@ -13,6 +13,7 @@ rand_chacha = "0.3"
 criterion = { version = "0.3", features = ["html_reports"] }
 bevy_app = { path = "../crates/bevy_app" }
 bevy_ecs = { path = "../crates/bevy_ecs", features = ["multi-threaded"] }
+bevy_graph = { path = "../crates/bevy_graph" }
 bevy_reflect = { path = "../crates/bevy_reflect" }
 bevy_tasks = { path = "../crates/bevy_tasks" }
 bevy_utils = { path = "../crates/bevy_utils" }

crates/bevy_graph/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "bevy_graph"
+version = "0.9.0"
+edition = "2021"
+description = "Graph data structures, as used by the Bevy game engine"
+homepage = "https://bevyengine.org"
+repository = "https://github.com/bevyengine/bevy"
+license = "MIT OR Apache-2.0"
+keywords = ["bevy"]
+
+[dependencies]
+hashbrown = "0.13.1"
+slotmap = "1.0.6"
+thiserror = "1.0.38"

crates/bevy_graph/src/algos/bfs.rs

@@ -0,0 +1,151 @@
+use std::{collections::VecDeque, marker::PhantomData};
+
+use hashbrown::HashSet;
+
+use crate::{
+    graphs::{edge::EdgeRef, keys::NodeIdx, Graph},
+    iters,
+};
+
+/// Implementation of the [`BFS` algorithm](https://www.geeksforgeeks.org/breadth-first-search-or-bfs-for-a-graph/)
+///
+/// when `d` is the distance between a node and the startnode,
+/// it will evaluate every node with `d=1`, then continue with `d=2` and so on.
+pub struct BreadthFirstSearch<'g, N, E: 'g, G: Graph<N, E>, I: Iterator<Item = EdgeRef<'g, E>>> {
+    graph: &'g G,
+    queue: VecDeque<NodeIdx>,
+    visited: HashSet<NodeIdx>,
+    visitor: fn(&'g G, NodeIdx) -> I,
+    phantom: PhantomData<(N, E)>,
+}
+
+impl<'g, N, E: 'g, G: Graph<N, E>, I: Iterator<Item = EdgeRef<'g, E>>>
+    BreadthFirstSearch<'g, N, E, G, I>
+{
+    /// Creates a new `BreadthFirstSearch` with a start node and a custom visitor
+    pub fn custom(graph: &'g G, start: NodeIdx, visitor: fn(&'g G, NodeIdx) -> I) -> Self {
+        let node_count = graph.node_count();
+        let mut queue = VecDeque::with_capacity(node_count);
+        let mut visited = HashSet::with_capacity(node_count);
+
+        visited.insert(start);
+        queue.push_back(start);
+
+        Self {
+            graph,
+            queue,
+            visited,
+            visitor,
+            phantom: PhantomData,
+        }
+    }
+
+    /// Creates a new `BreadthFirstSearch` with a start node and a custom visitor wrapped inside an `NodesByIdx` iterator
+    #[inline]
+    pub fn custom_ref(
+        graph: &'g G,
+        start: NodeIdx,
+        visitor: fn(&'g G, NodeIdx) -> I,
+    ) -> iters::NodesByIdx<'g, N, NodeIdx, Self> {
+        let inner = Self::custom(graph, start, visitor);
+        iters::NodesByIdx::from_graph(inner, graph)
+    }
+
+    /// Creates a new `BreadthFirstSearch` with a start node and a custom visitor wrapped inside an `NodesByIdxMut` iterator
+    #[inline]
+    pub fn custom_mut(
+        graph: &'g mut G,
+        start: NodeIdx,
+        visitor: fn(&'g G, NodeIdx) -> I,
+    ) -> iters::NodesByIdxMut<'g, N, NodeIdx, Self> {
+        unsafe {
+            // SAFETY: `BreadthFirstSearch` assueres that every node gets visited only once
+            let ptr: *mut G = &mut *graph;
+            let inner = Self::custom(&*ptr, start, visitor);
+
+            iters::NodesByIdxMut::from_graph(inner, graph)
+        }
+    }
+}
+
+impl<'g, N, E: 'g, G: Graph<N, E>> BreadthFirstSearch<'g, N, E, G, G::OutgoingEdgesOf<'g>> {
+    /// Creates a new `BreadthFirstSearch` with a start node and the default visitor of `outgoing`
+    #[inline]
+    pub fn new(graph: &'g G, start: NodeIdx) -> Self {
+        Self::custom(graph, start, |graph, index| graph.outgoing_edges_of(index))
+    }
+
+    /// Creates a new `BreadthFirstSearch` with a start node and the default visitor of `outgoing` wrapped inside an `NodesByIdx` iterator
+    #[inline]
+    pub fn new_ref(graph: &'g G, start: NodeIdx) -> iters::NodesByIdx<'g, N, NodeIdx, Self> {
+        let inner = Self::new(graph, start);
+        iters::NodesByIdx::from_graph(inner, graph)
+    }
+
+    /// Creates a new `BreadthFirstSearch` with a start node and the default visitor of `outgoing` wrapped inside an `NodesByIdxMut` iterator
+    #[inline]
+    pub fn new_mut(graph: &'g mut G, start: NodeIdx) -> iters::NodesByIdxMut<'g, N, NodeIdx, Self> {
+        unsafe {
+            // SAFETY: `BreadthFirstSearch` assueres that every node gets visited only once
+            let ptr: *mut G = &mut *graph;
+            let inner = Self::new(&*ptr, start);
+
+            iters::NodesByIdxMut::from_graph(inner, graph)
+        }
+    }
+}
+
+impl<'g, N, E: 'g, G: Graph<N, E>, I: Iterator<Item = EdgeRef<'g, E>>> Iterator
+    for BreadthFirstSearch<'g, N, E, G, I>
+{
+    type Item = NodeIdx;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        if let Some(node) = self.queue.pop_front() {
+            for EdgeRef(_, dst, _) in (self.visitor)(self.graph, node) {
+                if !self.visited.contains(&dst) {
+                    self.visited.insert(dst);
+                    self.queue.push_back(dst);
+                }
+            }
+            Some(node)
+        } else {
+            None
+        }
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use crate::{
+        algos::bfs::BreadthFirstSearch,
+        graphs::{map::SimpleMapGraph, Graph},
+    };
+
+    #[test]
+    fn basic_imperative_bfs() {
+        let mut graph = SimpleMapGraph::<i32, (), true>::new();
+
+        let zero = graph.add_node(0);
+        let one = graph.add_node(1);
+        let two = graph.add_node(2);
+        let three = graph.add_node(3);
+
+        graph.add_edge(zero, one, ());
+        graph.add_edge(zero, two, ());
+        graph.add_edge(one, two, ());
+        graph.add_edge(two, zero, ());
+        graph.add_edge(two, three, ());
+
+        let elements = vec![0, 2, 1, 3];
+
+        let mut counted_elements = Vec::with_capacity(4);
+
+        let bfs = BreadthFirstSearch::new_ref(&graph, zero);
+        for node in bfs {
+            counted_elements.push(*node);
+        }
+
+        assert_eq!(elements, counted_elements);
+    }
+}

crates/bevy_graph/src/algos/dfs.rs

@@ -0,0 +1,148 @@
+use std::marker::PhantomData;
+
+use hashbrown::HashSet;
+
+use crate::{
+    graphs::{edge::EdgeRef, keys::NodeIdx, Graph},
+    iters,
+};
+
+/// Implementation of the [`DFS` algorithm](https://www.geeksforgeeks.org/depth-first-search-or-dfs-for-a-graph/)
+///
+/// it will evaluate every node from the start as deep as it can and then continue at the next sibling node from the top.
+pub struct DepthFirstSearch<'g, N, E: 'g, G: Graph<N, E>, I: Iterator<Item = EdgeRef<'g, E>>> {
+    graph: &'g G,
+    stack: Vec<NodeIdx>,
+    visited: HashSet<NodeIdx>,
+    visitor: fn(&'g G, NodeIdx) -> I,
+    phantom: PhantomData<(N, E)>,
+}
+
+impl<'g, N, E: 'g, G: Graph<N, E>, I: Iterator<Item = EdgeRef<'g, E>>>
+    DepthFirstSearch<'g, N, E, G, I>
+{
+    /// Creates a new `DepthFirstSearch` with a start node and a custom visitor
+    pub fn custom(graph: &'g G, start: NodeIdx, visitor: fn(&'g G, NodeIdx) -> I) -> Self {
+        let node_count = graph.node_count();
+        let mut stack = Vec::with_capacity(node_count);
+        let mut visited = HashSet::with_capacity(node_count);
+
+        visited.insert(start);
+        stack.push(start);
+
+        Self {
+            graph,
+            stack,
+            visited,
+            visitor,
+            phantom: PhantomData,
+        }
+    }
+
+    /// Creates a new `DepthFirstSearch` with a start node and a custom visitor wrapped inside an `NodesByIdx` iterator
+    #[inline]
+    pub fn custom_ref(
+        graph: &'g G,
+        start: NodeIdx,
+        visitor: fn(&'g G, NodeIdx) -> I,
+    ) -> iters::NodesByIdx<'g, N, NodeIdx, Self> {
+        let inner = Self::custom(graph, start, visitor);
+        iters::NodesByIdx::from_graph(inner, graph)
+    }
+
+    /// Creates a new `DepthFirstSearch` with a start node and a custom visitor wrapped inside an `NodesByIdxMut` iterator
+    #[inline]
+    pub fn custom_mut(
+        graph: &'g mut G,
+        start: NodeIdx,
+        visitor: fn(&'g G, NodeIdx) -> I,
+    ) -> iters::NodesByIdxMut<'g, N, NodeIdx, Self> {
+        unsafe {
+            // SAFETY: `DepthFirstSearch` assueres that every node gets visited only once
+            let ptr: *mut G = &mut *graph;
+            let inner = Self::custom(&*ptr, start, visitor);
+
+            iters::NodesByIdxMut::from_graph(inner, graph)
+        }
+    }
+}
+
+impl<'g, N, E: 'g, G: Graph<N, E>> DepthFirstSearch<'g, N, E, G, G::OutgoingEdgesOf<'g>> {
+    /// Creates a new `DepthFirstSearch` with a start node and the default visitor of `outgoing`
+    #[inline]
+    pub fn new(graph: &'g G, start: NodeIdx) -> Self {
+        Self::custom(graph, start, |graph, index| graph.outgoing_edges_of(index))
+    }
+
+    /// Creates a new `DepthFirstSearch` with a start node and the default visitor of `outgoing` wrapped inside an `NodesByIdx` iterator
+    pub fn new_ref(graph: &'g G, start: NodeIdx) -> iters::NodesByIdx<'g, N, NodeIdx, Self> {
+        let inner = Self::new(graph, start);
+        iters::NodesByIdx::from_graph(inner, graph)
+    }
+
+    /// Creates a new `DepthFirstSearch` with a start node and the default visitor of `outgoing` wrapped inside an `NodesByIdxMut` iterator
+    pub fn new_mut(graph: &'g mut G, start: NodeIdx) -> iters::NodesByIdxMut<'g, N, NodeIdx, Self> {
+        unsafe {
+            // SAFETY: `DepthFirstSearch` assueres that every node gets visited only once
+            let ptr: *mut G = &mut *graph;
+            let inner = Self::new(&*ptr, start);
+
+            iters::NodesByIdxMut::from_graph(inner, graph)
+        }
+    }
+}
+
+impl<'g, N, E: 'g, G: Graph<N, E>, I: Iterator<Item = EdgeRef<'g, E>>> Iterator
+    for DepthFirstSearch<'g, N, E, G, I>
+{
+    type Item = NodeIdx;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        if let Some(node) = self.stack.pop() {
+            for EdgeRef(_, dst, _) in (self.visitor)(self.graph, node) {
+                if !self.visited.contains(&dst) {
+                    self.visited.insert(dst);
+                    self.stack.push(dst);
+                }
+            }
+            Some(node)
+        } else {
+            None
+        }
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use crate::{
+        algos::dfs::DepthFirstSearch,
+        graphs::{map::SimpleMapGraph, Graph},
+    };
+
+    #[test]
+    fn basic_imperative_dfs() {
+        let mut graph = SimpleMapGraph::<i32, (), true>::new();
+
+        let zero = graph.add_node(0);
+        let one = graph.add_node(1);
+        let two = graph.add_node(2);
+        let three = graph.add_node(3);
+
+        graph.add_edge(zero, one, ());
+        graph.add_edge(zero, two, ());
+        graph.add_edge(one, two, ());
+        graph.add_edge(two, zero, ());
+        graph.add_edge(two, three, ());
+
+        let elements = vec![0, 1, 2, 3];
+
+        let mut counted_elements = Vec::with_capacity(4);
+
+        let dfs = DepthFirstSearch::new_ref(&graph, zero);
+        for node in dfs {
+            counted_elements.push(*node);
+        }
+
+        assert_eq!(elements, counted_elements);
+    }
+}

crates/bevy_graph/src/algos/mod.rs

@@ -0,0 +1,4 @@
+/// Implementation of the [`BFS` algorythm](https://www.geeksforgeeks.org/breadth-first-search-or-bfs-for-a-graph/)
+pub mod bfs;
+/// Implementation of the [`DFS` algorythm](https://www.geeksforgeeks.org/depth-first-search-or-dfs-for-a-graph/)
+pub mod dfs;

crates/bevy_graph/src/error.rs

@@ -0,0 +1,17 @@
+use thiserror::Error;
+
+use crate::graphs::keys::NodeIdx;
+
+/// An error that can occur when traversing or manipulating a graph data structure
+#[derive(Debug, Error)]
+pub enum GraphError {
+    /// the given `NodeIdx` is not preset in the graph
+    #[error("the given `{0:?}` isn't preset in the graph")]
+    NodeNotFound(NodeIdx),
+    /// there is already an edge between those nodes (not allowed in `SimpleGraph`)
+    #[error("there is already an edge between those nodes (not allowed in `SimpleGraph`)")]
+    Loop,
+    /// the `src` and `dst` nodes are equal, the edge would be a loop (not allowed in `SimpleGraph`)
+    #[error("the `src` and `dst` nodes are equal, the edge would be a loop (not allowed in `SimpleGraph`)")]
+    ContainsEdgeBetween,
+}