osom_lib_arrays/
traits.rs

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

osom_lib_arrays/
traits.rs
