updated docs

added `save_spare`
removed `set_len`
updated unsized storages

Author: RustyYato

src/lib.rs

@@ -160,13 +160,15 @@ use core::{
 mod extension;
 mod impls;
 mod slice;
-// mod set_len;
 
 pub mod iter;
 pub mod raw;
 
 use raw::Storage;
 
+#[doc(hidden)]
+pub use core;
+
 /// A heap backed vector with a growable capacity
 #[cfg(any(doc, feature = "alloc"))]
 #[cfg(feature = "nightly")]
@@ -181,7 +183,7 @@ pub type HeapVec<T> = GenericVec<T, raw::Heap<T>>;
 #[cfg(any(doc, feature = "nightly"))]
 pub type ArrayVec<T, const N: usize> = TypeVec<T, [T; N]>;
 /// An slice backed vector backed by potentially uninitialized memory
-pub type SliceVec<'a, T> = GenericVec<T, raw::UninitSlice<'a, T>>;
+pub type SliceVec<'a, T> = GenericVec<T, &'a mut raw::UninitSlice<T>>;
 
 /// An array backed vector backed by initialized memory
 #[cfg(any(doc, feature = "nightly"))]
@@ -286,6 +288,37 @@ macro_rules! uninit_array {
     };
 }
 
+/// Save the changes to [`GenericVec::spare_capacity_mut`]
+///
+/// $orig - a mutable reference to a [`GenericVec`]
+/// $spare - the [`SliceVec`] that was obtained from [`$orig.spare_capacity_mut()`]
+///
+/// # Safety
+///
+/// `$spare` should be the [`SliceVec`] returned by `$orig.spare_capacity_mut()`
+#[macro_export]
+macro_rules! save_spare {
+    ($spare:expr, $orig:expr) => {{
+        let spare: $crate::SliceVec<_> = $spare;
+        let spare = $crate::core::mem::ManuallyDrop::new(spare);
+        let len = spare.len();
+        let ptr = spare.as_ptr();
+        let orig: &mut $crate::GenericVec<_, _> = $orig;
+        $crate::validate_spare(ptr, orig);
+        let len = len + orig.len();
+        $orig.set_len_unchecked(len);
+    }};
+}
+
+#[doc(hidden)]
+pub fn validate_spare<T>(spare_ptr: *const T, orig: &[T]) {
+    debug_assert!(
+        unsafe { orig.as_ptr().add(orig.len()) == spare_ptr },
+        "Tried to use `save_spare!` with a `SliceVec` that was not obtained from `GenricVec::spare_capacity_mut`. \
+         This is undefined behavior on release mode!"
+    )
+}
+
 /// A vector type that can be backed up by a variety of different backends
 /// including slices, arrays, and the heap.
 #[repr(C)]
