Tracking Issue for convenience methods on `NonNull`

[WaffleLapkin]

Feature gate: #![feature(non_null_convenience)]

This is a tracking issue for convenience methods on NonNull.

Public API

// core::ptr

impl<T: Sized> NonNull<T> {
    pub const unsafe fn offset(self, count: isize) -> NonNull<T>;
    pub const unsafe fn add(self, count: usize) -> NonNull<T>;
    pub const unsafe fn sub(self, count: usize) -> NonNull<T>;

    pub const unsafe fn offset_from(self, origin: NonNull<T>) -> isize;
    pub const unsafe fn sub_ptr(self, subtracted: NonNull<T>) -> usize;

    pub const unsafe fn read(self) -> T;
    pub unsafe fn read_volatile(self) -> T;
    pub const unsafe fn read_unaligned(self) -> T;

    pub const unsafe fn copy_to(self, dest: NonNull<T>, count: usize);
    pub const unsafe fn copy_to_nonoverlapping(self, dest: NonNull<T>, count: usize);
    pub const unsafe fn copy_from(self, src: NonNull<T>, count: usize);
    pub const unsafe fn copy_from_nonoverlapping(self, src: NonNull<T>, count: usize);
    pub const unsafe fn write(self, val: T); 
    pub const unsafe fn write_bytes(self, val: u8, count: usize);
    pub unsafe fn write_volatile(self, val: T);
    pub const unsafe fn write_unaligned(self, val: T);
    pub unsafe fn replace(self, src: T) -> T;
    pub const unsafe fn swap(self, with: NonNull<T>);

    pub const fn align_offset(self, align: usize) -> usize;
    pub const fn is_aligned(self) -> bool;    
}
    
impl<T: ?Sized> NonNull<T> {
    pub const unsafe fn byte_offset(self, count: isize) -> NonNull<T>;
    pub const unsafe fn byte_add(self, count: usize) -> NonNull<T>;
    pub const unsafe fn byte_sub(self, count: usize) -> NonNull<T>;

    pub const unsafe fn byte_offset_from<U: ?Sized>(self, origin: NonNull<U>) -> isize;

    pub unsafe fn drop_in_place(self);

    pub const fn is_aligned_to(self, align: usize) -> bool;
}

(I'll fill the API once PR is merged, stand-by...)

Steps / History

• ACP: Expose add/sub/sub_ptr on NonNull libs-team#251
• Implementation: Non null convenience ops #117697
• Final comment period (FCP)¹
• Stabilization PR

Unresolved Questions

• None yet.

Footnotes

1. https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html ↩

[tgross35]

These haven't been around super long but seem uncontroversial. Any opposition to moving toward stabilization?

[Amanieu]

This exposes methods on NonNull that are also available on raw pointer types, which makes NonNull more ergonomic to use.

@rfcbot fcp merge

[rfcbot]

Team member @Amanieu has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[dtolnay]

Please make sure is_aligned_to is not included in the stabilization. That's unstable on raw pointers still.

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