1 //! Free functions to create `&[T]` and `&mut [T]`.
7 /// Forms a slice from a pointer and a length.
9 /// The `len` argument is the number of **elements**, not the number of bytes.
13 /// Behavior is undefined if any of the following conditions are violated:
15 /// * `data` must be [valid] for reads for `len * mem::size_of::<T>()` many bytes,
16 /// and it must be properly aligned. This means in particular:
18 /// * The entire memory range of this slice must be contained within a single allocated object!
19 /// Slices can never span across multiple allocated objects. See [below](#incorrect-usage)
20 /// for an example incorrectly not taking this into account.
21 /// * `data` must be non-null and aligned even for zero-length slices. One
22 /// reason for this is that enum layout optimizations may rely on references
23 /// (including slices of any length) being aligned and non-null to distinguish
24 /// them from other data. You can obtain a pointer that is usable as `data`
25 /// for zero-length slices using [`NonNull::dangling()`].
27 /// * `data` must point to `len` consecutive properly initialized values of type `T`.
29 /// * The memory referenced by the returned slice must not be mutated for the duration
30 /// of lifetime `'a`, except inside an `UnsafeCell`.
32 /// * The total size `len * mem::size_of::<T>()` of the slice must be no larger than `isize::MAX`.
33 /// See the safety documentation of [`pointer::offset`].
37 /// The lifetime for the returned slice is inferred from its usage. To
38 /// prevent accidental misuse, it's suggested to tie the lifetime to whichever
39 /// source lifetime is safe in the context, such as by providing a helper
40 /// function taking the lifetime of a host value for the slice, or by explicit
48 /// // manifest a slice for a single element
50 /// let ptr = &x as *const _;
51 /// let slice = unsafe { slice::from_raw_parts(ptr, 1) };
52 /// assert_eq!(slice[0], 42);
55 /// ### Incorrect usage
57 /// The following `join_slices` function is **unsound** ⚠️
62 /// fn join_slices<'a, T>(fst: &'a [T], snd: &'a [T]) -> &'a [T] {
63 /// let fst_end = fst.as_ptr().wrapping_add(fst.len());
64 /// let snd_start = snd.as_ptr();
65 /// assert_eq!(fst_end, snd_start, "Slices must be contiguous!");
67 /// // The assertion above ensures `fst` and `snd` are contiguous, but they might
68 /// // still be contained within _different allocated objects_, in which case
69 /// // creating this slice is undefined behavior.
70 /// slice::from_raw_parts(fst.as_ptr(), fst.len() + snd.len())
75 /// // `a` and `b` are different allocated objects...
78 /// // ... which may nevertheless be laid out contiguously in memory: | a | b |
79 /// let _ = join_slices(slice::from_ref(&a), slice::from_ref(&b)); // UB
83 /// [valid]: ptr#safety
84 /// [`NonNull::dangling()`]: ptr::NonNull::dangling
86 #[stable(feature = "rust1", since = "1.0.0")]
87 #[rustc_const_unstable(feature = "const_slice_from_raw_parts", issue = "67456")]
88 pub const unsafe fn from_raw_parts<'a, T>(data: *const T, len: usize) -> &'a [T] {
89 debug_check_data_len(data, len);
91 // SAFETY: the caller must uphold the safety contract for `from_raw_parts`.
92 unsafe { &*ptr::slice_from_raw_parts(data, len) }
95 /// Performs the same functionality as [`from_raw_parts`], except that a
96 /// mutable slice is returned.
100 /// Behavior is undefined if any of the following conditions are violated:
102 /// * `data` must be [valid] for both reads and writes for `len * mem::size_of::<T>()` many bytes,
103 /// and it must be properly aligned. This means in particular:
105 /// * The entire memory range of this slice must be contained within a single allocated object!
106 /// Slices can never span across multiple allocated objects.
107 /// * `data` must be non-null and aligned even for zero-length slices. One
108 /// reason for this is that enum layout optimizations may rely on references
109 /// (including slices of any length) being aligned and non-null to distinguish
110 /// them from other data. You can obtain a pointer that is usable as `data`
111 /// for zero-length slices using [`NonNull::dangling()`].
113 /// * `data` must point to `len` consecutive properly initialized values of type `T`.
115 /// * The memory referenced by the returned slice must not be accessed through any other pointer
116 /// (not derived from the return value) for the duration of lifetime `'a`.
117 /// Both read and write accesses are forbidden.
119 /// * The total size `len * mem::size_of::<T>()` of the slice must be no larger than `isize::MAX`.
120 /// See the safety documentation of [`pointer::offset`].
122 /// [valid]: ptr#safety
123 /// [`NonNull::dangling()`]: ptr::NonNull::dangling
125 #[stable(feature = "rust1", since = "1.0.0")]
126 #[rustc_const_unstable(feature = "const_slice_from_raw_parts", issue = "67456")]
127 pub const unsafe fn from_raw_parts_mut<'a, T>(data: *mut T, len: usize) -> &'a mut [T] {
128 debug_check_data_len(data as _, len);
130 // SAFETY: the caller must uphold the safety contract for `from_raw_parts_mut`.
131 unsafe { &mut *ptr::slice_from_raw_parts_mut(data, len) }
134 // In debug builds checks that `data` pointer is aligned and non-null and that slice with given `len` would cover less than half the address space
135 #[cfg(debug_assertions)]
136 #[unstable(feature = "const_slice_from_raw_parts", issue = "67456")]
137 #[rustc_const_unstable(feature = "const_slice_from_raw_parts", issue = "67456")]
138 const fn debug_check_data_len<T>(data: *const T, len: usize) {
139 fn rt_check<T>(data: *const T) {
140 use crate::intrinsics::is_aligned_and_not_null;
142 assert!(is_aligned_and_not_null(data), "attempt to create unaligned or null slice");
145 const fn noop<T>(_: *const T) {}
149 // `rt_check` is just a debug assert to hint users that they are causing UB,
150 // it is not required for safety (the safety must be guatanteed by
151 // the `from_raw_parts[_mut]` caller).
153 // As per our safety precondition, we may assume that assertion above never fails.
154 // Therefore, noop and rt_check are observably equivalent.
156 crate::intrinsics::const_eval_select((data,), noop, rt_check);
160 crate::mem::size_of::<T>().saturating_mul(len) <= isize::MAX as usize,
161 "attempt to create slice covering at least half the address space"
165 #[cfg(not(debug_assertions))]
166 const fn debug_check_data_len<T>(_data: *const T, _len: usize) {}
168 /// Converts a reference to T into a slice of length 1 (without copying).
169 #[stable(feature = "from_ref", since = "1.28.0")]
170 #[rustc_const_unstable(feature = "const_slice_from_ref", issue = "90206")]
171 pub const fn from_ref<T>(s: &T) -> &[T] {
175 /// Converts a reference to T into a slice of length 1 (without copying).
176 #[stable(feature = "from_ref", since = "1.28.0")]
177 #[rustc_const_unstable(feature = "const_slice_from_ref", issue = "90206")]
178 pub const fn from_mut<T>(s: &mut T) -> &mut [T] {
182 /// Forms a slice from a pointer range.
184 /// This function is useful for interacting with foreign interfaces which
185 /// use two pointers to refer to a range of elements in memory, as is
190 /// Behavior is undefined if any of the following conditions are violated:
192 /// * The `start` pointer of the range must be a [valid] and properly aligned pointer
193 /// to the first element of a slice.
195 /// * The `end` pointer must be a [valid] and properly aligned pointer to *one past*
196 /// the last element, such that the offset from the end to the start pointer is
197 /// the length of the slice.
199 /// * The range must contain `N` consecutive properly initialized values of type `T`:
201 /// * The entire memory range of this slice must be contained within a single allocated object!
202 /// Slices can never span across multiple allocated objects.
204 /// * The memory referenced by the returned slice must not be mutated for the duration
205 /// of lifetime `'a`, except inside an `UnsafeCell`.
207 /// * The total length of the range must be no larger than `isize::MAX`.
208 /// See the safety documentation of [`pointer::offset`].
210 /// Note that a range created from [`slice::as_ptr_range`] fulfills these requirements.
214 /// The lifetime for the returned slice is inferred from its usage. To
215 /// prevent accidental misuse, it's suggested to tie the lifetime to whichever
216 /// source lifetime is safe in the context, such as by providing a helper
217 /// function taking the lifetime of a host value for the slice, or by explicit
223 /// #![feature(slice_from_ptr_range)]
227 /// let x = [1, 2, 3];
228 /// let range = x.as_ptr_range();
231 /// assert_eq!(slice::from_ptr_range(range), &x);
235 /// [valid]: ptr#safety
236 #[unstable(feature = "slice_from_ptr_range", issue = "89792")]
237 pub unsafe fn from_ptr_range<'a, T>(range: Range<*const T>) -> &'a [T] {
238 // SAFETY: the caller must uphold the safety contract for `from_ptr_range`.
239 unsafe { from_raw_parts(range.start, range.end.offset_from(range.start) as usize) }
242 /// Performs the same functionality as [`from_ptr_range`], except that a
243 /// mutable slice is returned.
247 /// Behavior is undefined if any of the following conditions are violated:
249 /// * The `start` pointer of the range must be a [valid] and properly aligned pointer
250 /// to the first element of a slice.
252 /// * The `end` pointer must be a [valid] and properly aligned pointer to *one past*
253 /// the last element, such that the offset from the end to the start pointer is
254 /// the length of the slice.
256 /// * The range must contain `N` consecutive properly initialized values of type `T`:
258 /// * The entire memory range of this slice must be contained within a single allocated object!
259 /// Slices can never span across multiple allocated objects.
261 /// * The memory referenced by the returned slice must not be accessed through any other pointer
262 /// (not derived from the return value) for the duration of lifetime `'a`.
263 /// Both read and write accesses are forbidden.
265 /// * The total length of the range must be no larger than `isize::MAX`.
266 /// See the safety documentation of [`pointer::offset`].
268 /// Note that a range created from [`slice::as_mut_ptr_range`] fulfills these requirements.
273 /// #![feature(slice_from_ptr_range)]
277 /// let mut x = [1, 2, 3];
278 /// let range = x.as_mut_ptr_range();
281 /// assert_eq!(slice::from_mut_ptr_range(range), &mut [1, 2, 3]);
285 /// [valid]: ptr#safety
286 #[unstable(feature = "slice_from_ptr_range", issue = "89792")]
287 pub unsafe fn from_mut_ptr_range<'a, T>(range: Range<*mut T>) -> &'a mut [T] {
288 // SAFETY: the caller must uphold the safety contract for `from_mut_ptr_range`.
289 unsafe { from_raw_parts_mut(range.start, range.end.offset_from(range.start) as usize) }