@@ -452,13 +485,13 @@ impl<T, A: std::alloc::AllocRef> HeapVec<T, A> {
 #[cfg(not(feature = "nightly"))]
 impl<'a, T> SliceVec<'a, T> {
     /// Create a new empty `SliceVec`
-    pub fn new(slice: &'a mut [MaybeUninit<T>]) -> Self { Self::with_storage(raw::UninitSlice::new(slice)) }
+    pub fn new(slice: &'a mut [MaybeUninit<T>]) -> Self { Self::with_storage(raw::UninitSlice::from_mut(slice)) }
 }
 
 #[cfg(feature = "nightly")]
 impl<'a, T> SliceVec<'a, T> {
     /// Create a new empty `SliceVec`
-    pub const fn new(slice: &'a mut [MaybeUninit<T>]) -> Self { Self::with_storage(raw::UninitSlice::new(slice)) }
+    pub const fn new(slice: &'a mut [MaybeUninit<T>]) -> Self { Self::with_storage(raw::UninitSlice::from_mut(slice)) }
 }
 
 impl<'a, T: Copy> InitSliceVec<'a, T> {
@@ -587,10 +620,28 @@ impl<T, S: ?Sized + Storage<T>> GenericVec<T, S> {
     pub unsafe fn storage_mut(&mut self) -> &mut S { &mut self.storage }
 
     /// Returns the remaining spare capacity of the vector as
-    /// a `SliceVec<'_, T>`.
+    /// a [`SliceVec<'_, T>`](SliceVec).
     ///
-    /// Keep in mind that the `SliceVec<'_, T>` will drop all elements
-    /// that you push into it!
+    /// Keep in mind that the [`SliceVec<'_, T>`](SliceVec) will drop all elements
+    /// that you push into it when it goes out of scope! If you want
+    /// these modifications to persist then you should use [`save_spare`]
+    /// to persist these writes.
+    ///
+    /// ```
+    /// let mut vec = generic_vec::TypeVec::<i32, [i32; 16]>::new();
+    ///
+    /// let mut spare = vec.spare_capacity_mut();
+    /// spare.push(0);
+    /// spare.push(2);
+    /// drop(spare);
+    /// assert_eq!(vec, []);
+    ///
+    /// let mut spare = vec.spare_capacity_mut();
+    /// spare.push(0);
+    /// spare.push(2);
+    /// unsafe { generic_vec::save_spare!(spare, &mut vec) }
+    /// assert_eq!(vec, [0, 2]);
+    /// ```
     pub fn spare_capacity_mut(&mut self) -> SliceVec<'_, T> {
         // Safety
         //
@@ -725,9 +776,7 @@ impl<T, S: ?Sized + Storage<T>> GenericVec<T, S> {
         }
 
         unsafe {
-            let writer = core::mem::ManuallyDrop::new(writer);
-            let len = writer.len() + self.len();
-            self.set_len_unchecked(len);
+            save_spare!(writer, self);
         }
     }
 
@@ -1601,7 +1650,7 @@ impl<T, S: ?Sized + Storage<T>> GenericVec<T, S> {
     ///
     /// When the iterator is dropped, all elements in the range are removed from
     /// the vector, even if the iterator was not fully consumed. If the iterator
-    /// is not dropped (with mem::forget for example), it is unspecified how many
+    /// is not dropped (with `mem::forget` for example), it is unspecified how many
     /// elements are removed.
     ///
     /// # Panic

src/raw/slice.rs

@@ -4,25 +4,22 @@ use core::mem::{align_of, size_of, MaybeUninit};
 
 /// An uninitialized slice storage
 #[repr(transparent)]
-pub struct UninitSlice<'a, T>(&'a mut [MaybeUninit<T>]);
+pub struct UninitSlice<T>([MaybeUninit<T>]);
 
-unsafe impl<T> Send for UninitSlice<'_, T> {}
-unsafe impl<T> Sync for UninitSlice<'_, T> {}
+unsafe impl<T> Send for UninitSlice<T> {}
+unsafe impl<T> Sync for UninitSlice<T> {}
 
 #[cfg(not(feature = "nightly"))]
-impl<'a, T> UninitSlice<'a, T> {
+impl<T> UninitSlice<T> {
     /// Create a new `UninitSlice` storage
-    pub fn new(buffer: &'a mut [MaybeUninit<T>]) -> Self { Self(buffer) }
-
-    /// Reborrow an `UninitSlice` storage
-    pub fn as_ref(&mut self) -> UninitSlice<'_, T> { UninitSlice(self.0) }
+    pub fn from_mut(buffer: &mut [MaybeUninit<T>]) -> &mut Self { unsafe { &mut *(buffer as *mut [_] as *mut Self) } }
 
     /// Get the backing value of the this `Uninit` storage
     ///
     /// # Safety
     ///
     /// You may not write uninitialized memory to this slice
-    pub unsafe fn into_inner(self) -> &'a mut [MaybeUninit<T>] { self.0 }
+    pub unsafe fn into_mut(&mut self) -> &mut [MaybeUninit<T>] { unsafe { &mut *(self as *mut Self as *mut [_]) } }
 }
 
 #[cfg(feature = "nightly")]
@@ -41,7 +38,7 @@ impl<'a, T> UninitSlice<'a, T> {
     pub const unsafe fn into_inner(self) -> &'a mut [MaybeUninit<T>] { self.0 }
 }
 
-unsafe impl<T, U> Storage<U> for UninitSlice<'_, T> {
+unsafe impl<T, U> Storage<U> for UninitSlice<T> {
     const IS_ALIGNED: bool = align_of::<T>() >= align_of::<U>();
 
     fn capacity(&self) -> usize { crate::raw::capacity(self.0.len(), size_of::<T>(), size_of::<U>()) }

src/raw/uninit.rs

@@ -1,3 +1,6 @@
+//! `UninitBuffer` represents some uninitialized memory
+//!
+
 use core::mem::{align_of, size_of, MaybeUninit};
 
 use super::{AllocError, Storage, StorageWithCapacity};
@@ -8,10 +11,29 @@ struct AlignedBuffer<T, A> {
     value: T,
 }
 
-/// An uninitialized storage
+/// An uninitialized storage. This storage can store values
+/// of any type that has an alignment smaller of equal to `T` or `A`.
+///
+/// `UninitBuffer` has a max capacity of
+/// `round_up(size_of::<T>(), align_::<A>()) / size_of::<Element>()`
+/// elements.
+///
+/// i.e. `UninitBuffer<[i32; 12]>` can store 12 `i32`s, but
+/// `UninitBuffer<[i32; 1], u64>` can store 2 `i32`s. Because `u64 is
+/// aligned to 8 bytes, so `round_up(4 bytes, 8 bytes) / 4 bytes == 2`
 ///
-/// This type is represented as, generally the second type parameter can only
-/// be used to align the storage
+/// You can query the capacity with [`UninitBuffer::capacity`]
+///
+/// ```rust
+/// # use generic_vec::raw::UninitBuffer;
+/// assert_eq!(UninitBuffer::<[i32; 12]>::capacity::<i32>(), 12);
+/// assert_eq!(UninitBuffer::<[i32; 1], u64>::capacity::<i32>(), 2);
+/// assert_eq!(UninitBuffer::<[i32; 1]>::capacity::<u64>(), 0);
+/// ```
+///
+/// ## In memory representation
+///
+/// This type is represented in memory as
 ///
 /// ```
 /// #[repr(C)]
@@ -21,12 +43,10 @@ struct AlignedBuffer<T, A> {
 /// }
 /// ```
 ///
-/// By default the alignment type is set to `u8`, so that it doesn't get in the way.
-/// But if you need a higher alignment, then you can change the second type.
-/// This allows you to do things like `UninitBuffer<[u8; 4], u32>` to get a
-/// 4 byte aligned buffer of 4 bytes or `UninitBuffer<[CustomType; 12], usize>` to
-/// get an array of `CustomType`, and guarantee it is pointer-aligned.
-#[repr(C)]
+/// The size of the buffer is determined by type paramter `T`, and
+/// the alignment is the maximum alignment of `T` and `A`. This means
+/// that `A` should be used to ensure a certain alignment.
+#[repr(transparent)]
 pub struct UninitBuffer<T, A = u8>(MaybeUninit<AlignedBuffer<T, A>>);
 
 unsafe impl<T, A> Send for UninitBuffer<T, A> {}
@@ -41,6 +61,9 @@ const fn size<U, T, A>() -> usize {
 }
 
 impl<T, A> UninitBuffer<T, A> {
+    /// Get the capacity of this buffer for a given element type
+    pub const fn capacity<U>() -> usize { size::<U, T, A>() }
+
     /// Create a new uninitialized array storage
     pub const fn uninit() -> Self { Self(MaybeUninit::uninit()) }