vectrix 0.4.0

A stack-allocated matrix type implemented with const generics
Documentation 
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
139
140
141
142
143
144
145
146
147
148

use crate::Matrix;

mod private {
    pub trait Sealed {}
    impl Sealed for usize {}
    impl Sealed for (usize, usize) {}
}

/// A helper trait used for indexing operations.
///
/// This is the [`Matrix`] version of [`SliceIndex`][`core::slice::SliceIndex`].
/// You should not use or implement this trait directly but instead use the
/// corresponding methods on [`Matrix`].
///
/// # Safety
///
/// Implementations of this trait have to promise that if the argument
/// to `get_(mut_)unchecked` is a safe reference, then so is the result.
pub unsafe trait MatrixIndex<T: ?Sized>: private::Sealed {
    /// The output type returned by methods.
    type Output: ?Sized;

    /// Returns a shared reference to the output at this location, if in
    /// bounds.
    fn get(self, matrix: &T) -> Option<&Self::Output>;

    /// Returns a mutable reference to the output at this location, if in
    /// bounds.
    fn get_mut(self, matrix: &mut T) -> Option<&mut Self::Output>;

    /// Returns a shared reference to the output at this location, without
    /// performing any bounds checking.
    ///
    /// # Safety
    ///
    /// Calling this method with an out-of-bounds index or a dangling `matrix`
    /// pointer is *[undefined behavior]* even if the resulting reference is not
    /// used.
    ///
    /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
    unsafe fn get_unchecked(self, matrix: *const T) -> *const Self::Output;

    /// Returns a mutable reference to the output at this location, without
    /// performing any bounds checking.
    ///
    /// # Safety
    ///
    /// Calling this method with an out-of-bounds index or a dangling `matrix`
    /// pointer is *[undefined behavior]* even if the resulting reference is not
    /// used.
    ///
    /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
    unsafe fn get_unchecked_mut(self, stride: *mut T) -> *mut Self::Output;

    /// Returns a shared reference to the output at this location, panicking
    /// if out of bounds.
    #[track_caller]
    fn index(self, stride: &T) -> &Self::Output;

    /// Returns a mutable reference to the output at this location, panicking
    /// if out of bounds.
    #[track_caller]
    fn index_mut(self, stride: &mut T) -> &mut Self::Output;
}

unsafe impl<T, const M: usize, const N: usize> MatrixIndex<Matrix<T, M, N>> for usize {
    type Output = T;

    #[inline]
    fn get(self, matrix: &Matrix<T, M, N>) -> Option<&Self::Output> {
        matrix.as_slice().get(self)
    }

    #[inline]
    fn get_mut(self, matrix: &mut Matrix<T, M, N>) -> Option<&mut Self::Output> {
        matrix.as_mut_slice().get_mut(self)
    }

    #[inline]
    unsafe fn get_unchecked(self, matrix: *const Matrix<T, M, N>) -> *const Self::Output {
        // SAFETY: it is the caller's responsibility not to call this with an
        // out-of-bounds index or a dangling `matrix` pointer.
        let matrix = unsafe { (*matrix).as_slice() };
        unsafe { matrix.get_unchecked(self) }
    }

    #[inline]
    unsafe fn get_unchecked_mut(self, matrix: *mut Matrix<T, M, N>) -> *mut Self::Output {
        // SAFETY: it is the caller's responsibility not to call this with an
        // out-of-bounds index or a dangling `matrix` pointer.
        let matrix = unsafe { (*matrix).as_mut_slice() };
        unsafe { matrix.get_unchecked_mut(self) }
    }

    #[track_caller]
    #[inline]
    fn index(self, matrix: &Matrix<T, M, N>) -> &Self::Output {
        &matrix.as_slice()[self]
    }

    #[track_caller]
    #[inline]
    fn index_mut(self, matrix: &mut Matrix<T, M, N>) -> &mut Self::Output {
        &mut matrix.as_mut_slice()[self]
    }
}

unsafe impl<T, const M: usize, const N: usize> MatrixIndex<Matrix<T, M, N>> for (usize, usize) {
    type Output = T;

    #[inline]
    fn get(self, matrix: &Matrix<T, M, N>) -> Option<&Self::Output> {
        matrix.as_slice().get(self.1 * M + self.0)
    }

    #[inline]
    fn get_mut(self, matrix: &mut Matrix<T, M, N>) -> Option<&mut Self::Output> {
        matrix.as_mut_slice().get_mut(self.1 * M + self.0)
    }

    #[inline]
    unsafe fn get_unchecked(self, matrix: *const Matrix<T, M, N>) -> *const Self::Output {
        // SAFETY: it is the caller's responsibility not to call this with an
        // out-of-bounds index or a dangling `matrix` pointer.
        let matrix = unsafe { (*matrix).as_slice() };
        unsafe { matrix.get_unchecked(self.1 * M + self.0) }
    }

    #[inline]
    unsafe fn get_unchecked_mut(self, matrix: *mut Matrix<T, M, N>) -> *mut Self::Output {
        // SAFETY: it is the caller's responsibility not to call this with an
        // out-of-bounds index or a dangling `matrix` pointer.
        let matrix = unsafe { (*matrix).as_mut_slice() };
        unsafe { matrix.get_unchecked_mut(self.1 * M + self.0) }
    }

    #[track_caller]
    #[inline]
    fn index(self, matrix: &Matrix<T, M, N>) -> &Self::Output {
        &matrix.as_slice()[self.1 * M + self.0]
    }

    #[track_caller]
    #[inline]
    fn index_mut(self, matrix: &mut Matrix<T, M, N>) -> &mut Self::Output {
        &mut matrix.as_mut_slice()[self.1 * M + self.0]
    }
}