library/core/src/slice/raw.rs

   1 //! Free functions to create `&[T]` and `&mut [T]`.
   2
   3 use crate::array;
   4 use crate::intrinsics::{
   5     assert_unsafe_precondition, is_aligned_and_not_null, is_valid_allocation_size,
   6 };
   7 use crate::ops::Range;
   8 use 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 ///   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 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`.
  94     unsafe {
  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)
  99         );
 100         &*ptr::slice_from_raw_parts(data, len)
 101     }
 102 }
 103
 104 /// Performs the same functionality as [`from_raw_parts`], except that a
 105 /// mutable slice is returned.
 106 ///
 107 /// # Safety
 108 ///
 109 /// Behavior is undefined if any of the following conditions are violated:
 110 ///
 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:
 113 ///
 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()`].
 121 ///
 122 /// * `data` must point to `len` consecutive properly initialized values of type `T`.
 123 ///
 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.
 127 ///
 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`].
 130 ///
 131 /// [valid]: ptr#safety
 132 /// [`NonNull::dangling()`]: ptr::NonNull::dangling
 133 #[inline]
 134 #[stable(feature = "rust1", since = "1.0.0")]
 135 #[rustc_const_unstable(feature = "const_slice_from_raw_parts_mut", issue = "67456")]
 136 #[must_use]
 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`.
 139     unsafe {
 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)
 144         );
 145         &mut *ptr::slice_from_raw_parts_mut(data, len)
 146     }
 147 }
 148
 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")]
 152 #[must_use]
 153 pub const fn from_ref<T>(s: &T) -> &[T] {
 154     array::from_ref(s)
 155 }
 156
 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")]
 160 #[must_use]
 161 pub const fn from_mut<T>(s: &mut T) -> &mut [T] {
 162     array::from_mut(s)
 163 }
 164
 165 /// Forms a slice from a pointer range.
 166 ///
 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
 169 /// common in C++.
 170 ///
 171 /// # Safety
 172 ///
 173 /// Behavior is undefined if any of the following conditions are violated:
 174 ///
 175 /// * The `start` pointer of the range must be a [valid] and properly aligned pointer
 176 ///   to the first element of a slice.
 177 ///
 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.
 181 ///
 182 /// * The range must contain `N` consecutive properly initialized values of type `T`:
 183 ///
 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.
 186 ///
 187 /// * The memory referenced by the returned slice must not be mutated for the duration
 188 ///   of lifetime `'a`, except inside an `UnsafeCell`.
 189 ///
 190 /// * The total length of the range must be no larger than `isize::MAX`.
 191 ///   See the safety documentation of [`pointer::offset`].
 192 ///
 193 /// Note that a range created from [`slice::as_ptr_range`] fulfills these requirements.
 194 ///
 195 /// # Panics
 196 ///
 197 /// This function panics if `T` is a Zero-Sized Type (“ZST”).
 198 ///
 199 /// # Caveat
 200 ///
 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
 205 /// annotation.
 206 ///
 207 /// # Examples
 208 ///
 209 /// ```
 210 /// #![feature(slice_from_ptr_range)]
 211 ///
 212 /// use core::slice;
 213 ///
 214 /// let x = [1, 2, 3];
 215 /// let range = x.as_ptr_range();
 216 ///
 217 /// unsafe {
 218 ///     assert_eq!(slice::from_ptr_range(range), &x);
 219 /// }
 220 /// ```
 221 ///
 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)) }
 228 }
 229
 230 /// Forms a mutable slice from a pointer range.
 231 ///
 232 /// This is the same functionality as [`from_ptr_range`], except that a
 233 /// mutable slice is returned.
 234 ///
 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
 237 /// common in C++.
 238 ///
 239 /// # Safety
 240 ///
 241 /// Behavior is undefined if any of the following conditions are violated:
 242 ///
 243 /// * The `start` pointer of the range must be a [valid] and properly aligned pointer
 244 ///   to the first element of a slice.
 245 ///
 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.
 249 ///
 250 /// * The range must contain `N` consecutive properly initialized values of type `T`:
 251 ///
 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.
 254 ///
 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.
 258 ///
 259 /// * The total length of the range must be no larger than `isize::MAX`.
 260 ///   See the safety documentation of [`pointer::offset`].
 261 ///
 262 /// Note that a range created from [`slice::as_mut_ptr_range`] fulfills these requirements.
 263 ///
 264 /// # Panics
 265 ///
 266 /// This function panics if `T` is a Zero-Sized Type (“ZST”).
 267 ///
 268 /// # Caveat
 269 ///
 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
 274 /// annotation.
 275 ///
 276 /// # Examples
 277 ///
 278 /// ```
 279 /// #![feature(slice_from_ptr_range)]
 280 ///
 281 /// use core::slice;
 282 ///
 283 /// let mut x = [1, 2, 3];
 284 /// let range = x.as_mut_ptr_range();
 285 ///
 286 /// unsafe {
 287 ///     assert_eq!(slice::from_mut_ptr_range(range), &mut [1, 2, 3]);
 288 /// }
 289 /// ```
 290 ///
 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)) }
 297 }