devela/data/collections/vec/d2/methods/
general.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
// devela::data::collections::vec::d2::methods::general
//
//! 2-dimensional Vec general methods
//

use crate::{vec_ as vec, IndexOutOfBounds, Vec, Vec2d};

/* constructors */

// T: Clone
impl<T: Clone, const RMAJ: bool> Vec2d<T, RMAJ> {
    /// Returns a 2-dimensional grid, allocated in the stack,
    /// using `element` to fill the remaining free data.
    /// # Errors
    /// Returns [`IndexOutOfBounds`] if `rows * cols > usize::MAX`.
    /// # Examples
    /// ```
    /// # use devela::Vec2d;
    /// let g = Vec2d::<char, true>::with_cloned('.', 4, 4);
    /// ```
    pub fn with_cloned(element: T, rows: usize, cols: usize) -> Result<Self, IndexOutOfBounds> {
        let size = rows.checked_mul(cols).ok_or(IndexOutOfBounds(None))?;
        let data = vec![element; size]; // Efficiently initializes all elements
        Ok(Self { data, rows, cols })
    }
}

// Order-independent
// T
#[rustfmt::skip]
impl<T, const RMAJ: bool> Vec2d<T, RMAJ> {
    /* general queries */

    /// Returns the total length of the array, equals `C * R`.
    #[must_use]
    pub const fn len(&self) -> usize { self.cols * self.rows }

    /// Returns the length of the cols axis.
    /// (AKA width, number of columns or row length).
    #[must_use] pub const fn x_len(&self) -> usize { self.cols }

    /// Returns the length of the rows axis
    /// (AKA height, number of rows or column length).
    #[must_use] pub const fn y_len(&self) -> usize { self.rows }

    /// Returns `true` if the stack is empty (has 0 length).
    /// # Examples
    /// ```
    /// # use devela::Vec2d;
    /// let g2 = Vec2d::<i32>::default();
    /// assert![g2.is_empty()];
    /// ```
    #[must_use]
    pub const fn is_empty(&self) -> bool { self.len() == 0 }

    // DELETE
    // /// Checks the geometry of the columns, rows and their product length.
    // /// # Errors
    // /// Returns [`IndexOutOfBounds`] if `C * R > usize::MAX`
    // /// or [`MismatchedCapacity`] if `C * R != CR`.
    // #[allow(non_snake_case)]
    // pub(crate) const fn check_CR() -> Result<(), MismatchedBounds> {
    //     if let Some(len) = C.checked_mul(R) {
    //         if len == CR {
    //             Ok(())
    //         } else {
    //             Err(MismatchedCapacity(Mismatch { need: CR, have: len, info: "C * R != CR" }))
    //         }
    //     } else {
    //         Err(IndexOutOfBounds)
    //     }
    // }
    //
    // /// Checks the geometry of the columns, rows and their product length.
    // /// # Panics
    // /// Panics if `C * R > usize::MAX` or if `C * R != CR`.
    // #[allow(non_snake_case)]
    // pub(crate) const fn panic_check_CR() {
    //     if let Some(len) = C.checked_mul(R) {
    //         if len != CR {
    //             panic![concat![ "Vec2d Mismatch: C * R != CR: ",
    //                 stringify!(C), " * ", stringify!(R), " != ", stringify!(CR) ]];
    //         }
    //     } else {
    //         panic![concat![ "Vec2d overflow: C * R (",
    //             stringify!(R), " * ", stringify!(C), " > usize::MAX)" ]];
    //     }
    // }

    /// Returns the inner `Vec`.
    #[must_use]
    pub fn into_vec(self) -> Vec<T> { self.data }

    /* slices */

    /// Returns a slice containing the full grid.
    // /// # Examples
    // /// ```
    // /// # use devela::Vec2d;
    // /// let g = Vec2d::from([1, 2, 3]);
    // /// assert_eq![s.as_slice(), &[1, 2, 3]];
    // /// ```
    #[must_use]
    pub fn as_slice(&self) -> &[T] { self.data.as_slice() }

    /// Returns the stack as an exclusive slice.
    // /// # Examples
    // /// ```
    // /// # use devela::Vec2d;
    // /// let mut g = Vec2d::<_, (), 2, 2, 4>::from([1, 2, 3]);
    // /// assert_eq![s.as_mut_slice(), &mut [1, 2, 3]];
    // /// ```
    #[must_use]
    pub fn as_mut_slice(&mut self) -> &mut [T] { self.data.as_mut_slice() }
}

// T: Clone
#[rustfmt::skip]
impl<T: Clone, const RMAJ: bool> Vec2d<T, RMAJ> {
    /// Fills all elements of the grid with the given `element`.
    pub fn fill(&mut self, element: T) { self.data.fill(element) }
}

// T: PartialEq
impl<T: PartialEq, const RMAJ: bool> Vec2d<T, RMAJ> {
    /// Returns true if the array contains `element`.
    /// # Examples
    // /// ```
    // /// # use devela::Vec2d;
    // /// let a = Vec2d::<_, 5, 5, 25>::new([5, 78, 42, 33, 9]);
    // /// assert![a.contains(&9)];
    // /// assert![!a.contains(&8)];
    // /// ```
    #[must_use]
    pub fn contains(&self, element: &T) -> bool {
        self.data.iter().any(|n| n == element)
    }
}