raw.rs - source
Description: Source of the Rust file `library/core/src/slice/raw.rs`.

#
core/slice/
raw.rs

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