constptr 0.3.1

#![doc = include_str!("../README.md")]
#![warn(clippy::cargo_common_metadata)]
#![warn(clippy::doc_markdown)]
#![warn(clippy::missing_panics_doc)]
#![warn(clippy::must_use_candidate)]
#![warn(clippy::semicolon_if_nothing_returned)]
#![warn(missing_docs)]
#![warn(rustdoc::missing_crate_level_docs)]
#![cfg_attr(not(feature = "std"), no_std)]

use core::cmp::Ordering;
use core::ptr::*;
use core::num::NonZeroUsize;

/// A pointer that references immutable data and is never `Null`.
#[repr(transparent)]
pub struct ConstPtr<T: ?Sized>(NonNull<T>);

/// `ConstPtr` pointers can be `Send` because they are constant.
unsafe impl<T: ?Sized + Send> Send for ConstPtr<T> {}

/// `ConstPtr` pointers can be `Sync` because they are constant.
unsafe impl<T: ?Sized + Send + Sync> Sync for ConstPtr<T> {}

impl<T: ?Sized> ConstPtr<T> {
    /// Creates a new `ConstPtr`. This is a const fn.
    ///
    /// # Safety
    ///
    /// `ptr` must be non-null.
    ///
    /// # Examples
    ///
    /// ```
    /// use constptr::ConstPtr;
    ///
    /// static x: u32 = 0u32;
    /// let ptr = unsafe { ConstPtr::new_unchecked(&x) };
    /// ```
    #[inline]
    pub const unsafe fn new_unchecked(ptr: *const T) -> Self {
        debug_assert!(!ptr.is_null(), "passed null pointer to ConstPtr::new_unchecked()");
        // SAFETY: the caller must guarantee that `ptr` is non-null.
        ConstPtr(core::mem::transmute::<*const T, NonNull<T>>(ptr))
    }

    /// Creates a new `ConstPtr` from a reference which makes it safe. This is a const fn.
    /// # Examples
    ///
    /// ```
    /// use constptr::ConstPtr;
    ///
    /// static x: u32 = 0u32;
    /// let ptr = ConstPtr::from(&x);
    /// ```
    // use this until const From becomes stable
    #[inline]
    pub const fn from(reference: &T) -> Self {
        // SAFETY: references are always valid pointers
        unsafe { ConstPtr::new_unchecked(reference) }
    }

    /// Creates a new `ConstPtr` if `ptr` is non-null.
    ///
    /// # Examples
    ///
    /// ```
    /// use constptr::ConstPtr;
    ///
    /// let x = 0u32;
    /// let ptr = ConstPtr::new(&x).expect("ptr is null!");
    ///
    /// if let Some(ptr) = ConstPtr::new(std::ptr::null::<u32>()) {
    ///     unreachable!();
    /// }
    /// ```
    // TODO: const fn once ptr.is_null() in const context is stable
    #[inline]
    #[allow(clippy::not_unsafe_ptr_arg_deref)]
    pub fn new(ptr: *const T) -> Option<Self> {
        if !ptr.is_null() {
            // SAFETY: The pointer is already checked and is not null
            Some(unsafe { ConstPtr(core::mem::transmute::<*const T, NonNull<T>>(ptr)) })
        } else {
            None
        }
    }

    // /// Performs the same functionality as [`std::ptr::from_raw_parts`], except that a
    // /// `ConstPtr` pointer is returned, as opposed to a raw `*const` pointer.
    // ///
    // /// See the documentation of [`std::ptr::from_raw_parts`] for more details.
    // ///
    // /// [`std::ptr::from_raw_parts`]: crate::ptr::from_raw_parts
    // TODO: when stable #[unstable(feature = "ptr_metadata", issue = "81513")]
    // #[inline]
    // pub const fn from_raw_parts(
    //     data_address: ConstPtr<()>,
    //     metadata: <T as super::Pointee>::Metadata,
    // ) -> ConstPtr<T> {
    //     // SAFETY: The result of `ptr::from::raw_parts_mut` is non-null because `data_address` is.
    //     unsafe {
    //         ConstPtr::new_unchecked(super::from_raw_parts_mut(data_address.as_ptr(), metadata))
    //     }
    // }

    // /// Decompose a (possibly wide) pointer into its address and metadata components.
    // ///
    // /// The pointer can be later reconstructed with [`ConstPtr::from_raw_parts`].
    // TODO: when stable #[unstable(feature = "ptr_metadata", issue = "81513")]
    // #[must_use = "this returns the result of the operation, \
    //               without modifying the original"]
    // #[inline]
    // pub const fn to_raw_parts(self) -> (ConstPtr<()>, <T as super::Pointee>::Metadata) {
    //     (self.cast(), super::metadata(self.as_ptr()))
    // }

