Added uninitialized memory optimization

- When the unsafe_optimizations flag is toggled on uninitialized memory is
  allocated to avoid zeroing the array of AABBs for all the boxes, this
  improves performance when building an index

Author: jbuckmccready

CHANGELOG.md

@@ -13,6 +13,10 @@ All notable changes to the static_aabb2d_index crate will be documented in this
   1_000_000 items).
 - Avoid some allocations when building an index by determining the exact length of the
   `level_bounds` array before constructing it (performance improvement).
+- Added uninitialized memory optimization when the feature flag `unsafe_optimizations` is on. This
+  further improves performance when building an index by avoiding zeroing the array of AABBs
+  allocated for the all the boxes. Care was taken to avoid undefined behavior due to reading from or
+  creating references to any uninitialized memory.
 
 ## 1.0.0 - 2023-03-02
 

README.md

@@ -7,7 +7,10 @@ spatial ordering. This is a rust port of the excellent
 [flatbush](https://github.com/mourner/flatbush) javascript library.
 
 By default no unsafe code is used (`#![forbid(unsafe_code)]` is applied). Some unsafe optimizations
-can be enabled by toggling on the `unsafe_optimizations` flag.
+can be enabled by toggling on the `unsafe_optimizations` flag. Note the API is still safe when this
+flag is enabled, all optimizations are internal to the library. Currently the unsafe code is used
+to eliminate slice bounds checking and utilize uninitialized memory to avoid zeroing arrays when
+allocated.
 
 ## Quick Links
 

src/static_aabb2d_index.rs

@@ -47,15 +47,11 @@ where
     node_size: usize,
     num_items: usize,
     level_bounds: Box<[usize]>,
-    /// boxes holds the tree data (all nodes and items)
     #[cfg(feature = "unsafe_optimizations")]
     boxes: Box<[std::mem::MaybeUninit<AABB<T>>]>,
     #[cfg(not(feature = "unsafe_optimizations"))]
     boxes: Box<[AABB<T>]>,
-    /// indices is used to map from sorted indices to indices ordered according to the order items
-    /// were added
     indices: Box<[usize]>,
-    // used to keep track of the current position for boxes added
     pos: usize,
 }
 
@@ -106,14 +102,14 @@ where
     node_size: usize,
     num_items: usize,
     level_bounds: Box<[usize]>,
-    /// boxes holds the tree data (all nodes and items)
     boxes: Box<[AABB<T>]>,
-    /// indices is used to map from sorted indices to indices ordered according to the order items
-    /// were added
     indices: Box<[usize]>,
 }
 
-// get_at_index and set_at_index helper functions to toggle bounds checking at compile time
+// Helper functions to toggle bounds checking/uninitialized memory handling. NOTE: the functions are
+// not marked unsafe to facilitate easy global usages since we never rely on these functions
+// throwing a panic (so with unsafe_optimizations feature on we assume correct bounds and
+// initialization).
 #[cfg(not(feature = "unsafe_optimizations"))]
 #[inline(always)]
 fn get_at_index<T>(container: &[T], index: usize) -> &T {
@@ -315,6 +311,7 @@ where
         }
 
         #[cfg(feature = "unsafe_optimizations")]
+        // SAFETY: All the item boxes are initialized (all elements from index 0 to num_items - 1).
         let item_boxes: &mut [AABB<T>] =
             unsafe { std::mem::transmute(&mut self.boxes[0..self.num_items]) };
 
@@ -350,8 +347,12 @@ where
             );
 
             #[cfg(feature = "unsafe_optimizations")]
+            // SAFETY: All boxes are initialized.
             let boxes: Box<[AABB<T>]> = unsafe { std::mem::transmute(self.boxes) };
 
+            #[cfg(not(feature = "unsafe_optimizations"))]
+            let boxes = self.boxes;
+
             return Ok(StaticAABB2DIndex {
                 node_size: self.node_size,
                 num_items: self.num_items,
@@ -441,8 +442,12 @@ where
         }
 
         #[cfg(feature = "unsafe_optimizations")]
+        // SAFETY: All boxes are initialized.
         let boxes: Box<[AABB<T>]> = unsafe { std::mem::transmute(self.boxes) };
 
+        #[cfg(not(feature = "unsafe_optimizations"))]
+        let boxes = self.boxes;
+
         Ok(StaticAABB2DIndex {
             node_size: self.node_size,
             num_items: self.num_items,