osom_arrays/
traits.rs

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

osom_arrays/
traits.rs