    /// Gets the "address" portion of the pointer.
    ///
    /// For more details see the equivalent method on a raw pointer `pointer::addr`.
    #[must_use]
    #[inline]
    pub fn addr(self) -> NonZeroUsize
    {
        self.0.addr()
    }

    // /// Creates a new pointer with the given address.
    // ///
    // /// For more details see the equivalent method on a raw pointer, [`pointer::with_addr`].
    // ///
    // /// This API and its claimed semantics are part of the Strict Provenance experiment,
    // /// see the [`ptr` module documentation][crate::ptr].
    // #[must_use]
    // #[inline]
    // TODO: when stable #[unstable(feature = "strict_provenance", issue = "95228")]
    // pub fn with_addr(self, addr: NonZeroUsize) -> Self
    // where
    //     T: Sized,
    // {
    //     // SAFETY: The result of `ptr::from::with_addr` is non-null because `addr` is guaranteed to be non-zero.
    //     unsafe { ConstPtr::new_unchecked(self.pointer.with_addr(addr.get()) as *const _) }
    // }

    // /// Creates a new pointer by mapping `self`'s address to a new one.
    // ///
    // /// For more details see the equivalent method on a raw pointer, [`pointer::map_addr`].
    // ///
    // /// This API and its claimed semantics are part of the Strict Provenance experiment,
    // /// see the [`ptr` module documentation][crate::ptr].
    // #[must_use]
    // #[inline]
    // TODO: when stable #[unstable(feature = "strict_provenance", issue = "95228")]
    // pub fn map_addr(self, f: impl FnOnce(NonZeroUsize) -> NonZeroUsize) -> Self
    // where
    //     T: Sized,
    // {
    //     self.with_addr(f(self.addr()))
    // }

    /// Acquires the underlying `*const` pointer.
    ///
    /// # Examples
    ///
    /// ```
    /// use constptr::ConstPtr;
    ///
    /// let mut x = 0u32;
    /// let ptr = ConstPtr::new(&mut x).expect("ptr is null!");
    ///
    /// let x_value = unsafe { *ptr.as_ptr() };
    /// assert_eq!(x_value, 0);
    /// ```
    #[must_use]
    #[inline(always)]
    pub const fn as_ptr(self) -> *const T {
        self.0.as_ptr()
    }

    /// Returns a shared reference to the value.
    ///
    /// # Safety
    ///
    /// When calling this method, you have to ensure that all of the following is true:
    ///
    /// * The pointer must be properly aligned.
    ///
    /// * It must be "dereferenceable".
    ///
    /// * The pointer must point to an initialized instance of `T`.
    ///
    /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
    ///   arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
    ///   In particular, while this reference exists, the memory the pointer points to must
    ///   not get mutated (except inside `UnsafeCell`).
    ///
    /// This applies even if the result of this method is unused!
    /// (The part about being initialized is not yet fully decided, but until
    /// it is, the only safe approach is to ensure that they are indeed initialized.)
    ///
    /// # Examples
    ///
    /// ```
    /// use constptr::ConstPtr;
    ///
    /// let x = 0u32;
    /// let ptr = ConstPtr::new(&x).expect("ptr is null!");
    ///
    /// let ref_x = unsafe { ptr.as_ref() };
    /// println!("{ref_x}");
    /// ```
    #[must_use]
    #[inline(always)]
    pub const unsafe fn as_ref<'a>(&self) -> &'a T {
        // SAFETY: the caller must guarantee that `self` meets all the
        // requirements for a reference.
        unsafe { &*self.0.as_ptr() }
    }

    /// Casts to a pointer of another type.
    ///
    /// # Examples
    ///
    /// ```
    /// use constptr::ConstPtr;
    ///
    /// let  x = 0u32;
    /// let ptr = ConstPtr::new(&x).expect("null pointer");
    ///
    /// let casted_ptr = ptr.cast::<i8>();
    /// let raw_ptr: *const i8 = casted_ptr.as_ptr();
    /// ```
    #[must_use = "this returns the result of the operation, \
                  without modifying the original"]
    #[inline]
    pub const fn cast<U>(self) -> ConstPtr<U> {
        // SAFETY: `self` is a `ConstPtr` pointer which is necessarily non-null
        unsafe { ConstPtr::new_unchecked(self.as_ptr() as *const U) }
    }
}

