]> git.proxmox.com Git - rustc.git/blame - library/core/src/slice/raw.rs
New upstream version 1.63.0+dfsg1
[rustc.git] / library / core / src / slice / raw.rs
CommitLineData
1b1a35ee
XL
1//! Free functions to create `&[T]` and `&mut [T]`.
2
3use crate::array;
5e7ed085
FG
4use crate::intrinsics::{assert_unsafe_precondition, is_aligned_and_not_null};
5use crate::ops::Range;
1b1a35ee
XL
6use crate::ptr;
7
8/// Forms a slice from a pointer and a length.
9///
10/// The `len` argument is the number of **elements**, not the number of bytes.
11///
12/// # Safety
13///
14/// Behavior is undefined if any of the following conditions are violated:
15///
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:
18///
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()`].
27///
28/// * `data` must point to `len` consecutive properly initialized values of type `T`.
29///
30/// * The memory referenced by the returned slice must not be mutated for the duration
31/// of lifetime `'a`, except inside an `UnsafeCell`.
32///
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`].
35///
36/// # Caveat
37///
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
42/// annotation.
43///
44/// # Examples
45///
46/// ```
47/// use std::slice;
48///
49/// // manifest a slice for a single element
50/// let x = 42;
51/// let ptr = &x as *const _;
52/// let slice = unsafe { slice::from_raw_parts(ptr, 1) };
53/// assert_eq!(slice[0], 42);
54/// ```
55///
56/// ### Incorrect usage
57///
58/// The following `join_slices` function is **unsound** ⚠️
59///
60/// ```rust,no_run
61/// use std::slice;
62///
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!");
67/// unsafe {
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())
72/// }
73/// }
74///
75/// fn main() {
76/// // `a` and `b` are different allocated objects...
77/// let a = 42;
78/// let b = 27;
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
81/// }
82/// ```
83///
84/// [valid]: ptr#safety
85/// [`NonNull::dangling()`]: ptr::NonNull::dangling
1b1a35ee
XL
86#[inline]
87#[stable(feature = "rust1", since = "1.0.0")]
3c0e092e 88#[rustc_const_unstable(feature = "const_slice_from_raw_parts", issue = "67456")]
5e7ed085 89#[must_use]
3c0e092e 90pub const unsafe fn from_raw_parts<'a, T>(data: *const T, len: usize) -> &'a [T] {
1b1a35ee 91 // SAFETY: the caller must uphold the safety contract for `from_raw_parts`.
5e7ed085
FG
92 unsafe {
93 assert_unsafe_precondition!(
94 is_aligned_and_not_null(data)
95 && crate::mem::size_of::<T>().saturating_mul(len) <= isize::MAX as usize
96 );
97 &*ptr::slice_from_raw_parts(data, len)
98 }
1b1a35ee
XL
99}
100
101/// Performs the same functionality as [`from_raw_parts`], except that a
102/// mutable slice is returned.
103///
104/// # Safety
105///
106/// Behavior is undefined if any of the following conditions are violated:
107///
5869c6ff 108/// * `data` must be [valid] for both reads and writes for `len * mem::size_of::<T>()` many bytes,
1b1a35ee
XL
109/// and it must be properly aligned. This means in particular:
110///
111/// * The entire memory range of this slice must be contained within a single allocated object!
112/// Slices can never span across multiple allocated objects.
113/// * `data` must be non-null and aligned even for zero-length slices. One
114/// reason for this is that enum layout optimizations may rely on references
115/// (including slices of any length) being aligned and non-null to distinguish
116/// them from other data. You can obtain a pointer that is usable as `data`
117/// for zero-length slices using [`NonNull::dangling()`].
118///
119/// * `data` must point to `len` consecutive properly initialized values of type `T`.
120///
121/// * The memory referenced by the returned slice must not be accessed through any other pointer
122/// (not derived from the return value) for the duration of lifetime `'a`.
123/// Both read and write accesses are forbidden.
124///
125/// * The total size `len * mem::size_of::<T>()` of the slice must be no larger than `isize::MAX`.
126/// See the safety documentation of [`pointer::offset`].
127///
128/// [valid]: ptr#safety
129/// [`NonNull::dangling()`]: ptr::NonNull::dangling
1b1a35ee
XL
130#[inline]
131#[stable(feature = "rust1", since = "1.0.0")]
3c0e092e 132#[rustc_const_unstable(feature = "const_slice_from_raw_parts", issue = "67456")]
5e7ed085 133#[must_use]
3c0e092e 134pub const unsafe fn from_raw_parts_mut<'a, T>(data: *mut T, len: usize) -> &'a mut [T] {
1b1a35ee 135 // SAFETY: the caller must uphold the safety contract for `from_raw_parts_mut`.
3c0e092e 136 unsafe {
5e7ed085
FG
137 assert_unsafe_precondition!(
138 is_aligned_and_not_null(data)
139 && crate::mem::size_of::<T>().saturating_mul(len) <= isize::MAX as usize
140 );
141 &mut *ptr::slice_from_raw_parts_mut(data, len)
3c0e092e 142 }
3c0e092e
XL
143}
144
1b1a35ee
XL
145/// Converts a reference to T into a slice of length 1 (without copying).
146#[stable(feature = "from_ref", since = "1.28.0")]
923072b8 147#[rustc_const_stable(feature = "const_slice_from_ref_shared", since = "1.63.0")]
5e7ed085 148#[must_use]
3c0e092e 149pub const fn from_ref<T>(s: &T) -> &[T] {
1b1a35ee
XL
150 array::from_ref(s)
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")]
3c0e092e 155#[rustc_const_unstable(feature = "const_slice_from_ref", issue = "90206")]
5e7ed085 156#[must_use]
3c0e092e 157pub const fn from_mut<T>(s: &mut T) -> &mut [T] {
1b1a35ee
XL
158 array::from_mut(s)
159}
5e7ed085
FG
160
161/// Forms a slice from a pointer range.
162///
163/// This function is useful for interacting with foreign interfaces which
164/// use two pointers to refer to a range of elements in memory, as is
165/// common in C++.
166///
167/// # Safety
168///
169/// Behavior is undefined if any of the following conditions are violated:
170///
171/// * The `start` pointer of the range must be a [valid] and properly aligned pointer
172/// to the first element of a slice.
173///
174/// * The `end` pointer must be a [valid] and properly aligned pointer to *one past*
175/// the last element, such that the offset from the end to the start pointer is
176/// the length of the slice.
177///
178/// * The range must contain `N` consecutive properly initialized values of type `T`:
179///
180/// * The entire memory range of this slice must be contained within a single allocated object!
181/// Slices can never span across multiple allocated objects.
182///
183/// * The memory referenced by the returned slice must not be mutated for the duration
184/// of lifetime `'a`, except inside an `UnsafeCell`.
185///
186/// * The total length of the range must be no larger than `isize::MAX`.
187/// See the safety documentation of [`pointer::offset`].
188///
189/// Note that a range created from [`slice::as_ptr_range`] fulfills these requirements.
190///
191/// # Caveat
192///
193/// The lifetime for the returned slice is inferred from its usage. To
194/// prevent accidental misuse, it's suggested to tie the lifetime to whichever
195/// source lifetime is safe in the context, such as by providing a helper
196/// function taking the lifetime of a host value for the slice, or by explicit
197/// annotation.
198///
199/// # Examples
200///
201/// ```
202/// #![feature(slice_from_ptr_range)]
203///
204/// use core::slice;
205///
206/// let x = [1, 2, 3];
207/// let range = x.as_ptr_range();
208///
209/// unsafe {
210/// assert_eq!(slice::from_ptr_range(range), &x);
211/// }
212/// ```
213///
214/// [valid]: ptr#safety
215#[unstable(feature = "slice_from_ptr_range", issue = "89792")]
923072b8
FG
216#[rustc_const_unstable(feature = "const_slice_from_ptr_range", issue = "89792")]
217pub const unsafe fn from_ptr_range<'a, T>(range: Range<*const T>) -> &'a [T] {
5e7ed085 218 // SAFETY: the caller must uphold the safety contract for `from_ptr_range`.
04454e1e 219 unsafe { from_raw_parts(range.start, range.end.sub_ptr(range.start)) }
5e7ed085
FG
220}
221
222/// Performs the same functionality as [`from_ptr_range`], except that a
223/// mutable slice is returned.
224///
225/// # Safety
226///
227/// Behavior is undefined if any of the following conditions are violated:
228///
229/// * The `start` pointer of the range must be a [valid] and properly aligned pointer
230/// to the first element of a slice.
231///
232/// * The `end` pointer must be a [valid] and properly aligned pointer to *one past*
233/// the last element, such that the offset from the end to the start pointer is
234/// the length of the slice.
235///
236/// * The range must contain `N` consecutive properly initialized values of type `T`:
237///
238/// * The entire memory range of this slice must be contained within a single allocated object!
239/// Slices can never span across multiple allocated objects.
240///
241/// * The memory referenced by the returned slice must not be accessed through any other pointer
242/// (not derived from the return value) for the duration of lifetime `'a`.
243/// Both read and write accesses are forbidden.
244///
245/// * The total length of the range must be no larger than `isize::MAX`.
246/// See the safety documentation of [`pointer::offset`].
247///
248/// Note that a range created from [`slice::as_mut_ptr_range`] fulfills these requirements.
249///
250/// # Examples
251///
252/// ```
253/// #![feature(slice_from_ptr_range)]
254///
255/// use core::slice;
256///
257/// let mut x = [1, 2, 3];
258/// let range = x.as_mut_ptr_range();
259///
260/// unsafe {
261/// assert_eq!(slice::from_mut_ptr_range(range), &mut [1, 2, 3]);
262/// }
263/// ```
264///
265/// [valid]: ptr#safety
266#[unstable(feature = "slice_from_ptr_range", issue = "89792")]
923072b8
FG
267#[rustc_const_unstable(feature = "const_slice_from_mut_ptr_range", issue = "89792")]
268pub const unsafe fn from_mut_ptr_range<'a, T>(range: Range<*mut T>) -> &'a mut [T] {
5e7ed085 269 // SAFETY: the caller must uphold the safety contract for `from_mut_ptr_range`.
04454e1e 270 unsafe { from_raw_parts_mut(range.start, range.end.sub_ptr(range.start)) }
5e7ed085 271}