Use generic InsufficientCapacity error type

"InsufficientCapacity" is a more precise description than "VectorFull"
or similar error names.

Author: awillenbuecher-xq-tec

src/containers/generic/queue.rs

@@ -11,12 +11,12 @@
 // SPDX-License-Identifier: Apache-2.0
 // *******************************************************************************
 
-use core::fmt;
 use core::marker::PhantomData;
 use core::mem::needs_drop;
 use core::ops::Range;
 use core::ptr;
 
+use crate::InsufficientCapacity;
 use crate::storage::Storage;
 
 #[repr(C)]
@@ -104,8 +104,8 @@ impl<T, S: Storage<T>> GenericQueue<T, S> {
     /// Tries to push an element to the back of the queue.
     ///
     /// If the queue has spare capacity, the push succeeds and a reference to that element
-    /// is returned; otherwise, `Err(QueueFull)` is returned.
-    pub fn push_back(&mut self, value: T) -> Result<&mut T, QueueFull> {
+    /// is returned; otherwise, `Err(InsufficientCapacity)` is returned.
+    pub fn push_back(&mut self, value: T) -> Result<&mut T, InsufficientCapacity> {
         let capacity = self.storage.capacity();
         if self.len < capacity {
             let write_pos = self.front_index as u64 + self.len as u64;
@@ -117,15 +117,15 @@ impl<T, S: Storage<T>> GenericQueue<T, S> {
             self.len += 1;
             Ok(unsafe { self.storage.element_mut(write_pos).write(value) })
         } else {
-            Err(QueueFull)
+            Err(InsufficientCapacity)
         }
     }
 
     /// Tries to push an element to the front of the queue.
     ///
     /// If the queue has spare capacity, the push succeeds and a reference to that element
-    /// is returned; otherwise, `Err(QueueFull)` is returned.
-    pub fn push_front(&mut self, value: T) -> Result<&mut T, QueueFull> {
+    /// is returned; otherwise, `Err(InsufficientCapacity)` is returned.
+    pub fn push_front(&mut self, value: T) -> Result<&mut T, InsufficientCapacity> {
         let capacity = self.storage.capacity();
         if self.len < capacity {
             let write_pos = if self.front_index > 0 { self.front_index - 1 } else { capacity - 1 };
@@ -134,7 +134,7 @@ impl<T, S: Storage<T>> GenericQueue<T, S> {
             self.front_index = write_pos;
             Ok(element)
         } else {
-            Err(QueueFull)
+            Err(InsufficientCapacity)
         }
     }
 
@@ -203,18 +203,6 @@ impl<T, S: Storage<T>> GenericQueue<T, S> {
     }
 }
 
-/// Indicates that an operation failed because the queue would exceed its maximum capacity.
-#[derive(Clone, Copy, Default, Debug)]
-pub struct QueueFull;
-
-impl fmt::Display for QueueFull {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        write!(f, "queue is full")
-    }
-}
-
-impl core::error::Error for QueueFull {}
-
 #[cfg(test)]
 mod tests {
     use std::{collections::VecDeque, mem::MaybeUninit};

src/containers/generic/string.rs

@@ -16,6 +16,7 @@ use core::ops;
 use core::str;
 
 use super::vec::GenericVec;
+use crate::InsufficientCapacity;
 use crate::storage::Storage;
 
 #[repr(transparent)]
@@ -86,23 +87,23 @@ impl<S: Storage<u8>> GenericString<S> {
     /// Tries to append the given character to the end of the string.
     ///
     /// If the string has sufficient spare capacity, the operation succeeds and a reference to the new character is returned;
-    /// otherwise, `Err(StringFull)` is returned.
-    pub fn push(&mut self, ch: char) -> Result<&mut str, StringFull> {
+    /// otherwise, `Err(InsufficientCapacity)` is returned.
+    pub fn push(&mut self, ch: char) -> Result<&mut str, InsufficientCapacity> {
         let mut buffer = [0_u8; 4];
         self.push_str(ch.encode_utf8(&mut buffer))
     }
 
     /// Tries to append the given string slice to the end of the string.
     ///
     /// If the string has sufficient spare capacity, the operation succeeds and a reference to the new characters is returned;
-    /// otherwise, `Err(StringFull)` is returned.
-    pub fn push_str(&mut self, other: &str) -> Result<&mut str, StringFull> {
+    /// otherwise, `Err(InsufficientCapacity)` is returned.
+    pub fn push_str(&mut self, other: &str) -> Result<&mut str, InsufficientCapacity> {
         match self.vec.extend_from_slice(other.as_bytes()) {
             Ok(bytes) => Ok(
                 // SAFETY: `bytes == string.as_bytes()`, therefore this is valid UTF-8
                 unsafe { str::from_utf8_unchecked_mut(bytes) },
             ),
-            Err(_) => Err(StringFull),
+            Err(_) => Err(InsufficientCapacity),
         }
     }
 
@@ -147,18 +148,6 @@ impl<S: Storage<u8>> fmt::Debug for GenericString<S> {
     }
 }
 
-/// Indicates that an operation failed because the string would exceed its maximum capacity.
-#[derive(Clone, Copy, Default, Debug)]
-pub struct StringFull;
-
-impl fmt::Display for StringFull {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        write!(f, "string is full")
-    }
-}
-
-impl core::error::Error for StringFull {}
-
 #[cfg(test)]
 mod tests {
     use std::mem::MaybeUninit;

src/containers/generic/vec.rs

@@ -17,6 +17,7 @@ use core::mem::needs_drop;
 use core::ops;
 use core::ptr;
 
+use crate::InsufficientCapacity;
 use crate::storage::Storage;
 
 #[repr(C)]
@@ -88,14 +89,14 @@ impl<T, S: Storage<T>> GenericVec<T, S> {
     /// Tries to push an element to the back of the vector.
     ///
     /// If the vector has spare capacity, the push succeeds and a reference to that element
-    /// is returned; otherwise, `Err(VectorFull)` is returned.
-    pub fn push(&mut self, value: T) -> Result<&mut T, VectorFull> {
+    /// is returned; otherwise, `Err(InsufficientCapacity)` is returned.
+    pub fn push(&mut self, value: T) -> Result<&mut T, InsufficientCapacity> {
         if self.len < self.storage.capacity() {
             let element = unsafe { self.storage.element_mut(self.len) }.write(value);
             self.len += 1;
             Ok(element)
         } else {
-            Err(VectorFull)
+            Err(InsufficientCapacity)
         }
     }
 
@@ -140,9 +141,9 @@ impl<T: Copy, S: Storage<T>> GenericVec<T, S> {
     /// Tries to append a copy of the given slice to the end of the vector.
     ///
     /// If the vector has sufficient spare capacity, the operation succeeds and a reference to those elements is returned;
-    /// otherwise, `Err(VectorFull)` is returned.
-    pub fn extend_from_slice(&mut self, other: &[T]) -> Result<&mut [T], VectorFull> {
-        let new_len = (self.len as usize).checked_add(other.len()).ok_or(VectorFull)?;
+    /// otherwise, `Err(InsufficientCapacity)` is returned.
+    pub fn extend_from_slice(&mut self, other: &[T]) -> Result<&mut [T], InsufficientCapacity> {
+        let new_len = (self.len as usize).checked_add(other.len()).ok_or(InsufficientCapacity)?;
         if new_len <= self.capacity() {
             let new_len = new_len as u32; // No overflow, because new_len <= capacity <= u32::MAX
             // SAFETY:
@@ -161,7 +162,7 @@ impl<T: Copy, S: Storage<T>> GenericVec<T, S> {
             // SAFETY: the memory in the `target` slice has now been initialized
             Ok(unsafe { &mut *target })
         } else {
-            Err(VectorFull)
+            Err(InsufficientCapacity)
         }
     }
 }
@@ -186,18 +187,6 @@ impl<T: fmt::Debug, S: Storage<T>> fmt::Debug for GenericVec<T, S> {
     }
 }
 
-/// Indicates that an operation failed because the vector would exceed its maximum capacity.
-#[derive(Clone, Copy, Default, Debug)]
-pub struct VectorFull;
-
-impl fmt::Display for VectorFull {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        write!(f, "vector is full")
-    }
-}
-
-impl core::error::Error for VectorFull {}
-
 #[cfg(test)]
 mod tests {
     use std::mem::MaybeUninit;

src/containers/lib.rs

@@ -19,3 +19,19 @@ pub mod fixed_capacity;
 pub(crate) mod generic;
 pub mod inline;
 pub(crate) mod storage;
+
+use core::fmt;
+
+/// Indicates that an operation failed because the container doesn't have enough remaining capacity.
+///
+/// Note that this doesn't necessarily mean that the container is full.
+#[derive(Clone, Copy, Default, Debug)]
+pub struct InsufficientCapacity;
+
+impl fmt::Display for InsufficientCapacity {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "insufficient capacity for this operation")
+    }
+}
+
+impl core::error::Error for InsufficientCapacity {}