// TODO: the whole slices API isn't stable yet
impl<T> ConstPtr<[T]> {
    // /// Creates a non-null raw slice from a thin pointer and a length.
    // ///
    // /// The `len` argument is the number of **elements**, not the number of bytes.
    // ///
    // /// This function is safe, but dereferencing the return value is unsafe.
    // /// See the documentation of [`slice::from_raw_parts`] for slice safety requirements.
    // ///
    // /// # Examples
    // ///
    // /// ```rust
    // /// #![feature(nonnull_slice_from_raw_parts)]
    // ///
    // /// use constptr::ConstPtr;
    // ///
    // /// // create a slice pointer when starting out with a pointer to the first element
    // /// let  x = [5, 6, 7];
    // /// let nonnull_pointer = ConstPtr::new(x.as_mut_ptr()).unwrap();
    // /// let slice = ConstPtr::slice_from_raw_parts(nonnull_pointer, 3);
    // /// assert_eq!(unsafe { slice.as_ref()[2] }, 7);
    // /// ```
    // ///
    // /// (Note that this example artificially demonstrates a use of this method,
    // /// but `let slice = ConstPtr::from(&x[..]);` would be a better way to write code like this.)
    // TODO: when stable  #[unstable(feature = "nonnull_slice_from_raw_parts", issue = "71941")]
    // #[rustc_const_unstable(feature = "const_nonnull_slice_from_raw_parts", issue = "71941")]
    // #[must_use]
    // #[inline]
    // pub const fn slice_from_raw_parts(data: ConstPtr<T>, len: usize) -> Self {
    //     // SAFETY: `data` is a `ConstPtr` pointer which is necessarily non-null
    //     unsafe { Self::new_unchecked(super::slice_from_raw_parts_mut(data.as_ptr(), len)) }
    // }
    //
    // /// Returns the length of a non-null raw slice.
    // ///
    // /// The returned value is the number of **elements**, not the number of bytes.
    // ///
    // /// This function is safe, even when the non-null raw slice cannot be dereferenced to a slice
    // /// because the pointer does not have a valid address.
    // ///
    // /// # Examples
    // ///
    // /// ```rust
    // /// #![feature(nonnull_slice_from_raw_parts)]
    // /// use constptr::ConstPtr;
    // ///
    // /// let slice: ConstPtr<[i8]> = ConstPtr::slice_from_raw_parts(ConstPtr::dangling(), 3);
    // /// assert_eq!(slice.len(), 3);
    // /// ```
    // TODO: when stable #[stable(feature = "slice_ptr_len_nonnull", since = "1.63.0")]
    // #[rustc_const_stable(feature = "const_slice_ptr_len_nonnull", since = "1.63.0")]
    // #[rustc_allow_const_fn_unstable(const_slice_ptr_len)]
    // #[must_use]
    // #[inline]
    // pub const fn len(self) -> usize {
    //     self.as_ptr().len()
    // }
    //
    // /// Returns a non-null pointer to the slice's buffer.
    // ///
    // /// # Examples
    // ///
    // /// ```rust
    // /// #![feature(slice_ptr_get, nonnull_slice_from_raw_parts)]
    // /// use constptr::ConstPtr;
    // ///
    // /// let slice: ConstPtr<[i8]> = ConstPtr::slice_from_raw_parts(ConstPtr::dangling(), 3);
    // /// assert_eq!(slice.as_non_null_ptr(), ConstPtr::<i8>::dangling());
    // /// ```
    // #[inline]
    // #[must_use]
    // TODO: when stable #[unstable(feature = "slice_ptr_get", issue = "74265")]
    // #[rustc_const_unstable(feature = "slice_ptr_get", issue = "74265")]
    // pub const fn as_non_null_ptr(self) -> ConstPtr<T> {
    //     // SAFETY: We know `self` is non-null.
    //     unsafe { ConstPtr::new_unchecked(self.as_ptr().as_mut_ptr()) }
    // }

    // /// Returns a raw pointer to an element or subslice, without doing bounds
    // /// checking.
    // ///
    // /// Calling this method with an out-of-bounds index or when `self` is not dereferenceable
    // /// is *[undefined behavior]* even if the resulting pointer is not used.
    // ///
    // /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
    // ///
    // /// # Examples
    // ///
    // /// ```
    // /// #![feature(slice_ptr_get, nonnull_slice_from_raw_parts)]
    // /// use constptr::ConstPtr;
    // ///
    // /// let x = &mut [1, 2, 4];
    // /// let x = ConstPtr::slice_from_raw_parts(ConstPtr::new(x.as_mut_ptr()).unwrap(), x.len());
    // ///
    // /// unsafe {
    // ///     assert_eq!(x.get_unchecked_mut(1).as_ptr(), x.as_non_null_ptr().as_ptr().add(1));
    // /// }
    // /// ```
    // TODO: when stable #[unstable(feature = "slice_ptr_get", issue = "74265")]
    // #[rustc_const_unstable(feature = "const_slice_index", issue = "none")]
    // #[inline]
    // pub const unsafe fn get_unchecked_mut<I>(self, index: I) -> ConstPtr<I::Output>
    // where
    //     I: ~const SliceIndex<[T]>,
    // {
    //     // SAFETY: the caller ensures that `self` is dereferenceable and `index` in-bounds.
    //     // As a consequence, the resulting pointer cannot be null.
    //     unsafe { ConstPtr::new_unchecked(self.as_ptr().get_unchecked_mut(index)) }
    // }
}

