Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add <*{const|mut} T>::{to|from}_bits #91127

Merged
merged 2 commits into from
Dec 11, 2021
Merged

Add <*{const|mut} T>::{to|from}_bits #91127

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
875e01e
Add `<*{const|mut} T>::{to|from}_bits`
scottmcm Nov 22, 2021
348a250
Intra-doc links apparently don't like pointers?
scottmcm Nov 22, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 48 additions & 0 deletions library/core/src/ptr/const_ptr.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,54 @@ impl<T: ?Sized> *const T {
self as _
}

/// Casts a pointer to its raw bits.
///
/// This is equivalent to `as usize`, but is more specific to enhance readability.
/// The inverse method is [`from_bits`](#method.from_bits).
///
/// In particular, `*p as usize` and `p as usize` will both compile for
/// pointers to numeric types but do very different things, so using this
/// helps emphasize that reading the bits was intentional.
///
/// # Examples
///
/// ```
/// #![feature(ptr_to_from_bits)]
/// let array = [13, 42];
/// let p0: *const i32 = &array[0];
/// assert_eq!(<*const _>::from_bits(p0.to_bits()), p0);
/// let p1: *const i32 = &array[1];
/// assert_eq!(p1.to_bits() - p0.to_bits(), 4);
/// ```
#[unstable(feature = "ptr_to_from_bits", issue = "91126")]
pub fn to_bits(self) -> usize
where
T: Sized,
{
self as usize
}

/// Creates a pointer from its raw bits.
///
/// This is equivalent to `as *const T`, but is more specific to enhance readability.
/// The inverse method is [`to_bits`](#method.to_bits).
///
/// # Examples
///
/// ```
/// #![feature(ptr_to_from_bits)]
/// use std::ptr::NonNull;
/// let dangling: *const u8 = NonNull::dangling().as_ptr();
/// assert_eq!(<*const u8>::from_bits(1), dangling);
/// ```
#[unstable(feature = "ptr_to_from_bits", issue = "91126")]
pub fn from_bits(bits: usize) -> Self
where
T: Sized,
{
bits as Self
}

/// Decompose a (possibly wide) pointer into its address and metadata components.
///
/// The pointer can be later reconstructed with [`from_raw_parts`].
Expand Down
49 changes: 49 additions & 0 deletions library/core/src/ptr/mut_ptr.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,55 @@ impl<T: ?Sized> *mut T {
self as _
}

/// Casts a pointer to its raw bits.
///
/// This is equivalent to `as usize`, but is more specific to enhance readability.
/// The inverse method is [`from_bits`](#method.from_bits-1).
///
/// In particular, `*p as usize` and `p as usize` will both compile for
/// pointers to numeric types but do very different things, so using this
/// helps emphasize that reading the bits was intentional.
///
/// # Examples
///
/// ```
/// #![feature(ptr_to_from_bits)]
/// let mut array = [13, 42];
/// let mut it = array.iter_mut();
/// let p0: *mut i32 = it.next().unwrap();
/// assert_eq!(<*mut _>::from_bits(p0.to_bits()), p0);
/// let p1: *mut i32 = it.next().unwrap();
/// assert_eq!(p1.to_bits() - p0.to_bits(), 4);
/// ```
#[unstable(feature = "ptr_to_from_bits", issue = "91126")]
pub fn to_bits(self) -> usize
where
T: Sized,
{
self as usize
}

/// Creates a pointer from its raw bits.
///
/// This is equivalent to `as *mut T`, but is more specific to enhance readability.
/// The inverse method is [`to_bits`](#method.to_bits-1).
Copy link
Member

@camelid camelid Nov 24, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note that the number disambiguates between *const and *mut, though I don't know if the number is stable. If you don't want to disambiguate, you can also use [`to_bits`](pointer::to_bits) as an intra-doc link.

Copy link
Member Author

@scottmcm scottmcm Nov 28, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also don't know if it's stable. I put it this way as it worked locally in x.py doc. Based on the zulip conversation there's no great solution right now, so I think I'll just leave it like this. Hopefully one day it can go back to just [`Self::to_bits`].

///
/// # Examples
///
/// ```
/// #![feature(ptr_to_from_bits)]
/// use std::ptr::NonNull;
/// let dangling: *mut u8 = NonNull::dangling().as_ptr();
/// assert_eq!(<*mut u8>::from_bits(1), dangling);
/// ```
#[unstable(feature = "ptr_to_from_bits", issue = "91126")]
pub fn from_bits(bits: usize) -> Self
where
T: Sized,
{
bits as Self
}

/// Decompose a (possibly wide) pointer into its address and metadata components.
///
/// The pointer can be later reconstructed with [`from_raw_parts_mut`].
Expand Down