library/core/src/slice/raw.rs

   1 //! Free functions to create `&[T]` and `&mut [T]`.
   2
   3 use crate::array;
   4 use crate::intrinsics::{assert_unsafe_precondition, is_aligned_and_not_null};
   5 use crate::ops::Range;
   6 use 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
  86 #[inline]
  87 #[stable(feature = "rust1", since = "1.0.0")]
  88 #[rustc_const_stable(feature = "const_slice_from_raw_parts", since = "1.64.0")]
  89 #[must_use]
  90 pub const unsafe fn from_raw_parts<'a, T>(data: *const T, len: usize) -> &'a [T] {
  91     // SAFETY: the caller must uphold the safety contract for `from_raw_parts`.
  92     unsafe {
  93         assert_unsafe_precondition!([T](data: *const T, len: usize) =>
  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     }
  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 ///
 108 /// * `data` must be [valid] for both reads and writes for `len * mem::size_of::<T>()` many bytes,
 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
 130 #[inline]
 131 #[stable(feature = "rust1", since = "1.0.0")]
 132 #[rustc_const_unstable(feature = "const_slice_from_raw_parts_mut", issue = "67456")]
 133 #[must_use]
 134 pub const unsafe fn from_raw_parts_mut<'a, T>(data: *mut T, len: usize) -> &'a mut [T] {
 135     // SAFETY: the caller must uphold the safety contract for `from_raw_parts_mut`.
 136     unsafe {
 137         assert_unsafe_precondition!([T](data: *mut T, len: usize) =>
 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)
 142     }
 143 }
 144
 145 /// Converts a reference to T into a slice of length 1 (without copying).
 146 #[stable(feature = "from_ref", since = "1.28.0")]
 147 #[rustc_const_stable(feature = "const_slice_from_ref_shared", since = "1.63.0")]
 148 #[must_use]
 149 pub const fn from_ref<T>(s: &T) -> &[T] {
 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")]
 155 #[rustc_const_unstable(feature = "const_slice_from_ref", issue = "90206")]
 156 #[must_use]
 157 pub const fn from_mut<T>(s: &mut T) -> &mut [T] {
 158     array::from_mut(s)
 159 }
 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 /// # Panics
 192 ///
 193 /// This function panics if `T` is a Zero-Sized Type (“ZST”).
 194 ///
 195 /// # Caveat
 196 ///
 197 /// The lifetime for the returned slice is inferred from its usage. To
 198 /// prevent accidental misuse, it's suggested to tie the lifetime to whichever
 199 /// source lifetime is safe in the context, such as by providing a helper
 200 /// function taking the lifetime of a host value for the slice, or by explicit
 201 /// annotation.
 202 ///
 203 /// # Examples
 204 ///
 205 /// ```
 206 /// #![feature(slice_from_ptr_range)]
 207 ///
 208 /// use core::slice;
 209 ///
 210 /// let x = [1, 2, 3];
 211 /// let range = x.as_ptr_range();
 212 ///
 213 /// unsafe {
 214 ///     assert_eq!(slice::from_ptr_range(range), &x);
 215 /// }
 216 /// ```
 217 ///
 218 /// [valid]: ptr#safety
 219 #[unstable(feature = "slice_from_ptr_range", issue = "89792")]
 220 #[rustc_const_unstable(feature = "const_slice_from_ptr_range", issue = "89792")]
 221 pub const unsafe fn from_ptr_range<'a, T>(range: Range<*const T>) -> &'a [T] {
 222     // SAFETY: the caller must uphold the safety contract for `from_ptr_range`.
 223     unsafe { from_raw_parts(range.start, range.end.sub_ptr(range.start)) }
 224 }
 225
 226 /// Forms a mutable slice from a pointer range.
 227 ///
 228 /// This is the same functionality as [`from_ptr_range`], except that a
 229 /// mutable slice is returned.
 230 ///
 231 /// This function is useful for interacting with foreign interfaces which
 232 /// use two pointers to refer to a range of elements in memory, as is
 233 /// common in C++.
 234 ///
 235 /// # Safety
 236 ///
 237 /// Behavior is undefined if any of the following conditions are violated:
 238 ///
 239 /// * The `start` pointer of the range must be a [valid] and properly aligned pointer
 240 ///   to the first element of a slice.
 241 ///
 242 /// * The `end` pointer must be a [valid] and properly aligned pointer to *one past*
 243 ///   the last element, such that the offset from the end to the start pointer is
 244 ///   the length of the slice.
 245 ///
 246 /// * The range must contain `N` consecutive properly initialized values of type `T`:
 247 ///
 248 ///     * The entire memory range of this slice must be contained within a single allocated object!
 249 ///       Slices can never span across multiple allocated objects.
 250 ///
 251 /// * The memory referenced by the returned slice must not be accessed through any other pointer
 252 ///   (not derived from the return value) for the duration of lifetime `'a`.
 253 ///   Both read and write accesses are forbidden.
 254 ///
 255 /// * The total length of the range must be no larger than `isize::MAX`.
 256 ///   See the safety documentation of [`pointer::offset`].
 257 ///
 258 /// Note that a range created from [`slice::as_mut_ptr_range`] fulfills these requirements.
 259 ///
 260 /// # Panics
 261 ///
 262 /// This function panics if `T` is a Zero-Sized Type (“ZST”).
 263 ///
 264 /// # Caveat
 265 ///
 266 /// The lifetime for the returned slice is inferred from its usage. To
 267 /// prevent accidental misuse, it's suggested to tie the lifetime to whichever
 268 /// source lifetime is safe in the context, such as by providing a helper
 269 /// function taking the lifetime of a host value for the slice, or by explicit
 270 /// annotation.
 271 ///
 272 /// # Examples
 273 ///
 274 /// ```
 275 /// #![feature(slice_from_ptr_range)]
 276 ///
 277 /// use core::slice;
 278 ///
 279 /// let mut x = [1, 2, 3];
 280 /// let range = x.as_mut_ptr_range();
 281 ///
 282 /// unsafe {
 283 ///     assert_eq!(slice::from_mut_ptr_range(range), &mut [1, 2, 3]);
 284 /// }
 285 /// ```
 286 ///
 287 /// [valid]: ptr#safety
 288 #[unstable(feature = "slice_from_ptr_range", issue = "89792")]
 289 #[rustc_const_unstable(feature = "const_slice_from_mut_ptr_range", issue = "89792")]
 290 pub const unsafe fn from_mut_ptr_range<'a, T>(range: Range<*mut T>) -> &'a mut [T] {
 291     // SAFETY: the caller must uphold the safety contract for `from_mut_ptr_range`.
 292     unsafe { from_raw_parts_mut(range.start, range.end.sub_ptr(range.start)) }
 293 }