osom_lib_arrays/
traits.rs

1//! Defines mutable and immutable traits for arrays.
2
3use osom_lib_primitives::length::Length;
4use osom_lib_try_clone::TryClone;
5
6use crate::errors::{ArrayError, ArrayIsEmptyError, ArrayTryCloneError};
7
8/// Represents a simply contiguous block of memory.
9pub trait ImmutableArray<T>: AsRef<[T]> {
10    /// Returns array's length as [`Length`].
11    fn length(&self) -> Length;
12
13    /// Returns the current capacity for holding items in the array.
14    fn capacity(&self) -> Length;
15
16    /// Returns `true` if array is empty, `false` otherwise.
17    /// Should be consistent with `self.length() == Length::ZERO`
18    /// check.
19    #[inline(always)]
20    #[must_use]
21    fn is_empty(&self) -> bool {
22        self.length() == Length::ZERO
23    }
24}
25
26/// Represents a simply contiguous block of memory that is not only
27/// mutable internally but can also grow/shrink in size.
28pub trait MutableArray<T>: ImmutableArray<T> + AsMut<[T]> {
29    /// Tries to push raw array to the array.
30    ///
31    /// # Errors
32    ///
33    /// For errors see [`ArrayError`].
34    fn try_push_array<const TSIZE: usize>(&mut self, arr: [T; TSIZE]) -> Result<(), ArrayError>;
35
36    /// Tries to push slice to the array. This method requires [`Clone`]
37    /// trait on `T`.
38    ///
39    /// # Errors
40    ///
41    /// For errors see [`ArrayError`].
42    fn try_push_slice(&mut self, slice: &[T]) -> Result<(), ArrayTryCloneError>
43    where
44        T: TryClone;
45
46    /// Removes element from the top of the array.
47    ///
48    /// # Errors
49    ///
50    /// Returns [`ArrayIsEmptyError`] when the array is empty.
51    fn try_pop(&mut self) -> Result<T, ArrayIsEmptyError>;
52
53    /// Removes element from the top of the array.
54    ///
55    /// # Panics
56    ///
57    /// Panics if is the array is empty. Should be consistent with [`MutableArray::try_pop`].
58    #[inline(always)]
59    #[must_use]
60    fn pop(&mut self) -> T {
61        self.try_pop()
62            .expect("Couldn't pop from the array, since it was empty.")
63    }
64
65    /// Pushes a single element to the array.
66    ///
67    /// # Errors
68    ///
69    /// For errors see [`ArrayError`].
70    #[inline(always)]
71    fn try_push(&mut self, value: T) -> Result<(), ArrayError> {
72        self.try_push_array([value])
73    }
74
75    /// Pushes raw array to the array.
76    ///
77    /// # Panics
78    ///
79    /// Panics whenever [`MutableArray::try_push_array`] would.
80    #[inline(always)]
81    fn push_array<const TSIZE: usize>(&mut self, arr: [T; TSIZE]) {
82        self.try_push_array(arr)
83            .expect("Failed to push_array due to array error.");
84    }
85
86    /// Pushes raw slice to the array. This method requires [`Clone`]
87    /// trait on `T`.
88    ///
89    /// # Panics
90    ///
91    /// Panics whenever [`MutableArray::try_push_slice`] would.
92    #[inline(always)]
93    fn push_slice(&mut self, slice: &[T])
94    where
95        T: TryClone,
96    {
97        self.try_push_slice(slice)
98            .expect("Failed to push_slice due to array error.");
99    }
100
101    /// Pushes a single element to the array.
102    ///
103    /// # Panics
104    ///
105    /// Panics whenever [`MutableArray::try_push`] would.
106    #[inline(always)]
107    fn push(&mut self, value: T) {
108        self.try_push(value).expect("Failed to push due to array error.");
109    }
110}
osom_lib_arrays/traits.rs

osom_lib_arrays/
traits.rs
