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
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168

use crate::ImpVec;
use orx_pinned_vec::PinnedVec;

impl<'a, T, P> ImpVec<T, P>
where
    P: PinnedVec<T> + 'a,
{
    /// Returns a mutable reference to the item at the `index`-th position of the vector;
    /// returns None if index is out of bounds.
    ///
    /// The main purpose of this method is to be able to build vectors
    /// elements of which reference other elements,
    /// while these references lead to cyclic relations.
    ///
    /// # Safety
    ///
    /// This method allows to mutate an existing element of the vector
    /// with an immutable reference.
    /// For obvious reasons, this operation is not safe.
    /// Therefore, it is important that this method is used in limited
    /// scopes, where the caller is able to guarantee the safety
    /// of the call.
    ///
    /// You may see in the next section such an example where the unsafe `get_mut`
    /// method is called only once to complete the cycle of references
    /// of points of a triangle.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use orx_imp_vec::prelude::*;
    /// use std::fmt::Debug;
    ///
    /// #[derive(Debug)]
    /// struct Point<'a, T> {
    ///     data: T,
    ///     next: Option<&'a Point<'a, T>>,
    /// }
    /// impl<'a, T: PartialEq + Debug> PartialEq for Point<'a, T> {
    ///     fn eq(&self, other: &Self) -> bool {
    ///         let ptr_eq =
    ///             |l1, r1| std::ptr::eq(l1 as *const Point<'_, T>, r1 as *const Point<'_, T>);
    ///         self.data == other.data
    ///             && match (self.next, other.next) {
    ///                 (Some(l1), Some(r1)) => ptr_eq(l1, r1),
    ///                 _ => {
    ///                     core::mem::discriminant(&self.next) == core::mem::discriminant(&other.next)
    ///                 }
    ///             }
    ///     }
    /// }
    ///
    /// // build cyclic reference of three points:
    /// // Point('x') -> Point('y') -> Point('z') -> Point('x') -> ...
    ///
    /// // the vector will grow; however, this does not invalidate references
    /// // since `SplitVec` and `FixedVec` both implement `PinnedVec`.
    /// let triangle: ImpVec<_, _> = SplitVec::with_doubling_growth(2).into();
    ///
    /// let z = triangle.push_get_ref(Point {
    ///     data: 'z',
    ///     next: None, /*none for now*/
    /// });
    /// let y = triangle.push_get_ref(Point {
    ///     data: 'y',
    ///     next: Some(z),
    /// });
    /// let x = triangle.push_get_ref(Point {
    ///     data: 'x',
    ///     next: Some(y),
    /// });
    ///
    /// // close the circle with the unsafe call
    /// unsafe { triangle.get_mut(0) }.unwrap().next = Some(x);
    ///
    /// let mut curr = x;
    /// let mut relations = curr.data.to_string();
    /// for _ in 0..4 {
    ///     curr = curr.next.unwrap();
    ///     relations.push_str(" -> ");
    ///     relations.push(curr.data);
    /// }
    /// println!("{}", relations);
    /// assert_eq!("x -> y -> z -> x -> y", relations);
    ///
    /// assert_eq!(
    ///     &x,
    ///     &x.next.unwrap().next.unwrap().next.unwrap() // x -> y -> z -> x
    /// );
    /// ```
    pub unsafe fn get_mut<'b>(&self, index: usize) -> Option<&'a mut T>
    where
        'a: 'b,
    {
        let data = self.as_mut_ptr();
        unsafe {
            let pinned_vec = &mut *data;
            pinned_vec.get_mut(index)
        }
    }

    /// Returns a reference to the item at the `index`-th position of the vector;
    /// returns None if index is out of bounds.
    ///
    /// The main purpose of this method is to be able to build vectors
    /// elements of which reference other elements,
    /// while these references lead to cyclic relations.
    ///
    /// # Safety
    ///
    /// This method allows to mutate an existing element of the vector
    /// with an immutable reference.
    /// For obvious reasons, this operation is not safe.
    /// Therefore, it is important that this method is used in limited
    /// scopes, where the caller is able to guarantee the safety
    /// of the call.
    /// See the `get_mut` examples related to safety.
    pub unsafe fn get_ref<'b>(&self, index: usize) -> Option<&'b T>
    where
        'a: 'b,
    {
        let data = self.as_mut_ptr();
        unsafe {
            let pinned_vec = &mut *data;
            pinned_vec.get(index)
        }
    }
}

#[cfg(test)]
mod tests {
    use crate::prelude::*;
    use crate::test_all_pinned_types;

    #[test]
    fn get_mut() {
        struct N<'a> {
            data: usize,
            next: Option<&'a N<'a>>,
        }

        fn test<'a, P: PinnedVec<N<'a>> + 'a>(pinned_vec: P) {
            let imp: ImpVec<_, _> = pinned_vec.into();

            let new_node = |data| N { data, next: None };

            let mut refs = vec![];
            for i in 0..1000 {
                let rf = imp.push_get_ref(new_node(i));
                refs.push(Some(rf));
            }

            unsafe { imp.get_mut(999) }.expect("-").next = refs[0];
            for i in 0..999 {
                unsafe { imp.get_mut(i) }.expect("-").next = refs[i + 1];
            }

            for i in 0..999 {
                assert_eq!(i, imp[i].data);
                assert_eq!(Some(i + 1), imp[i].next.map(|x| x.data))
            }
            assert_eq!(999, imp[999].data);
            assert_eq!(Some(0), imp[999].next.map(|x| x.data))
        }

        test_all_pinned_types!(test);
    }
}