1 //! Free functions to create `&[T]` and `&mut [T]`.
4 use crate::intrinsics::{
5 assert_unsafe_precondition, is_aligned_and_not_null, is_valid_allocation_size,
10 /// Forms a slice from a pointer and a length.
12 /// The `len` argument is the number of **elements**, not the number of bytes.
16 /// Behavior is undefined if any of the following conditions are violated:
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:
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()`].
30 /// * `data` must point to `len` consecutive properly initialized values of type `T`.
32 /// * The memory referenced by the returned slice must not be mutated for the duration
33 /// of lifetime `'a`, except inside an `UnsafeCell`.
35 /// * The total size `len * mem::size_of::<T>()` of the slice must be no larger than `isize::MAX`.
36 /// See the safety documentation of [`pointer::offset`].
40 /// The lifetime for the returned slice is inferred from its usage. To
41 /// prevent accidental misuse, it's suggested to tie the lifetime to whichever
42 /// source lifetime is safe in the context, such as by providing a helper
43 /// function taking the lifetime of a host value for the slice, or by explicit
51 /// // manifest a slice for a single element
53 /// let ptr = &x as *const _;
54 /// let slice = unsafe { slice::from_raw_parts(ptr, 1) };
55 /// assert_eq!(slice[0], 42);
58 /// ### Incorrect usage
60 /// The following `join_slices` function is **unsound** ⚠️
65 /// fn join_slices<'a, T>(fst: &'a [T], snd: &'a [T]) -> &'a [T] {
66 /// let fst_end = fst.as_ptr().wrapping_add(fst.len());
67 /// let snd_start = snd.as_ptr();
68 /// assert_eq!(fst_end, snd_start, "Slices must be contiguous!");
70 /// // The assertion above ensures `fst` and `snd` are contiguous, but they might
71 /// // still be contained within _different allocated objects_, in which case
72 /// // creating this slice is undefined behavior.
73 /// slice::from_raw_parts(fst.as_ptr(), fst.len() + snd.len())
78 /// // `a` and `b` are different allocated objects...
81 /// // ... which may nevertheless be laid out contiguously in memory: | a | b |
82 /// let _ = join_slices(slice::from_ref(&a), slice::from_ref(&b)); // UB
86 /// [valid]: ptr#safety
87 /// [`NonNull::dangling()`]: ptr::NonNull::dangling
89 #[stable(feature = "rust1", since = "1.0.0")]
90 #[rustc_const_stable(feature = "const_slice_from_raw_parts", since = "1.64.0")]
92 pub const unsafe fn from_raw_parts<'a, T>(data: *const T, len: usize) -> &'a [T] {
93 // SAFETY: the caller must uphold the safety contract for `from_raw_parts`.
95 assert_unsafe_precondition!(
96 "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`",
97 [T](data: *const T, len: usize) => is_aligned_and_not_null(data)
98 && is_valid_allocation_size::<T>(len)
100 &*ptr::slice_from_raw_parts(data, len)
104 /// Performs the same functionality as [`from_raw_parts`], except that a
105 /// mutable slice is returned.
109 /// Behavior is undefined if any of the following conditions are violated:
111 /// * `data` must be [valid] for both reads and writes for `len * mem::size_of::<T>()` many bytes,
112 /// and it must be properly aligned. This means in particular:
114 /// * The entire memory range of this slice must be contained within a single allocated object!
115 /// Slices can never span across multiple allocated objects.
116 /// * `data` must be non-null and aligned even for zero-length slices. One
117 /// reason for this is that enum layout optimizations may rely on references
118 /// (including slices of any length) being aligned and non-null to distinguish
119 /// them from other data. You can obtain a pointer that is usable as `data`
120 /// for zero-length slices using [`NonNull::dangling()`].
122 /// * `data` must point to `len` consecutive properly initialized values of type `T`.
124 /// * The memory referenced by the returned slice must not be accessed through any other pointer
125 /// (not derived from the return value) for the duration of lifetime `'a`.
126 /// Both read and write accesses are forbidden.
128 /// * The total size `len * mem::size_of::<T>()` of the slice must be no larger than `isize::MAX`.
129 /// See the safety documentation of [`pointer::offset`].
131 /// [valid]: ptr#safety
132 /// [`NonNull::dangling()`]: ptr::NonNull::dangling
134 #[stable(feature = "rust1", since = "1.0.0")]
135 #[rustc_const_unstable(feature = "const_slice_from_raw_parts_mut", issue = "67456")]
137 pub const unsafe fn from_raw_parts_mut<'a, T>(data: *mut T, len: usize) -> &'a mut [T] {
138 // SAFETY: the caller must uphold the safety contract for `from_raw_parts_mut`.
140 assert_unsafe_precondition!(
141 "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`",
142 [T](data: *mut T, len: usize) => is_aligned_and_not_null(data)
143 && is_valid_allocation_size::<T>(len)
145 &mut *ptr::slice_from_raw_parts_mut(data, len)
149 /// Converts a reference to T into a slice of length 1 (without copying).
150 #[stable(feature = "from_ref", since = "1.28.0")]
151 #[rustc_const_stable(feature = "const_slice_from_ref_shared", since = "1.63.0")]
153 pub const fn from_ref<T>(s: &T) -> &[T] {
157 /// Converts a reference to T into a slice of length 1 (without copying).
158 #[stable(feature = "from_ref", since = "1.28.0")]
159 #[rustc_const_unstable(feature = "const_slice_from_ref", issue = "90206")]
161 pub const fn from_mut<T>(s: &mut T) -> &mut [T] {
165 /// Forms a slice from a pointer range.
167 /// This function is useful for interacting with foreign interfaces which
168 /// use two pointers to refer to a range of elements in memory, as is
173 /// Behavior is undefined if any of the following conditions are violated:
175 /// * The `start` pointer of the range must be a [valid] and properly aligned pointer
176 /// to the first element of a slice.
178 /// * The `end` pointer must be a [valid] and properly aligned pointer to *one past*
179 /// the last element, such that the offset from the end to the start pointer is
180 /// the length of the slice.
182 /// * The range must contain `N` consecutive properly initialized values of type `T`:
184 /// * The entire memory range of this slice must be contained within a single allocated object!
185 /// Slices can never span across multiple allocated objects.
187 /// * The memory referenced by the returned slice must not be mutated for the duration
188 /// of lifetime `'a`, except inside an `UnsafeCell`.
190 /// * The total length of the range must be no larger than `isize::MAX`.
191 /// See the safety documentation of [`pointer::offset`].
193 /// Note that a range created from [`slice::as_ptr_range`] fulfills these requirements.
197 /// This function panics if `T` is a Zero-Sized Type (“ZST”).
201 /// The lifetime for the returned slice is inferred from its usage. To
202 /// prevent accidental misuse, it's suggested to tie the lifetime to whichever
203 /// source lifetime is safe in the context, such as by providing a helper
204 /// function taking the lifetime of a host value for the slice, or by explicit
210 /// #![feature(slice_from_ptr_range)]
214 /// let x = [1, 2, 3];
215 /// let range = x.as_ptr_range();
218 /// assert_eq!(slice::from_ptr_range(range), &x);
222 /// [valid]: ptr#safety
223 #[unstable(feature = "slice_from_ptr_range", issue = "89792")]
224 #[rustc_const_unstable(feature = "const_slice_from_ptr_range", issue = "89792")]
225 pub const unsafe fn from_ptr_range<'a, T>(range: Range<*const T>) -> &'a [T] {
226 // SAFETY: the caller must uphold the safety contract for `from_ptr_range`.
227 unsafe { from_raw_parts(range.start, range.end.sub_ptr(range.start)) }
230 /// Forms a mutable slice from a pointer range.
232 /// This is the same functionality as [`from_ptr_range`], except that a
233 /// mutable slice is returned.
235 /// This function is useful for interacting with foreign interfaces which
236 /// use two pointers to refer to a range of elements in memory, as is
241 /// Behavior is undefined if any of the following conditions are violated:
243 /// * The `start` pointer of the range must be a [valid] and properly aligned pointer
244 /// to the first element of a slice.
246 /// * The `end` pointer must be a [valid] and properly aligned pointer to *one past*
247 /// the last element, such that the offset from the end to the start pointer is
248 /// the length of the slice.
250 /// * The range must contain `N` consecutive properly initialized values of type `T`:
252 /// * The entire memory range of this slice must be contained within a single allocated object!
253 /// Slices can never span across multiple allocated objects.
255 /// * The memory referenced by the returned slice must not be accessed through any other pointer
256 /// (not derived from the return value) for the duration of lifetime `'a`.
257 /// Both read and write accesses are forbidden.
259 /// * The total length of the range must be no larger than `isize::MAX`.
260 /// See the safety documentation of [`pointer::offset`].
262 /// Note that a range created from [`slice::as_mut_ptr_range`] fulfills these requirements.
266 /// This function panics if `T` is a Zero-Sized Type (“ZST”).
270 /// The lifetime for the returned slice is inferred from its usage. To
271 /// prevent accidental misuse, it's suggested to tie the lifetime to whichever
272 /// source lifetime is safe in the context, such as by providing a helper
273 /// function taking the lifetime of a host value for the slice, or by explicit
279 /// #![feature(slice_from_ptr_range)]
283 /// let mut x = [1, 2, 3];
284 /// let range = x.as_mut_ptr_range();
287 /// assert_eq!(slice::from_mut_ptr_range(range), &mut [1, 2, 3]);
291 /// [valid]: ptr#safety
292 #[unstable(feature = "slice_from_ptr_range", issue = "89792")]
293 #[rustc_const_unstable(feature = "const_slice_from_mut_ptr_range", issue = "89792")]
294 pub const unsafe fn from_mut_ptr_range<'a, T>(range: Range<*mut T>) -> &'a mut [T] {
295 // SAFETY: the caller must uphold the safety contract for `from_mut_ptr_range`.
296 unsafe { from_raw_parts_mut(range.start, range.end.sub_ptr(range.start)) }