1//! Free functions to create `&[T]` and `&mut [T]`.
2
3use crate::array;
4use crate::intrinsics::{
5 assert_unsafe_precondition, is_aligned_and_not_null, is_valid_allocation_size,
6};
7use crate::ops::Range;
8use 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"]
94pub 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"]
141pub 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]
157pub 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]
165pub 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")]
230pub 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")]
300pub 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