grow_to is implemented

Increases the capacity of the vector at least up to the `new_capacity`:
* has no affect if `new_capacity <= self.capacity()`, and returns `Ok(self.capacity())`;
* increases the capacity to `x >= new_capacity` otherwise if the operation succeeds.

This method is unsafe due to the internal guarantees of pinned vectors.
* A `SplitVec`, on the other hand, can grow to the `new_capacity` without any problem.
However, it is not designed to have intermediate empty fragments, while `grow_to` can leave such fragments.
Hence, the caller is responsible for handling this.

Author: Ugur-Arikan

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "orx-split-vec"
-version = "2.5.0"
+version = "2.6.0"
 edition = "2021"
 authors = ["orxfun <[email protected]>"]
 description = "An efficient constant access time vector with dynamic capacity and pinned elements."
@@ -10,7 +10,7 @@ keywords = ["vec", "array", "split", "fragments", "pinned"]
 categories = ["data-structures", "rust-patterns"]
 
 [dependencies]
-orx-pinned-vec = "2.4"
+orx-pinned-vec = "2.5"
 
 [[bench]]
 name = "serial_access"

src/pinned_vec.rs

@@ -575,6 +575,20 @@ where
             Ok(self.capacity())
         }
     }
+
+    unsafe fn grow_to(&mut self, new_capacity: usize) -> Result<usize, PinnedVecGrowthError> {
+        if new_capacity <= self.capacity() {
+            Ok(self.capacity())
+        } else {
+            let mut current_capacity = self.capacity();
+            while new_capacity > current_capacity {
+                let new_fragment_capacity = self.add_fragment_get_fragment_capacity();
+                current_capacity += new_fragment_capacity;
+            }
+            debug_assert_eq!(current_capacity, self.capacity());
+            Ok(current_capacity)
+        }
+    }
 }
 
 #[cfg(test)]
@@ -955,4 +969,48 @@ mod tests {
         }
         test_all_growth_types!(test);
     }
+
+    #[test]
+    fn grow_to_under_capacity() {
+        fn test<G: Growth>(mut vec: SplitVec<usize, G>) {
+            for _ in 0..10 {
+                assert_eq!(Ok(vec.capacity()), unsafe { vec.grow_to(0) });
+                assert_eq!(Ok(vec.capacity()), unsafe {
+                    vec.grow_to(vec.capacity() - 1)
+                });
+                assert_eq!(Ok(vec.capacity()), unsafe { vec.grow_to(vec.capacity()) });
+            }
+        }
+        test_all_growth_types!(test);
+    }
+
+    #[test]
+    fn grow_to() {
+        fn test<G: Growth>(mut vec: SplitVec<usize, G>) {
+            for _ in 0..10 {
+                let expected_capacity =
+                    vec.capacity() + vec.growth.new_fragment_capacity(vec.fragments());
+                let expected_num_fragments = vec.fragments().len() + 1;
+
+                assert_eq!(Ok(expected_capacity), unsafe {
+                    vec.grow_to(vec.capacity() + 1)
+                });
+
+                assert_eq!(vec.fragments().len(), expected_num_fragments);
+                assert_eq!(vec.capacity(), expected_capacity);
+            }
+
+            vec.clear();
+
+            for _ in 0..10 {
+                let prev_num_fragments = vec.fragments().len();
+
+                let new_capacity = unsafe { vec.grow_to(vec.capacity() + 1000) }.expect("is-okay");
+
+                assert!(vec.fragments().len() >= prev_num_fragments);
+                assert_eq!(vec.capacity(), new_capacity);
+            }
+        }
+        test_all_growth_types!(test);
+    }
 }

src/split_vec.rs

@@ -134,10 +134,17 @@ where
             .unwrap_or(false)
     }
 
+    /// Adds a new fragment to fragments of the split vector.
     pub(crate) fn add_fragment(&mut self) {
-        let capacity = self.growth.new_fragment_capacity(&self.fragments);
-        let new_fragment = Fragment::new(capacity);
+        self.add_fragment_get_fragment_capacity();
+    }
+
+    /// Adds a new fragment and return the capacity of the added (now last) fragment.
+    pub(crate) fn add_fragment_get_fragment_capacity(&mut self) -> usize {
+        let new_fragment_capacity = self.growth.new_fragment_capacity(&self.fragments);
+        let new_fragment = Fragment::new(new_fragment_capacity);
         self.fragments.push(new_fragment);
+        new_fragment_capacity
     }
 
     pub(crate) fn add_fragment_with_first_value(&mut self, first_value: T) {
@@ -225,4 +232,28 @@ mod tests {
         test(SplitVec::with_doubling_growth());
         test(SplitVec::with_linear_growth(6));
     }
+
+    #[test]
+    fn add_fragment() {
+        fn test<G: Growth>(mut vec: SplitVec<usize, G>) {
+            for _ in 0..10 {
+                let expected_new_fragment_cap = vec.growth.new_fragment_capacity(&vec.fragments);
+                let new_fragment_cap = vec.add_fragment_get_fragment_capacity();
+                assert_eq!(expected_new_fragment_cap, new_fragment_cap);
+            }
+
+            vec.clear();
+
+            let mut expected_capacity = vec.capacity();
+            for _ in 0..2 {
+                let expected_new_fragment_cap = vec.growth.new_fragment_capacity(&vec.fragments);
+                expected_capacity += expected_new_fragment_cap;
+                vec.add_fragment();
+            }
+
+            assert_eq!(expected_capacity, vec.capacity());
+        }
+
+        test_all_growth_types!(test);
+    }
 }