Add GraphTopologyAddition trait from GraphTopology

Move capacity and add methods from GraphTopology trait to new GraphTopologyAddition trait

src/traits.rs

@@ -2,13 +2,11 @@
 
 use crate::maps::EntityMap;
 
-// TODO: Add functions to reserve memory for vertices and edges.
-// TODO: Split out GraphTopologyAddition trait.
 /// A trait representing an undirected graph topology.
 ///
 /// An undirected graph is a set of vertices and undirected edges, where each edge connects either
 /// exactly two vertices or one vertex with itself (loop edge). This trait provides methods for
-/// querying a graph topology, iterating over vertices and edges, and adding new vertices and edges.
+/// querying a graph topology, and iterating over vertices and edges.
 ///
 /// # Vertices and edges
 ///
@@ -20,9 +18,10 @@ use crate::maps::EntityMap;
 /// Methods accepting vertices or edges as parameters panic if the handle was invalidated by a
 /// deletion, and return incorrect results if the handle was not produced by this graph instance.
 ///
-/// # Deletion
+/// # Addition and deletion
 ///
-/// This trait covers graph construction and querying only. To delete vertices and edges, see
+/// This trait covers graph querying only. To construct a graph incrementally by adding vertices and
+/// edges, see [`GraphTopologyAddition`]. To delete vertices and edges, see
 /// [`GraphTopologyDeletion`].
 ///
 /// [`Edge`]: GraphTopology::Edge
@@ -45,9 +44,6 @@ pub trait GraphTopology {
     /// Returns the number of vertices in the graph.
     fn vertex_count(&self) -> usize;
 
-    /// Returns the total number of vertices the graph can hold without reallocating.
-    fn vertex_capacity(&self) -> usize;
-
     /// Creates and returns an [`EntityMap`] for the vertices with every slot initialised to
     /// `default`.
     ///
@@ -74,9 +70,6 @@ pub trait GraphTopology {
     /// Returns the number of edges in the graph.
     fn edge_count(&self) -> usize;
 
-    /// Returns the total number of edges the graph can hold without reallocating.
-    fn edge_capacity(&self) -> usize;
-
     /// Creates and returns an [`EntityMap`] for the edges with every slot initialised to `default`.
     ///
     /// # Examples
@@ -179,6 +172,19 @@ pub trait GraphTopology {
     ///
     /// Panics if `v` is not a valid vertex of this graph.
     fn incidence_cursor(&self, v: Self::Vertex) -> Self::IncidenceCursor;
+}
+
+// TODO: Add functions to reserve memory for vertices and edges.
+/// A trait that adds construction operations to an undirected graph topology.
+///
+/// This trait provides methods for addition of vertices and edges, and capacity management in an
+/// undirected graph.
+pub trait GraphTopologyAddition: GraphTopology {
+    /// Returns the total number of vertices the graph can hold without reallocating.
+    fn vertex_capacity(&self) -> usize;
+
+    /// Returns the total number of edges the graph can hold without reallocating.
+    fn edge_capacity(&self) -> usize;
 
     /// Adds a new isolated vertex and returns its handle.
     fn add_vertex(&mut self) -> Self::Vertex;