Replace VertexMap and EdgeMap with now public EntityMap

src/maps.rs

@@ -1,84 +1,32 @@
+//! Provides maps to associate custom data to graph vertices and edges.
+//!
+//! [`EntityMap`] provides a copy-on-write, [`Vec`]-backed map to associate data to either all
+//! vertices or all edges in a graph.
+
 use std::ops::{Index, IndexMut};
 
-use crate::traits::GraphTopology;
-
-pub struct VertexMap<V: Copy, T: Clone> {
-    inner: EntityMap<V, T>,
-}
-
-impl<V: Copy, T: Clone> VertexMap<V, T> {
-    pub fn new(default: T, to_index: fn(V) -> usize, capacity: usize) -> Self {
-        Self {
-            inner: EntityMap::new(default, to_index, capacity),
-        }
-    }
-
-    // Reads beyond 'capacity' are valid and return the default value.
-    pub fn capacity(&self) -> usize {
-        self.inner.capacity()
-    }
-
-    pub fn sync<G: GraphTopology<Vertex = V>>(&mut self, graph: &G) {
-        self.inner.resize(graph.vertex_capacity());
-    }
-}
-
-impl<V: Copy, T: Clone> Index<V> for VertexMap<V, T> {
-    type Output = T;
-
-    fn index(&self, v: V) -> &T {
-        &self.inner[v]
-    }
-}
-
-impl<V: Copy, T: Clone> IndexMut<V> for VertexMap<V, T> {
-    fn index_mut(&mut self, v: V) -> &mut T {
-        &mut self.inner[v]
-    }
-}
-
-pub struct EdgeMap<E: Copy, T: Clone> {
-    inner: EntityMap<E, T>,
-}
-
-impl<E: Copy, T: Clone> EdgeMap<E, T> {
-    pub fn new(default: T, to_index: fn(E) -> usize, capacity: usize) -> Self {
-        Self {
-            inner: EntityMap::new(default, to_index, capacity),
-        }
-    }
-
-    // Reads beyond 'capacity' are valid and return the default value.
-    pub fn capacity(&self) -> usize {
-        self.inner.capacity()
-    }
-
-    pub fn sync<G: GraphTopology<Edge = E>>(&mut self, graph: &G) {
-        self.inner.resize(graph.edge_capacity());
-    }
-}
-
-impl<E: Copy, T: Clone> Index<E> for EdgeMap<E, T> {
-    type Output = T;
-
-    fn index(&self, e: E) -> &T {
-        &self.inner[e]
-    }
-}
-
-impl<E: Copy, T: Clone> IndexMut<E> for EdgeMap<E, T> {
-    fn index_mut(&mut self, e: E) -> &mut T {
-        &mut self.inner[e]
-    }
-}
-
-struct EntityMap<E: Copy, T: Clone> {
+/// A map to associate custom data to graph vertices or edges.
+///
+/// This map uses raw entity indices to associate homogenous custom data of type `T` to graph
+/// vertices or edges. The implementation uses a [`Vec`], allocating contiguous slots for the data,
+/// which means that the provided index conversion function should map entities to contiguous
+/// indices, or indices with relatively few gaps.
+///
+/// Data allocation happens as copy-on-write, i.e. the backing [`Vec`] is only resized if a value
+/// beyond current capacity is written, but the `default` value can transparently be read. No bound
+/// or validity checks are performed by the map on the provided entities.
+///
+/// Use [`GraphTopology::vertex_map`] or [`GraphTopology::edge_map`] to obtain an `EntityMap` for
+/// vertices or edges, respectively.
+pub struct EntityMap<E: Copy, T: Clone> {
     data: Vec<T>,
     default: T,
     to_index: fn(E) -> usize,
 }
 
 impl<E: Copy, T: Clone> EntityMap<E, T> {
+    /// Creates a new map with the given `default` value, an index conversion function `to_index`,
+    /// and an initial `capacity`.
     pub fn new(default: T, to_index: fn(E) -> usize, capacity: usize) -> Self {
         Self {
             data: vec![default.clone(); capacity],
@@ -87,11 +35,18 @@ impl<E: Copy, T: Clone> EntityMap<E, T> {
         }
     }
 
+    /// Returns the total number of data entries the map can write without reallocating. Reads
+    /// beyond `capacity` are valid and return the default value.
     pub fn capacity(&self) -> usize {
-        self.data.len()
+        self.data.capacity()
     }
 
-    pub fn resize(&mut self, capacity: usize) {
+    /// Extends the internal data storage of the map to `capacity`, pre-filling any new slots with
+    /// the default value.
+    ///
+    /// Use this before writing data for new graph entities to avoid incremental growth on the first
+    /// write to each new entity.
+    pub fn extend(&mut self, capacity: usize) {
         if capacity > self.data.len() {
             self.data.resize(capacity, self.default.clone());
         }