Tracking Issue for offset_from_unsigned (feature ptr_sub_ptr)

[scottmcm]

Feature gate: #![feature(ptr_sub_ptr)] & #![feature(const_ptr_sub_ptr)]

This is a tracking issue for the <*const _>::sub_ptr & <*mut _>::sub_ptr methods.

This is the produces-usize version of offset_from, the same way that add and sub are the takes-usize versions of offset.

It turns out that people almost always actually know which pointer is greater than which when doing this operation, and would rather a usize instead of an isize -- every use of offset_from in the library was followed with as usize in practice. So like how .add(d) greatly improved code compared to needing .offset(d as isize), being able to use ptr.sub_ptr(origin) instead of ptr.offset_from(origin) as usize is also a major improvement. And Miri can check the unsafety better, too, since if you get the order wrong it'll detect that, unlike happens with the as usize approach.

This also tracks the constness of operations, though with #92980 stabilizing offset_from being const , this being const is likely uncontroversial.

Public API

impl<T> *const T {
    pub const unsafe fn offset_from_unsigned(self, origin: *const T) -> usize;
    pub const unsafe fn byte_offset_from_unsigned<U>(self, origin: *const U) -> usize;
}

impl<T> *mut T {
    pub const unsafe fn offset_from_unsigned(self, origin: *const T) -> usize;
    pub const unsafe fn byte_offset_from_unsigned<U>(self, origin: *const U) -> usize;
}

impl <T> NonNull<T> {
    pub const unsafe fn offset_from_unsigned(self, subtracted: NonNull<T>) -> usize;
    pub const unsafe fn byte_offset_from_unsigned<U>(self, origin: NonNull<U>) -> usize;
}

Steps / History

• Implementation: Add sub_ptr on pointers (the usize version of offset_from) #95837
• Move the NonNull method to this gate Stabilize non_null_convenience #124498
• Final comment period (FCP)
• Stabilization PR
  • stabilize (const_)ptr_sub_ptr #137121
  • rename sub_ptr to offset_from_unsigned #137483

Unresolved Questions

• This uses the terminology of subtraction to match the existing add and sub methods, but there might be another name that would be more evocative for people Add sub_ptr on pointers (the usize version of offset_from) #95837 (comment)

[Stargateur]

I will always prefer this to the use of isize. The name is very generic. Thus I don't have better idea. Maybe usize_from or distance_from. I don't like the order of parameter but guess it's too late for pointer.

[Stargateur]

I also wonder if we could just say this doesn't panic but just return the absolute since we assert the greater than equal why not just make it return absolute ? this would cost nothing more and would remove the burden for dev to think about order, and we could just call this distance().

[scottmcm]

I would be strongly against this returning the absolute difference between the pointers. Part of the value of this API is that it's more efficient than offset_from -- that's why slice iterators were open-coding this before the function existed -- and if it needed to do tests for ordering it would no longer be that.

Adding a separate absolute difference API for pointers might make sense, like the integers have, but it wouldn't be a serviceable replacement for the current sub_ptr. (#106393 wouldn't use an absolute difference version, for example.)

(Oh, and as prior art, std::distance in C++ isn't an absolute distance either, so calling it distance might mislead people.)

[Stargateur]

I proposed this cause you write in the PR:

// SAFETY: The comparison has no side-effects, and the intrinsic
// does this check internally in the CTFE implementation.
unsafe { assert_unsafe_precondition!(self >= origin) };

so I expect it to be "free", I'm all in favor of remove all assert since the method is unsafe anyway, this kind of operation should be as fast as possible. I just see this line and wonder, well if it's free why not ?

(Oh, and as prior art, std::distance in C++ isn't an absolute distance either, so calling it distance might mislead people.)

I don't think C++ std using distance name wrongly is a good point, have you ever see "this object is -1cm" ? a distance is always positive, that why we return usize. Distance is also mention many time in #95837.

[scottmcm]

cause you write in the PR:

assert_unsafe_precondition! is a magic compiler thing that only does something in CTFE. At codegen time, sub_ptr doesn't do any checks, just an "I promise not to overflow" subtraction and a "I promise it's an exact multiple" division: https://rust.godbolt.org/z/fE79dv6WT.

[deltragon]

Since offset_from has a parallel byte_offset_from method (tracked in #96283), should this method have an equivalent byte_sub_ptr method?
I am aware that this was added specifically for slice iterators, and there it doesn't seem like there has been a usecase for a bytewise method so far - but looking at the docs it seemed somewhat surprising that this is missing.

[RalfJung]

Yeah, if this stabilizes after the other byte methods we probably want byte_sub_ptr as well.

[LoganDark]

I've read some of the bikeshedding in #95837, and I'd like to second @Gankra's suggestion of "offset_to" - it's not perfect, but when I was looking for this method, I couldn't find it in the autocomplete and had to search for the -> usize return type instead. Having offset in the name would have made it easier to locate, as that's one of the first things I looked for.

Are there any blockers for stabilization besides the name? I'm not familiar with the stabilization process, but I'd be willing to open a stabilization PR for this if that would help.

[RalfJung]

So offset_from returns isize but offset_to returns usize? That makes little sense to me.

Once this is stable we can put a note in the offset_from docs pointing to sub_ptr.

[LoganDark]

So offset_from returns isize but offset_to returns usize? That makes little sense to me.

In isolation, it doesn't make much sense to me either - given the chance to go back in time, I would have made offset_from return usize instead, as the earlier discussion mentioned, but it's too late for that now.

Another possibility may be count_from - it still retains a word from offset_from, so it shouldn't take more than a couple tries to discover through autocomplete, but it still communicates its unsignedness - an element count will/should always be unsigned, as opposed to a relative offset which can go in either direction. (Maybe also len_from.)

[RalfJung]

@rust-lang/libs-api what are your current thoughts on this function? Is this generally something we'd want to have, in terms of its semantics? Any opinions on the name?

sub_ptr seems like an okay name to me. None of the proposed alternatives (offset_to, count_from) obviously beat it.

This doesn't currently have a "byte" variant but I assume we'll want that, too.
(It is being added in #132459.)

[Amanieu]

I'm somewhat partial to offset_from_unsigned which clearly indicates that this produces a usize and that the offset must be positive. Although this is actually longer than offset_from() as usize, it does involve additional safety conditions and may be easier for people to type with IDE auto-completion.

[scottmcm]

I think it would be a shame if it ended up with a name as long as offset_from_unsigned since we found out it's actually substantially more commonly the case than offset_from. This is the one you probably want, not the weird one -- and it's more efficient than offset_from() as usize too.

(Worse, these are all subtly different, so it's not obvious that clippy can tell you to change one pattern to another, either.)

[rfcbot]

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

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

[hanna-kruppe]

The FCP was for the name offset_from_unsigned but the stabilization PR #137121 didn't do the renaming. Did I miss anything or should the renaming still be done?

[Noratrieb]

You did not miss anything, but @bend-n and I did, because the issue description still listed the old names. Quick rename PRs welcome.

[bend-n]

quick question, what happened to byte_sub_ptr? is that byte_offset_from_unsigned?

[Amanieu]

quick question, what happened to byte_sub_ptr? is that byte_offset_from_unsigned?

Yes, they all have the same name with the byte_ prefix added.