// TODO: when stable #[stable(feature = "nonnull", since = "1.25.0")]
// #[rustc_const_unstable(feature = "const_clone", issue = "91805")]
// impl<T: ?Sized> const Clone for ConstPtr<T> {
//     #[inline(always)]
//     fn clone(&self) -> Self {
//         *self
//     }
// }

// TODO: when stable #[unstable(feature = "coerce_unsized", issue = "27732")]
// impl<T: ?Sized, U: ?Sized> CoerceUnsized<ConstPtr<U>> for ConstPtr<T> where T: Unsize<U> {}

// TODO: when stable  #[unstable(feature = "dispatch_from_dyn", issue = "none")]
// impl<T: ?Sized, U: ?Sized> DispatchFromDyn<ConstPtr<U>> for ConstPtr<T> where T: Unsize<U> {}

impl<T: ?Sized> Copy for ConstPtr<T> {}

impl<T: ?Sized> Clone for ConstPtr<T> {
    #[inline(always)]
    fn clone(&self) -> Self {
        *self
    }
}

impl<T: ?Sized> core::fmt::Pointer for ConstPtr<T> {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        core::fmt::Pointer::fmt(&self.as_ptr(), f)
    }
}

impl<T: ?Sized> core::fmt::Debug for ConstPtr<T> {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        core::fmt::Pointer::fmt(&self.as_ptr(), f)
    }
}

impl<T: ?Sized> Eq for ConstPtr<T> {}

impl<T: ?Sized> PartialEq for ConstPtr<T> {
    #[inline]
    fn eq(&self, other: &Self) -> bool {
        addr_eq(self.as_ptr(), other.as_ptr())
    }
}

impl<T: ?Sized> Ord for ConstPtr<T> {
    #[inline]
    fn cmp(&self, other: &Self) -> Ordering {
        self.addr().cmp(&other.addr())
    }
}

impl<T: ?Sized> PartialOrd for ConstPtr<T> {
    #[inline]
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        Some(self.cmp(other))
    }
}

#[cfg(feature = "std")]
impl<T: ?Sized> std::hash::Hash for ConstPtr<T> {
    #[inline]
    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
        self.as_ptr().hash(state);
    }
}

// TODO: when stable #[unstable(feature = "ptr_internals", issue = "none")]
// #[rustc_const_unstable(feature = "const_convert", issue = "88674")]
// impl<T: ?Sized> const From<Unique<T>> for ConstPtr<T> {
//     #[inline]
//     fn from(unique: Unique<T>) -> Self {
//         // SAFETY: A Unique pointer cannot be null, so the conditions for
//         // new_unchecked() are respected.
//         unsafe { ConstPtr::new_unchecked(unique.as_ptr()) }
//     }
// }

// TODO: impl<T: ?Sized> const From<&mut T> for ConstPtr<T> {
impl<T: ?Sized> From<&mut T> for ConstPtr<T> {
    /// Converts a `&mut T` to a `ConstPtr<T>`.
    ///
    /// This conversion is safe and infallible since references cannot be null.
    ///
    /// # Safety
    ///
    /// Creating a `ConstPtr` from a mutable reference is safe. However, you must ensure that
    /// the `ConstPtr` is not used while the mutable reference is still in use. The other
    /// safety requirements for `ConstPtr` still apply. Eg the object must still be valid at
    /// the time of dereferencing, even after the mutable reference is dropped.
    #[inline]
    fn from(reference: &mut T) -> Self {
        ConstPtr::from(reference)
    }
}

// TODO: impl<T: ?Sized> const From<&T> for ConstPtr<T> {
impl<T: ?Sized> From<&T> for ConstPtr<T> {
    /// Converts a `&T` to a `ConstPtr<T>`.
    ///
    /// This conversion is safe and infallible since references cannot be null.
    #[inline]
    fn from(reference: &T) -> Self {
        ConstPtr::from(reference)
    }
}