Correctly document is_null CTFE behavior.

The "panic in const if CTFE doesn't know the answer" behavior was discussed to be the desired behavior in #74939, and is currently how the function actually behaves.

I intentionally wrote this documentation to allow for the possibility that a panic might not occur even if the pointer is out of bounds, because of #133700 and other potential changes in the future.

(cherry picked from commit 93889172bc)
This commit is contained in:
Tim (Theemathas) Chirananthavat 2024-12-15 12:37:14 +07:00 committed by Josh Stone
parent dc1a9f275c
commit 4171701e39
2 changed files with 20 additions and 14 deletions

View file

@ -12,14 +12,17 @@ impl<T: ?Sized> *const T {
/// Therefore, two pointers that are null may still not compare equal to /// Therefore, two pointers that are null may still not compare equal to
/// each other. /// each other.
/// ///
/// ## Behavior during const evaluation /// # Panics during const evaluation
/// ///
/// When this function is used during const evaluation, it may return `false` for pointers /// If this method is used during const evaluation, and `self` is a pointer
/// that turn out to be null at runtime. Specifically, when a pointer to some memory /// that is offset beyond the bounds of the memory it initially pointed to,
/// is offset beyond its bounds in such a way that the resulting pointer is null, /// then there might not be enough information to determine whether the
/// the function will still return `false`. There is no way for CTFE to know /// pointer is null. This is because the absolute address in memory is not
/// the absolute position of that memory, so we cannot tell if the pointer is /// known at compile time. If the nullness of the pointer cannot be
/// null or not. /// determined, this method will panic.
///
/// In-bounds pointers are never null, so the method will never panic for
/// such pointers.
/// ///
/// # Examples /// # Examples
/// ///

View file

@ -12,14 +12,17 @@ impl<T: ?Sized> *mut T {
/// Therefore, two pointers that are null may still not compare equal to /// Therefore, two pointers that are null may still not compare equal to
/// each other. /// each other.
/// ///
/// ## Behavior during const evaluation /// # Panics during const evaluation
/// ///
/// When this function is used during const evaluation, it may return `false` for pointers /// If this method is used during const evaluation, and `self` is a pointer
/// that turn out to be null at runtime. Specifically, when a pointer to some memory /// that is offset beyond the bounds of the memory it initially pointed to,
/// is offset beyond its bounds in such a way that the resulting pointer is null, /// then there might not be enough information to determine whether the
/// the function will still return `false`. There is no way for CTFE to know /// pointer is null. This is because the absolute address in memory is not
/// the absolute position of that memory, so we cannot tell if the pointer is /// known at compile time. If the nullness of the pointer cannot be
/// null or not. /// determined, this method will panic.
///
/// In-bounds pointers are never null, so the method will never panic for
/// such pointers.
/// ///
/// # Examples /// # Examples
/// ///