]>
Commit | Line | Data |
---|---|---|
1b1a35ee XL |
1 | //! Free functions to create `&[T]` and `&mut [T]`. |
2 | ||
3 | use crate::array; | |
ee023bcb FG |
4 | use crate::intrinsics::{assert_unsafe_precondition, is_aligned_and_not_null}; |
5 | use crate::ops::Range; | |
1b1a35ee XL |
6 | use crate::ptr; |
7 | ||
8 | /// Forms a slice from a pointer and a length. | |
9 | /// | |
10 | /// The `len` argument is the number of **elements**, not the number of bytes. | |
11 | /// | |
12 | /// # Safety | |
13 | /// | |
14 | /// Behavior is undefined if any of the following conditions are violated: | |
15 | /// | |
16 | /// * `data` must be [valid] for reads for `len * mem::size_of::<T>()` many bytes, | |
17 | /// and it must be properly aligned. This means in particular: | |
18 | /// | |
19 | /// * The entire memory range of this slice must be contained within a single allocated object! | |
20 | /// Slices can never span across multiple allocated objects. See [below](#incorrect-usage) | |
21 | /// for an example incorrectly not taking this into account. | |
22 | /// * `data` must be non-null and aligned even for zero-length slices. One | |
23 | /// reason for this is that enum layout optimizations may rely on references | |
24 | /// (including slices of any length) being aligned and non-null to distinguish | |
25 | /// them from other data. You can obtain a pointer that is usable as `data` | |
26 | /// for zero-length slices using [`NonNull::dangling()`]. | |
27 | /// | |
28 | /// * `data` must point to `len` consecutive properly initialized values of type `T`. | |
29 | /// | |
30 | /// * The memory referenced by the returned slice must not be mutated for the duration | |
31 | /// of lifetime `'a`, except inside an `UnsafeCell`. | |
32 | /// | |
33 | /// * The total size `len * mem::size_of::<T>()` of the slice must be no larger than `isize::MAX`. | |
34 | /// See the safety documentation of [`pointer::offset`]. | |
35 | /// | |
36 | /// # Caveat | |
37 | /// | |
38 | /// The lifetime for the returned slice is inferred from its usage. To | |
39 | /// prevent accidental misuse, it's suggested to tie the lifetime to whichever | |
40 | /// source lifetime is safe in the context, such as by providing a helper | |
41 | /// function taking the lifetime of a host value for the slice, or by explicit | |
42 | /// annotation. | |
43 | /// | |
44 | /// # Examples | |
45 | /// | |
46 | /// ``` | |
47 | /// use std::slice; | |
48 | /// | |
49 | /// // manifest a slice for a single element | |
50 | /// let x = 42; | |
51 | /// let ptr = &x as *const _; | |
52 | /// let slice = unsafe { slice::from_raw_parts(ptr, 1) }; | |
53 | /// assert_eq!(slice[0], 42); | |
54 | /// ``` | |
55 | /// | |
56 | /// ### Incorrect usage | |
57 | /// | |
58 | /// The following `join_slices` function is **unsound** ⚠️ | |
59 | /// | |
60 | /// ```rust,no_run | |
61 | /// use std::slice; | |
62 | /// | |
63 | /// fn join_slices<'a, T>(fst: &'a [T], snd: &'a [T]) -> &'a [T] { | |
64 | /// let fst_end = fst.as_ptr().wrapping_add(fst.len()); | |
65 | /// let snd_start = snd.as_ptr(); | |
66 | /// assert_eq!(fst_end, snd_start, "Slices must be contiguous!"); | |
67 | /// unsafe { | |
68 | /// // The assertion above ensures `fst` and `snd` are contiguous, but they might | |
69 | /// // still be contained within _different allocated objects_, in which case | |
70 | /// // creating this slice is undefined behavior. | |
71 | /// slice::from_raw_parts(fst.as_ptr(), fst.len() + snd.len()) | |
72 | /// } | |
73 | /// } | |
74 | /// | |
75 | /// fn main() { | |
76 | /// // `a` and `b` are different allocated objects... | |
77 | /// let a = 42; | |
78 | /// let b = 27; | |
79 | /// // ... which may nevertheless be laid out contiguously in memory: | a | b | | |
80 | /// let _ = join_slices(slice::from_ref(&a), slice::from_ref(&b)); // UB | |
81 | /// } | |
82 | /// ``` | |
83 | /// | |
84 | /// [valid]: ptr#safety | |
85 | /// [`NonNull::dangling()`]: ptr::NonNull::dangling | |
1b1a35ee XL |
86 | #[inline] |
87 | #[stable(feature = "rust1", since = "1.0.0")] | |
3c0e092e | 88 | #[rustc_const_unstable(feature = "const_slice_from_raw_parts", issue = "67456")] |
ee023bcb | 89 | #[must_use] |
3c0e092e | 90 | pub const unsafe fn from_raw_parts<'a, T>(data: *const T, len: usize) -> &'a [T] { |
1b1a35ee | 91 | // SAFETY: the caller must uphold the safety contract for `from_raw_parts`. |
ee023bcb FG |
92 | unsafe { |
93 | assert_unsafe_precondition!( | |
94 | is_aligned_and_not_null(data) | |
95 | && crate::mem::size_of::<T>().saturating_mul(len) <= isize::MAX as usize | |
96 | ); | |
97 | &*ptr::slice_from_raw_parts(data, len) | |
98 | } | |
1b1a35ee XL |
99 | } |
100 | ||
101 | /// Performs the same functionality as [`from_raw_parts`], except that a | |
102 | /// mutable slice is returned. | |
103 | /// | |
104 | /// # Safety | |
105 | /// | |
106 | /// Behavior is undefined if any of the following conditions are violated: | |
107 | /// | |
5869c6ff | 108 | /// * `data` must be [valid] for both reads and writes for `len * mem::size_of::<T>()` many bytes, |
1b1a35ee XL |
109 | /// and it must be properly aligned. This means in particular: |
110 | /// | |
111 | /// * The entire memory range of this slice must be contained within a single allocated object! | |
112 | /// Slices can never span across multiple allocated objects. | |
113 | /// * `data` must be non-null and aligned even for zero-length slices. One | |
114 | /// reason for this is that enum layout optimizations may rely on references | |
115 | /// (including slices of any length) being aligned and non-null to distinguish | |
116 | /// them from other data. You can obtain a pointer that is usable as `data` | |
117 | /// for zero-length slices using [`NonNull::dangling()`]. | |
118 | /// | |
119 | /// * `data` must point to `len` consecutive properly initialized values of type `T`. | |
120 | /// | |
121 | /// * The memory referenced by the returned slice must not be accessed through any other pointer | |
122 | /// (not derived from the return value) for the duration of lifetime `'a`. | |
123 | /// Both read and write accesses are forbidden. | |
124 | /// | |
125 | /// * The total size `len * mem::size_of::<T>()` of the slice must be no larger than `isize::MAX`. | |
126 | /// See the safety documentation of [`pointer::offset`]. | |
127 | /// | |
128 | /// [valid]: ptr#safety | |
129 | /// [`NonNull::dangling()`]: ptr::NonNull::dangling | |
1b1a35ee XL |
130 | #[inline] |
131 | #[stable(feature = "rust1", since = "1.0.0")] | |
3c0e092e | 132 | #[rustc_const_unstable(feature = "const_slice_from_raw_parts", issue = "67456")] |
ee023bcb | 133 | #[must_use] |
3c0e092e | 134 | pub const unsafe fn from_raw_parts_mut<'a, T>(data: *mut T, len: usize) -> &'a mut [T] { |
1b1a35ee | 135 | // SAFETY: the caller must uphold the safety contract for `from_raw_parts_mut`. |
3c0e092e | 136 | unsafe { |
ee023bcb FG |
137 | assert_unsafe_precondition!( |
138 | is_aligned_and_not_null(data) | |
139 | && crate::mem::size_of::<T>().saturating_mul(len) <= isize::MAX as usize | |
140 | ); | |
141 | &mut *ptr::slice_from_raw_parts_mut(data, len) | |
3c0e092e | 142 | } |
3c0e092e XL |
143 | } |
144 | ||
1b1a35ee XL |
145 | /// Converts a reference to T into a slice of length 1 (without copying). |
146 | #[stable(feature = "from_ref", since = "1.28.0")] | |
3c0e092e | 147 | #[rustc_const_unstable(feature = "const_slice_from_ref", issue = "90206")] |
ee023bcb | 148 | #[must_use] |
3c0e092e | 149 | pub const fn from_ref<T>(s: &T) -> &[T] { |
1b1a35ee XL |
150 | array::from_ref(s) |
151 | } | |
152 | ||
153 | /// Converts a reference to T into a slice of length 1 (without copying). | |
154 | #[stable(feature = "from_ref", since = "1.28.0")] | |
3c0e092e | 155 | #[rustc_const_unstable(feature = "const_slice_from_ref", issue = "90206")] |
ee023bcb | 156 | #[must_use] |
3c0e092e | 157 | pub const fn from_mut<T>(s: &mut T) -> &mut [T] { |
1b1a35ee XL |
158 | array::from_mut(s) |
159 | } | |
ee023bcb FG |
160 | |
161 | /// Forms a slice from a pointer range. | |
162 | /// | |
163 | /// This function is useful for interacting with foreign interfaces which | |
164 | /// use two pointers to refer to a range of elements in memory, as is | |
165 | /// common in C++. | |
166 | /// | |
167 | /// # Safety | |
168 | /// | |
169 | /// Behavior is undefined if any of the following conditions are violated: | |
170 | /// | |
171 | /// * The `start` pointer of the range must be a [valid] and properly aligned pointer | |
172 | /// to the first element of a slice. | |
173 | /// | |
174 | /// * The `end` pointer must be a [valid] and properly aligned pointer to *one past* | |
175 | /// the last element, such that the offset from the end to the start pointer is | |
176 | /// the length of the slice. | |
177 | /// | |
178 | /// * The range must contain `N` consecutive properly initialized values of type `T`: | |
179 | /// | |
180 | /// * The entire memory range of this slice must be contained within a single allocated object! | |
181 | /// Slices can never span across multiple allocated objects. | |
182 | /// | |
183 | /// * The memory referenced by the returned slice must not be mutated for the duration | |
184 | /// of lifetime `'a`, except inside an `UnsafeCell`. | |
185 | /// | |
186 | /// * The total length of the range must be no larger than `isize::MAX`. | |
187 | /// See the safety documentation of [`pointer::offset`]. | |
188 | /// | |
189 | /// Note that a range created from [`slice::as_ptr_range`] fulfills these requirements. | |
190 | /// | |
191 | /// # Caveat | |
192 | /// | |
193 | /// The lifetime for the returned slice is inferred from its usage. To | |
194 | /// prevent accidental misuse, it's suggested to tie the lifetime to whichever | |
195 | /// source lifetime is safe in the context, such as by providing a helper | |
196 | /// function taking the lifetime of a host value for the slice, or by explicit | |
197 | /// annotation. | |
198 | /// | |
199 | /// # Examples | |
200 | /// | |
201 | /// ``` | |
202 | /// #![feature(slice_from_ptr_range)] | |
203 | /// | |
204 | /// use core::slice; | |
205 | /// | |
206 | /// let x = [1, 2, 3]; | |
207 | /// let range = x.as_ptr_range(); | |
208 | /// | |
209 | /// unsafe { | |
210 | /// assert_eq!(slice::from_ptr_range(range), &x); | |
211 | /// } | |
212 | /// ``` | |
213 | /// | |
214 | /// [valid]: ptr#safety | |
215 | #[unstable(feature = "slice_from_ptr_range", issue = "89792")] | |
216 | pub unsafe fn from_ptr_range<'a, T>(range: Range<*const T>) -> &'a [T] { | |
217 | // SAFETY: the caller must uphold the safety contract for `from_ptr_range`. | |
218 | unsafe { from_raw_parts(range.start, range.end.offset_from(range.start) as usize) } | |
219 | } | |
220 | ||
221 | /// Performs the same functionality as [`from_ptr_range`], except that a | |
222 | /// mutable slice is returned. | |
223 | /// | |
224 | /// # Safety | |
225 | /// | |
226 | /// Behavior is undefined if any of the following conditions are violated: | |
227 | /// | |
228 | /// * The `start` pointer of the range must be a [valid] and properly aligned pointer | |
229 | /// to the first element of a slice. | |
230 | /// | |
231 | /// * The `end` pointer must be a [valid] and properly aligned pointer to *one past* | |
232 | /// the last element, such that the offset from the end to the start pointer is | |
233 | /// the length of the slice. | |
234 | /// | |
235 | /// * The range must contain `N` consecutive properly initialized values of type `T`: | |
236 | /// | |
237 | /// * The entire memory range of this slice must be contained within a single allocated object! | |
238 | /// Slices can never span across multiple allocated objects. | |
239 | /// | |
240 | /// * The memory referenced by the returned slice must not be accessed through any other pointer | |
241 | /// (not derived from the return value) for the duration of lifetime `'a`. | |
242 | /// Both read and write accesses are forbidden. | |
243 | /// | |
244 | /// * The total length of the range must be no larger than `isize::MAX`. | |
245 | /// See the safety documentation of [`pointer::offset`]. | |
246 | /// | |
247 | /// Note that a range created from [`slice::as_mut_ptr_range`] fulfills these requirements. | |
248 | /// | |
249 | /// # Examples | |
250 | /// | |
251 | /// ``` | |
252 | /// #![feature(slice_from_ptr_range)] | |
253 | /// | |
254 | /// use core::slice; | |
255 | /// | |
256 | /// let mut x = [1, 2, 3]; | |
257 | /// let range = x.as_mut_ptr_range(); | |
258 | /// | |
259 | /// unsafe { | |
260 | /// assert_eq!(slice::from_mut_ptr_range(range), &mut [1, 2, 3]); | |
261 | /// } | |
262 | /// ``` | |
263 | /// | |
264 | /// [valid]: ptr#safety | |
265 | #[unstable(feature = "slice_from_ptr_range", issue = "89792")] | |
266 | pub unsafe fn from_mut_ptr_range<'a, T>(range: Range<*mut T>) -> &'a mut [T] { | |
267 | // SAFETY: the caller must uphold the safety contract for `from_mut_ptr_range`. | |
268 | unsafe { from_raw_parts_mut(range.start, range.end.offset_from(range.start) as usize) } | |
269 | } |