Add Incidence struct for GraphTopology to use

src/traits.rs

@@ -4,7 +4,6 @@ use crate::maps::EntityMap;
 
 // TODO: Add functions to reserve memory for vertices and edges.
 // TODO: Split out GraphTopologyAddition trait.
-// TODO: Introduce an Incidence struct.
 /// A trait representing an undirected graph topology.
 ///
 /// An undirected graph is a set of vertices and undirected edges, where each edge connects either
@@ -165,7 +164,10 @@ pub trait GraphTopology {
     /// # Panics
     ///
     /// Panics if `v` is not a valid vertex of this graph.
-    fn incidences(&self, v: Self::Vertex) -> impl Iterator<Item = (Self::Vertex, Self::Edge)>;
+    fn incidences(
+        &self,
+        v: Self::Vertex,
+    ) -> impl Iterator<Item = Incidence<Self::Vertex, Self::Edge>>;
 
     /// Returns a cursor over all incidences of `v`, analogously to
     /// [`incidences`](Self::incidences), initially positioned before the first one.
@@ -221,8 +223,8 @@ pub trait GraphTopologyDeletion: GraphTopology {
 /// [`GraphTopology::IncidenceCursor`] for guidance on when to prefer a cursor over
 /// [`GraphTopology::incidences`].
 pub trait IncidenceCursor<G: GraphTopology + ?Sized>: Copy {
-    /// Advances the cursor and returns the next incidence as `Some((u, e))`, or `None` if the
-    /// traversal is exhausted.
+    /// Advances the cursor and returns the next incidence, or `None` if the traversal is
+    /// exhausted.
     ///
     /// # Examples
     ///
@@ -248,5 +250,17 @@ pub trait IncidenceCursor<G: GraphTopology + ?Sized>: Copy {
     /// assert!(c2.next(&graph).is_some());
     /// assert!(c2.next(&graph).is_none());
     /// ```
-    fn next(&mut self, graph: &G) -> Option<(G::Vertex, G::Edge)>;
+    fn next(&mut self, graph: &G) -> Option<Incidence<G::Vertex, G::Edge>>;
+}
+
+/// An incidence of some vertex *v* in a graph, i.e. a vertex-edge pair *(u, e)* such that *u* is
+/// adjacent to *v* and *e* is an edge between them.
+///
+/// Return type of [`GraphTopology::incidences`] and [`IncidenceCursor::next`].
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+pub struct Incidence<V, E> {
+    /// The vertex adjacent to *v*.
+    pub vertex: V,
+    /// The edge between *v* and [`vertex`](Self::vertex).
+    pub edge: E,
 }