soa-rs 0.8.1

A Vec-like structure-of-arrays container
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
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209

use std::ptr::NonNull;

use crate::Soars;

/// A low-level utility providing fundamental operations needed by [`Soa`].
///
/// In particular, it manages an allocation and a set of pointers into
/// the allocation. Each of the pointers corresponds to a field of the type `T`
/// and is treated as an array of values of that field's type.
///
/// # Safety
///
/// Use of this type is inherently unsafe and should be restricted to the
/// implementation of `Soa`. There is no guarantee of contract stability between
/// versions. Further, this type will **neither** deallocate its memory **nor**
/// drop its contents when it is dropped. Special care must be taken to avoid
/// unsound use.
///
/// In the method documentation, it is established that `PREV_CAP` is
///
/// - 0 if no previous calls to [`SoaRaw::realloc_grow`] or [`SoaRaw::realloc_shrink`] have been
/// made, or
/// - the same value as was used for `new_capacity` in previous calls
/// to [`SoaRaw::realloc_grow`] and [`SoaRaw::realloc_shrink`]
///
/// [`Soa`]: crate::Soa
#[doc(hidden)]
pub unsafe trait SoaRaw: Copy + Clone {
    /// The type of element the SoA will contain.
    ///
    /// This is also the type for which the trait implementation is derived when
    /// using the derive macro.
    type Item: Soars;

    /// Creates a [`SoaRaw`] with dangling pointers for all its fields and without
    /// allocating memory.
    fn dangling() -> Self;

    /// Construct a new [`SoaRaw`] with the given pointer and capacity.
    ///
    /// # Safety
    ///
    /// The pointer should come from a previous call to [`into_parts`] with
    /// `PREV_CAP == capacity`.
    ///
    /// [`into_parts`]: SoaRaw::into_parts
    unsafe fn from_parts(ptr: NonNull<u8>, capacity: usize) -> Self;

    /// Decomposes a [`SoaRaw`] into its raw components.
    ///
    /// Returns the raw pointer to the underlying data. The same pointer should
    /// be used as the first argument to [`from_parts`].
    ///
    /// [`from_parts`]: SoaRaw::from_parts
    fn into_parts(self) -> NonNull<u8>;

    /// Allocates room for `capacity` elements.
    ///
    /// # Safety
    ///
    /// The caller must ensure that
    ///
    /// - `size_of::<T>() > 0`
    /// - `capacity > 0`
    /// - `PREV_CAP == 0` (Otherwise use [`SoaRaw::realloc_grow`])
    #[must_use]
    unsafe fn alloc(capacity: usize) -> Self;

    /// Grows the allocation with room for `old_capacity` elements to fit
    /// `new_capacity` elements and moves `length` number of array elements to
    /// their new locations.
    ///
    /// # Safety
    ///
    /// The caller must ensure that
    ///
    /// - `size_of::<T>() > 0`
    /// - `new_capacity > old_capacity`
    /// - `length <= old_capacity`
    /// - `old_capacity > 0` (Otherwise use [`SoaRaw::alloc`])
    #[must_use]
    unsafe fn realloc_grow(
        &mut self,
        old_capacity: usize,
        new_capacity: usize,
        length: usize,
    ) -> Self;

    /// Shrinks the allocation with room for `old_capacity` elements to fit
    /// `new_capacity` elements and moves `length` number of array elements to
    /// their new locations.
    ///
    /// # Safety
    ///
    /// The caller must ensure that
    ///
    /// - `size_of::<T>() > 0`
    /// - `new_capacity < old_capacity`
    /// - `length <= new_capacity`
    /// - `new_capacity > 0` (Otherwise use [`SoaRaw::dealloc`])
    #[must_use]
    unsafe fn realloc_shrink(
        &mut self,
        old_capacity: usize,
        new_capacity: usize,
        length: usize,
    ) -> Self;

    /// Deallocates the allocation with room for `capacity` elements. The state
    /// after calling this method is equivalent to [`SoaRaw::dangling`].
    ///
    /// # Safety
    ///
    /// [`SoaRaw`] no longer valid after calling this function. The caller must ensure that
    ///
    /// - `size_of::<T>() > 0`
    /// - `old_capacity > 0`
    unsafe fn dealloc(self, old_capacity: usize);

    /// Copies `count` elements from `src` index to `dst` index in each of the
    /// arrays.
    ///
    /// # Safety
    ///
    /// The caller must ensure that
    ///
    /// - `src < PREV_CAP`
    /// - `dst < PREV_CAP`
    /// - `src + count <= PREV_CAP`
    /// - `dst + count <= PREV_CAP`
    unsafe fn copy_to(self, dst: Self, count: usize);

    /// Sets the element at `index` to `element`.
    ///
    /// # Safety
    ///
    /// The caller must ensure that
    ///
    /// - `index < PREV_CAP`
    unsafe fn set(self, element: Self::Item);

    /// Gets the element at `index`.
    ///
    /// # Safety
    ///
    /// After calling this method, the element at `index` should be treated as
    /// having been moved out of [`SoaRaw`] and into the caller. Therefore, it
    /// is no longer valid to reference this array element either by value or by
    /// reference. The caller must ensure that
    ///
    /// - `index < PREV_CAP`
    unsafe fn get(self) -> Self::Item;

    /// Gets a reference to the first element.
    ///
    /// # Safety
    ///
    /// The caller must ensure that
    ///
    /// The caller must ensure that either
    /// - Self is zero-sized, or
    /// - self points to at least one initialized value
    unsafe fn get_ref<'a>(self) -> <Self::Item as Soars>::Ref<'a>;

    /// Gets a mutable reference to the first element.
    ///
    /// # Safety
    ///
    /// The caller must ensure that either
    /// - Self is zero-sized, or
    /// - self points to at least one initialized value
    unsafe fn get_mut<'a>(self) -> <Self::Item as Soars>::RefMut<'a>;

    /// Create a new [`SoaRaw`] starting at index `count`.
    ///
    /// This is similar to indexing by [`RangeFrom`].
    ///
    /// # Safety
    ///
    /// The caller must ensure that
    ///
    /// - `count <= length`
    ///
    /// [`RangeFrom`]: std::ops::RangeFrom
    #[must_use]
    unsafe fn offset(self, count: usize) -> Self;

    /// Treats the raw SOA as a set of slices.
    ///
    /// # Safety
    ///
    /// The caller must ensure that
    ///
    /// - `len <= PREV_CAP`
    /// - At least `len` elements in the SOA have been initialized
    /// - The right lifetime is applied to the unconstrained lifetime returned
    unsafe fn slices<'a>(self, len: usize) -> <Self::Item as Soars>::Slices<'a>;

    /// Treats the raw SOA as a set of mutable slices.
    ///
    /// # Safety
    ///
    /// The caller must ensure that
    ///
    /// - `len <= PREV_CAP`
    /// - At least `len` elements in the SOA have been initialized
    /// - The right lifetime is applied to the unconstrained lifetime returned
    unsafe fn slices_mut<'a>(self, len: usize) -> <Self::Item as Soars>::SlicesMut<'a>;
}