orx_v/matrices/v1/v1_as_matrix.rs
1use super::{
2 layout::{V1LayoutColMajor, V1LayoutRowMajor},
3 v1_matrix::V1Matrix,
4};
5use crate::{NVec, NVecMut, D1};
6
7/// Creates matrix views of a flat `D1` vector.
8pub trait V1AsMatrix<T> {
9 /// Converts the flat `D1` vector into a row-major matrix.
10 ///
11 /// Say i represents row-index and j represents col-index.
12 /// In a row-major matrix:
13 /// * it is more efficient to iterate first over i, and then over j,
14 /// * [`row(i)`] often (1) returns a vector over a contagious memory location.
15 ///
16 /// *(1) When the data is represented by a complete allocation; however, recall that
17 /// it is possible to use a function or a sparse vector backed up with a lookup as
18 /// the underlying vector of the matrix.*
19 ///
20 /// [`row(i)`]: crate::MatrixRowMajor::row
21 ///
22 /// # Panics
23 ///
24 /// Panics if cardinality of the `D1` vector is not equal to
25 /// `num_rows * num_cols`.
26 ///
27 /// # Examples
28 ///
29 /// ```
30 /// use orx_v::*;
31 ///
32 /// let v1 = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
33 ///
34 /// let mat = v1.v1_into_matrix(4, 3);
35 ///
36 /// assert_eq!(mat.num_rows(), 4);
37 /// assert_eq!(mat.num_cols(), 3);
38 ///
39 /// for row in mat.rows() {
40 /// assert_eq!(row.card([]), 3);
41 /// }
42 ///
43 /// assert_eq!(
44 /// mat.equality(&[[1, 2, 3], [4, 5, 6], [7, 8, 9], [10, 11, 12]].as_matrix()),
45 /// Equality::Equal
46 /// );
47 ///
48 /// let row = mat.row(2);
49 /// assert_eq!(row.equality(&[7, 8, 9]), Equality::Equal); // rows are contagious
50 ///
51 /// assert_eq!(mat.at([2, 1]), 8);
52 ///
53 /// assert_eq!(mat.all().count(), 12);
54 /// ```
55 fn v1_into_matrix(self, num_rows: usize, num_cols: usize) -> V1Matrix<T, Self, V1LayoutRowMajor>
56 where
57 Self: NVec<D1, T>,
58 {
59 V1Matrix::new(V1LayoutRowMajor::new(num_rows, num_cols), self)
60 }
61
62 /// Creates a row-major matrix view over the flat `D1` vector.
63 ///
64 /// Say i represents row-index and j represents col-index.
65 /// In a row-major matrix:
66 /// * it is more efficient to iterate first over i, and then over j,
67 /// * [`row(i)`] often (1) returns a vector over a contagious memory location.
68 ///
69 /// *(1) When the data is represented by a complete allocation; however, recall that
70 /// it is possible to use a function or a sparse vector backed up with a lookup as
71 /// the underlying vector of the matrix.*
72 ///
73 /// [`row(i)`]: crate::MatrixRowMajor::row
74 ///
75 /// # Panics
76 ///
77 /// Panics if cardinality of the `D1` vector is not equal to
78 /// `num_rows * num_cols`.
79 ///
80 /// # Examples
81 ///
82 /// ```
83 /// use orx_v::*;
84 ///
85 /// let v1 = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
86 ///
87 /// let mat = v1.v1_as_matrix(4, 3);
88 ///
89 /// assert_eq!(mat.num_rows(), 4);
90 /// assert_eq!(mat.num_cols(), 3);
91 ///
92 /// for row in mat.rows() {
93 /// assert_eq!(row.card([]), 3);
94 /// }
95 ///
96 /// assert_eq!(
97 /// mat.equality(&[[1, 2, 3], [4, 5, 6], [7, 8, 9], [10, 11, 12]].as_matrix()),
98 /// Equality::Equal
99 /// );
100 ///
101 /// let row = mat.row(2);
102 /// assert_eq!(row.equality(&[7, 8, 9]), Equality::Equal); // rows are contagious
103 ///
104 /// assert_eq!(mat.at([2, 1]), 8);
105 ///
106 /// assert_eq!(mat.all().count(), 12);
107 /// ```
108 fn v1_as_matrix(&self, num_rows: usize, num_cols: usize) -> V1Matrix<T, &Self, V1LayoutRowMajor>
109 where
110 Self: NVec<D1, T>,
111 {
112 V1Matrix::new(V1LayoutRowMajor::new(num_rows, num_cols), self)
113 }
114
115 /// Creates a mutable row-major matrix view over the flat `D1` vector.
116 ///
117 /// Say i represents row-index and j represents col-index.
118 /// In a row-major matrix:
119 /// * it is more efficient to iterate first over i, and then over j,
120 /// * [`row(i)`] often (1) returns a vector over a contagious memory location.
121 ///
122 /// *(1) When the data is represented by a complete allocation; however, recall that
123 /// it is possible to use a function or a sparse vector backed up with a lookup as
124 /// the underlying vector of the matrix.*
125 ///
126 /// [`row(i)`]: crate::MatrixRowMajor::row
127 ///
128 /// # Panics
129 ///
130 /// Panics if cardinality of the `D1` vector is not equal to
131 /// `num_rows * num_cols`.
132 ///
133 /// # Examples
134 ///
135 /// ```
136 /// use orx_v::*;
137 ///
138 /// let mut v1 = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
139 ///
140 /// let mut mat = v1.v1_as_matrix_mut(4, 3);
141 ///
142 /// assert_eq!(mat.num_rows(), 4);
143 /// assert_eq!(mat.num_cols(), 3);
144 ///
145 /// assert_eq!(
146 /// mat.equality(&[[1, 2, 3], [4, 5, 6], [7, 8, 9], [10, 11, 12]].as_matrix()),
147 /// Equality::Equal
148 /// );
149 ///
150 /// *mat.at_mut([0, 1]) = 22;
151 ///
152 /// mat.row_mut(1).mut_all(|x| *x *= 10);
153 ///
154 /// assert_eq!(mat.row(0).equality(&[1, 22, 3]), Equality::Equal);
155 /// assert_eq!(mat.row(1).equality(&[40, 50, 60]), Equality::Equal);
156 /// ```
157 fn v1_as_matrix_mut(
158 &mut self,
159 num_rows: usize,
160 num_cols: usize,
161 ) -> V1Matrix<T, &mut Self, V1LayoutRowMajor>
162 where
163 Self: NVecMut<D1, T>,
164 {
165 V1Matrix::new(V1LayoutRowMajor::new(num_rows, num_cols), self)
166 }
167
168 /// Converts the flat `D1` vector into a column-major matrix.
169 ///
170 /// Say i represents row-index and j represents col-index.
171 /// In a column-major matrix:
172 /// * it is more efficient to iterate first over j, and then over i,
173 /// * [`col(j)`] often (1) returns a vector over a contagious memory location.
174 ///
175 /// *(1) When the data is represented by a complete allocation; however, recall that
176 /// it is possible to use a function or a sparse vector backed up with a lookup as
177 /// the underlying vector of the matrix.*
178 ///
179 /// # Panics
180 ///
181 /// Panics if cardinality of the `D1` vector is not equal to
182 /// `num_rows * num_cols`.
183 ///
184 /// # Examples
185 ///
186 /// ```
187 /// use orx_v::*;
188 ///
189 /// let v1 = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
190 ///
191 /// let mat = v1.v1_into_matrix_col_major(4, 3);
192 ///
193 /// assert_eq!(mat.num_rows(), 4);
194 /// assert_eq!(mat.num_cols(), 3);
195 ///
196 /// for col in mat.cols() {
197 /// assert_eq!(col.card([]), 4);
198 /// }
199 ///
200 /// assert_eq!(mat.at([2, 1]), 7);
201 ///
202 /// assert_eq!(mat.all().count(), 12);
203 ///
204 /// assert_eq!(
205 /// mat.equality(&[[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]].as_matrix()),
206 /// Equality::Equal
207 /// );
208 ///
209 /// let col = mat.col(1);
210 /// assert_eq!(col.equality(&[5, 6, 7, 8]), Equality::Equal); // columns are contagious
211 /// ```
212 fn v1_into_matrix_col_major(
213 self,
214 num_rows: usize,
215 num_cols: usize,
216 ) -> V1Matrix<T, Self, V1LayoutColMajor>
217 where
218 Self: NVec<D1, T>,
219 {
220 V1Matrix::new(V1LayoutColMajor::new(num_rows, num_cols), self)
221 }
222
223 /// Creates a column-major matrix view over the flat `D1` vector.
224 ///
225 /// Say i represents row-index and j represents col-index.
226 /// In a column-major matrix:
227 /// * it is more efficient to iterate first over j, and then over i,
228 /// * [`col(j)`] often (1) returns a vector over a contagious memory location.
229 ///
230 /// *(1) When the data is represented by a complete allocation; however, recall that
231 /// it is possible to use a function or a sparse vector backed up with a lookup as
232 /// the underlying vector of the matrix.*
233 ///
234 /// # Panics
235 ///
236 /// Panics if cardinality of the `D1` vector is not equal to
237 /// `num_rows * num_cols`.
238 ///
239 /// # Examples
240 ///
241 /// ```
242 /// use orx_v::*;
243 ///
244 /// let v1 = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
245 ///
246 /// let mat = v1.v1_into_matrix_col_major(4, 3);
247 ///
248 /// assert_eq!(mat.num_rows(), 4);
249 /// assert_eq!(mat.num_cols(), 3);
250 ///
251 /// for col in mat.cols() {
252 /// assert_eq!(col.card([]), 4);
253 /// }
254 ///
255 /// assert_eq!(mat.at([2, 1]), 7);
256 ///
257 /// assert_eq!(mat.all().count(), 12);
258 ///
259 /// assert_eq!(
260 /// mat.equality(&[[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]].as_matrix()),
261 /// Equality::Equal
262 /// );
263 ///
264 /// let col = mat.col(1);
265 /// assert_eq!(col.equality(&[5, 6, 7, 8]), Equality::Equal); // columns are contagious
266 /// ```
267 fn v1_as_matrix_col_major(
268 &self,
269 num_rows: usize,
270 num_cols: usize,
271 ) -> V1Matrix<T, &Self, V1LayoutColMajor>
272 where
273 Self: NVec<D1, T>,
274 {
275 V1Matrix::new(V1LayoutColMajor::new(num_rows, num_cols), self)
276 }
277
278 /// Creates a mutable column-major matrix view over the flat `D1` vector.
279 ///
280 /// Say i represents row-index and j represents col-index.
281 /// In a column-major matrix:
282 /// * it is more efficient to iterate first over j, and then over i,
283 /// * [`col(j)`] often (1) returns a vector over a contagious memory location.
284 ///
285 /// *(1) When the data is represented by a complete allocation; however, recall that
286 /// it is possible to use a function or a sparse vector backed up with a lookup as
287 /// the underlying vector of the matrix.*
288 ///
289 /// # Panics
290 ///
291 /// Panics if cardinality of the `D1` vector is not equal to
292 /// `num_rows * num_cols`.
293 ///
294 /// # Examples
295 ///
296 /// ```
297 /// use orx_v::*;
298 ///
299 /// let mut v1 = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
300 ///
301 /// let mut mat = v1.v1_as_matrix_col_major_mut(4, 3);
302 ///
303 /// assert_eq!(mat.num_rows(), 4);
304 /// assert_eq!(mat.num_cols(), 3);
305 ///
306 /// *mat.at_mut([0, 2]) = 42;
307 ///
308 /// mat.col_mut(1).mut_all(|x| *x += 10); // columns are contagious
309 ///
310 /// assert_eq!(
311 /// mat.equality(&[[1, 15, 42], [2, 16, 10], [3, 17, 11], [4, 18, 12]].as_matrix()),
312 /// Equality::Equal
313 /// );
314 ///
315 /// let col = mat.col(1);
316 /// assert_eq!(col.equality(&[15, 16, 17, 18]), Equality::Equal); // columns are contagious
317 /// ```
318 fn v1_as_matrix_col_major_mut(
319 &mut self,
320 num_rows: usize,
321 num_cols: usize,
322 ) -> V1Matrix<T, &mut Self, V1LayoutColMajor>
323 where
324 Self: NVecMut<D1, T>,
325 {
326 V1Matrix::new(V1LayoutColMajor::new(num_rows, num_cols), self)
327 }
328}
329
330impl<T, V> V1AsMatrix<T> for V where V: NVec<D1, T> {}