Polish for release

Author: GnomedDev

Cargo.toml

@@ -1,9 +1,10 @@
 [package]
 name = "small-fixed-array"
+description = "A crate providing fixed length immutable collections with a low memory footprint."
+repository = "https://github.com/GnomedDev/small-fixed-array"
 version = "0.1.0"
 edition = "2021"
-
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+license = "MIT"
 
 [dependencies]
 serde = { version = "1.0.193", optional = true }

LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-Present David Thomas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,3 @@
+# small-fixed-array
+
+See [module documentation](https://docs.rs/small-fixed-array) or use `cargo doc --open`.

src/array.rs

@@ -2,40 +2,61 @@ use std::{fmt::Debug, hash::Hash};
 
 use crate::non_empty_array::NonEmptyFixedArray;
 
-/// A fixed size array with length provided at creation with length denoted in [`u32`]
+/// A fixed size array with length provided at creation denoted in [`u32`]
+///
+/// See module level documentation for more information.
 #[derive(Clone)]
 pub struct FixedArray<T>(Option<NonEmptyFixedArray<T>>);
 
 impl<T> FixedArray<T> {
+    /// Alias to [`FixedArray::empty`].
+    #[must_use]
     pub fn new() -> Self {
         Self::empty()
     }
 
+    /// Creates a new, empty [`FixedArray`] that cannot be pushed to.
+    #[must_use]
     pub fn empty() -> Self {
         Self(None)
     }
 
+    /// Returns the length of the [`FixedArray`].
+    #[must_use]
     pub fn len(&self) -> u32 {
         self.0
             .as_ref()
             .map(NonEmptyFixedArray::small_len)
             .unwrap_or_default()
     }
 
+    /// Returns if the length is equal to 0.
+    #[must_use]
     pub fn is_empty(&self) -> bool {
         self.0.is_none()
     }
 
+    /// Converts [`FixedArray<T>`] to [`Vec<T>`], this operation should be cheap.
+    #[must_use]
+    pub fn into_vec(self) -> Vec<T> {
+        self.into()
+    }
+
+    /// Converts `&`[`FixedArray<T>`] to `&[T]`, this conversion can be performed by [`std::ops::Deref`].
+    #[must_use]
     pub fn as_slice(&self) -> &[T] {
         self
     }
 
-    pub fn into_vec(self) -> Vec<T> {
-        self.into()
+    /// Converts `&mut `[`FixedArray<T>`] to `&mut [T]`, this conversion can be performed by [`std::ops::DerefMut`].
+    #[must_use]
+    pub fn as_slice_mut(&mut self) -> &mut [T] {
+        self
     }
 }
 
 impl<T> Default for FixedArray<T> {
+    /// Creates a new, empty [`FixedArray`] that cannot be pushed to.
     fn default() -> Self {
         Self::empty()
     }
@@ -77,7 +98,7 @@ impl<T> std::ops::IndexMut<u32> for FixedArray<T> {
 
 impl<T: Hash> Hash for FixedArray<T> {
     fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
-        self.as_slice().hash(state)
+        self.as_slice().hash(state);
     }
 }
 

src/lib.rs

@@ -1,3 +1,18 @@
+//! A crate for [`FixedArray`] and [`FixedString`], types to provide a smaller memory footprint in exchange for:
+//! - Immutablity, [`FixedArray`] and [`FixedString`] cannot be mutated without converting back to their expanded forms.
+//! - Maximum length, [`FixedArray`] and [`FixedString`] have a length cap of [`u32::MAX`] elements.
+//!
+//! These types provide cheap conversions to [`Vec`] and [`String`], to make up for most of these downsides, but it is
+//! still not recommended to use these collections for mutated values as you will see a performance downside.
+//!
+//! These can be thought of as `Box<[T]>` and `Box<str>`, except the length is denoted as a [`u32`].
+//!
+//! ## Features
+//! - `serde`: Provides [`serde`] implementations for [`FixedArray`] and [`FixedString`].
+//! - `typesize`: Provides [`typesize`] implementations for [`FixedArray`] and [`FixedString`].
+#![warn(clippy::pedantic)]
+#![allow(clippy::module_name_repetitions)]
+
 mod array;
 mod string;
 // Internal only!

src/non_empty_array.rs

@@ -25,10 +25,10 @@ impl<T> NonEmptyFixedArray<T> {
         unsafe { std::slice::from_raw_parts_mut(self.ptr.as_ptr(), self.len()) }
     }
 
-    /// Converts the NonEmptyFixedArray to it's original [`Box<T>`].
+    /// Converts the [`NonEmptyFixedArray`] to it's original [`Box<T>`].
     ///
     /// # Safety
-    /// `self` must never be used again, and it is highly recommended to wrap in ManuallyDrop before calling.
+    /// `self` must never be used again, and it is highly recommended to wrap in [`ManuallyDrop`] before calling.
     pub(crate) unsafe fn as_box(&mut self) -> Box<[T]> {
         let slice = self.as_mut_slice();
 
@@ -40,7 +40,7 @@ impl<T> NonEmptyFixedArray<T> {
 impl<T> From<Box<[T]>> for NonEmptyFixedArray<T> {
     fn from(boxed_array: Box<[T]>) -> Self {
         let len = NonZeroU32::new(boxed_array.len().try_into().unwrap()).unwrap();
-        let array_ptr = Box::into_raw(boxed_array) as *mut T;
+        let array_ptr = Box::into_raw(boxed_array).cast::<T>();
 
         NonEmptyFixedArray {
             ptr: NonNull::new(array_ptr).expect("Box ptr != nullptr"),
@@ -67,10 +67,8 @@ impl<T: Clone> Clone for NonEmptyFixedArray<T> {
 
 impl<T> Drop for NonEmptyFixedArray<T> {
     fn drop(&mut self) {
-        unsafe {
-            // SAFETY: We never use `self` again, and we are in the drop impl.
-            self.as_box();
-        }
+        // SAFETY: We never use `self` again, and we are in the drop impl.
+        unsafe { self.as_box() };
     }
 }
 

src/string.rs

@@ -2,19 +2,39 @@ use std::fmt::Write as _;
 
 use crate::FixedArray;
 
+/// A fixed size String with length provided at creation denoted in [`u32`].
+///
+/// See module level documentation for more information.
 #[derive(Default, Clone, Hash, PartialEq, Eq)]
 #[cfg_attr(feature = "typesize", derive(typesize::derive::TypeSize))]
 pub struct FixedString(FixedArray<u8>);
 
 impl FixedString {
+    #[must_use]
     pub fn new() -> Self {
         FixedString(FixedArray::default())
     }
 
+    /// Returns the length of the [`FixedString`].
+    #[must_use]
+    pub fn len(&self) -> u32 {
+        self.0.len()
+    }
+
+    /// Returns if the length is equal to 0.
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.0.is_empty()
+    }
+
+    /// Converts `&`[`FixedString`] to `&str`, this conversion can be performed by [`std::ops::Deref`].
+    #[must_use]
     pub fn as_str(&self) -> &str {
         self
     }
 
+    /// Converts [`FixedString`] to [`String`], this operation should be cheap.
+    #[must_use]
     pub fn into_string(self) -> String {
         self.into()
     }