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