1 //! Free functions to create `&[T]` and `&mut [T]`.
4 use crate::intrinsics::{assert_unsafe_precondition, is_aligned_and_not_null};
8 /// Forms a slice from a pointer and a length.
10 /// The `len` argument is the number of **elements**, not the number of bytes.
14 /// Behavior is undefined if any of the following conditions are violated:
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:
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()`].
28 /// * `data` must point to `len` consecutive properly initialized values of type `T`.
30 /// * The memory referenced by the returned slice must not be mutated for the duration
31 /// of lifetime `'a`, except inside an `UnsafeCell`.
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`].
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
49 /// // manifest a slice for a single element
51 /// let ptr = &x as *const _;
52 /// let slice = unsafe { slice::from_raw_parts(ptr, 1) };
53 /// assert_eq!(slice[0], 42);
56 /// ### Incorrect usage
58 /// The following `join_slices` function is **unsound** ⚠️
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!");
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())
76 /// // `a` and `b` are different allocated objects...
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
84 /// [valid]: ptr#safety
85 /// [`NonNull::dangling()`]: ptr::NonNull::dangling
87 #[stable(feature = "rust1", since = "1.0.0")]
88 #[rustc_const_unstable(feature = "const_slice_from_raw_parts", issue = "67456")]
89 pub const unsafe fn from_raw_parts<'a, T>(data: *const T, len: usize) -> &'a [T] {
90 // SAFETY: the caller must uphold the safety contract for `from_raw_parts`.
92 assert_unsafe_precondition!(
93 is_aligned_and_not_null(data)
94 && crate::mem::size_of::<T>().saturating_mul(len) <= isize::MAX as usize
96 &*ptr::slice_from_raw_parts(data, len)
100 /// Performs the same functionality as [`from_raw_parts`], except that a
101 /// mutable slice is returned.
105 /// Behavior is undefined if any of the following conditions are violated:
107 /// * `data` must be [valid] for both reads and writes for `len * mem::size_of::<T>()` many bytes,
108 /// and it must be properly aligned. This means in particular:
110 /// * The entire memory range of this slice must be contained within a single allocated object!
111 /// Slices can never span across multiple allocated objects.
112 /// * `data` must be non-null and aligned even for zero-length slices. One
113 /// reason for this is that enum layout optimizations may rely on references
114 /// (including slices of any length) being aligned and non-null to distinguish
115 /// them from other data. You can obtain a pointer that is usable as `data`
116 /// for zero-length slices using [`NonNull::dangling()`].
118 /// * `data` must point to `len` consecutive properly initialized values of type `T`.
120 /// * The memory referenced by the returned slice must not be accessed through any other pointer
121 /// (not derived from the return value) for the duration of lifetime `'a`.
122 /// Both read and write accesses are forbidden.
124 /// * The total size `len * mem::size_of::<T>()` of the slice must be no larger than `isize::MAX`.
125 /// See the safety documentation of [`pointer::offset`].
127 /// [valid]: ptr#safety
128 /// [`NonNull::dangling()`]: ptr::NonNull::dangling
130 #[stable(feature = "rust1", since = "1.0.0")]
131 #[rustc_const_unstable(feature = "const_slice_from_raw_parts", issue = "67456")]
132 pub const unsafe fn from_raw_parts_mut<'a, T>(data: *mut T, len: usize) -> &'a mut [T] {
133 // SAFETY: the caller must uphold the safety contract for `from_raw_parts_mut`.
135 assert_unsafe_precondition!(
136 is_aligned_and_not_null(data)
137 && crate::mem::size_of::<T>().saturating_mul(len) <= isize::MAX as usize
139 &mut *ptr::slice_from_raw_parts_mut(data, len)
143 /// Converts a reference to T into a slice of length 1 (without copying).
144 #[stable(feature = "from_ref", since = "1.28.0")]
145 #[rustc_const_unstable(feature = "const_slice_from_ref", issue = "90206")]
146 pub const fn from_ref<T>(s: &T) -> &[T] {
150 /// Converts a reference to T into a slice of length 1 (without copying).
151 #[stable(feature = "from_ref", since = "1.28.0")]
152 #[rustc_const_unstable(feature = "const_slice_from_ref", issue = "90206")]
153 pub const fn from_mut<T>(s: &mut T) -> &mut [T] {
157 /// Forms a slice from a pointer range.
159 /// This function is useful for interacting with foreign interfaces which
160 /// use two pointers to refer to a range of elements in memory, as is
165 /// Behavior is undefined if any of the following conditions are violated:
167 /// * The `start` pointer of the range must be a [valid] and properly aligned pointer
168 /// to the first element of a slice.
170 /// * The `end` pointer must be a [valid] and properly aligned pointer to *one past*
171 /// the last element, such that the offset from the end to the start pointer is
172 /// the length of the slice.
174 /// * The range must contain `N` consecutive properly initialized values of type `T`:
176 /// * The entire memory range of this slice must be contained within a single allocated object!
177 /// Slices can never span across multiple allocated objects.
179 /// * The memory referenced by the returned slice must not be mutated for the duration
180 /// of lifetime `'a`, except inside an `UnsafeCell`.
182 /// * The total length of the range must be no larger than `isize::MAX`.
183 /// See the safety documentation of [`pointer::offset`].
185 /// Note that a range created from [`slice::as_ptr_range`] fulfills these requirements.
189 /// The lifetime for the returned slice is inferred from its usage. To
190 /// prevent accidental misuse, it's suggested to tie the lifetime to whichever
191 /// source lifetime is safe in the context, such as by providing a helper
192 /// function taking the lifetime of a host value for the slice, or by explicit
198 /// #![feature(slice_from_ptr_range)]
202 /// let x = [1, 2, 3];
203 /// let range = x.as_ptr_range();
206 /// assert_eq!(slice::from_ptr_range(range), &x);
210 /// [valid]: ptr#safety
211 #[unstable(feature = "slice_from_ptr_range", issue = "89792")]
212 pub unsafe fn from_ptr_range<'a, T>(range: Range<*const T>) -> &'a [T] {
213 // SAFETY: the caller must uphold the safety contract for `from_ptr_range`.
214 unsafe { from_raw_parts(range.start, range.end.offset_from(range.start) as usize) }
217 /// Performs the same functionality as [`from_ptr_range`], except that a
218 /// mutable slice is returned.
222 /// Behavior is undefined if any of the following conditions are violated:
224 /// * The `start` pointer of the range must be a [valid] and properly aligned pointer
225 /// to the first element of a slice.
227 /// * The `end` pointer must be a [valid] and properly aligned pointer to *one past*
228 /// the last element, such that the offset from the end to the start pointer is
229 /// the length of the slice.
231 /// * The range must contain `N` consecutive properly initialized values of type `T`:
233 /// * The entire memory range of this slice must be contained within a single allocated object!
234 /// Slices can never span across multiple allocated objects.
236 /// * The memory referenced by the returned slice must not be accessed through any other pointer
237 /// (not derived from the return value) for the duration of lifetime `'a`.
238 /// Both read and write accesses are forbidden.
240 /// * The total length of the range must be no larger than `isize::MAX`.
241 /// See the safety documentation of [`pointer::offset`].
243 /// Note that a range created from [`slice::as_mut_ptr_range`] fulfills these requirements.
248 /// #![feature(slice_from_ptr_range)]
252 /// let mut x = [1, 2, 3];
253 /// let range = x.as_mut_ptr_range();
256 /// assert_eq!(slice::from_mut_ptr_range(range), &mut [1, 2, 3]);
260 /// [valid]: ptr#safety
261 #[unstable(feature = "slice_from_ptr_range", issue = "89792")]
262 pub unsafe fn from_mut_ptr_range<'a, T>(range: Range<*mut T>) -> &'a mut [T] {
263 // SAFETY: the caller must uphold the safety contract for `from_mut_ptr_range`.
264 unsafe { from_raw_parts_mut(range.start, range.end.offset_from(range.start) as usize) }