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