offset_from: docs improvements

[RalfJung]

This is the part of #112837 that doesn't add a new function, just tweaks the existing docs.

[rustbot]

r? @Mark-Simulacrum

(rustbot has picked a reviewer for you, use r? to override)

[apiraino]

r? apiraino

[apiraino]

r? @Mark-Simulacrum

[GuillaumeGomez]

r? rust-lang/libs

[workingjubilee]

Typos.

Thank you! This is better, to be clear, so if you don't have any further thoughts or desire to improve this, I think it should go in, I just was wondering a little about thought process.

[workingjubilee]

Using the phrase "if and only if" makes me wonder "maybe this has a more natural way to say it?", as it then goes on to express itself as a counterfactual. It's a dual, and the text is correct, but not everyone will find the mental motion you are suggesting a very natural one to make.

Is the idea that this is a "shortcut" and that if they grok this then they can just skip the rest of the text, here?

[RalfJung]

I guess I'm too much of a logician, "if and only if" sounds natural to me. ;)

It's not a counterfactual, not in a logical sense anyway... the symbolic way of expressing this is

self.offset_from(origin) == Ok(n) <-> origin.offset(n) == Ok(self)

(where the Ok indicates non-UB execution)

Maybe there are better ways to put this into English?
"This function is well-defined with return value n if and only if origin.offset(n) is well-defined with return value self."

Is the idea that this is a "shortcut" and that if they grok this then they can just skip the rest of the text, here?

Hm, not entirely sure. The claim about the inverse already existed before, but I thought it needs clarification since these are 2-input partial functions, so there is no obvious default meaning of "inverse".

[workingjubilee]

I suppose it's more of a "complement"?

Perhaps more direct about the constraint, then, something like:

"This is the inverse of [`offset`]: this function's returned `isize` will,
if used in `origin.offset(n)`, produce a pointer with the same address as `self`,
and if one would be UB to call then both are UB to call."

Maybe a small snippet in a Rust block, whatever seems to format nicest in ./x.py doc library --open

[RalfJung]

I find that slightly ambiguous since "if one would be UB to call then both are UB to call" here is under the scope of "the function's returned isize" but that already assumes that it was not UB to call. (A function that's UB doesn't return an isize. It's like the function returns Result<isize, UB>.)

[workingjubilee]

Oh, I'm certainly not trying to be precious about the exact wording. I just think that it should state this in two steps, because they're actually disjoint from the perspective of the programmer:

• The resulting value can be used as an argument in one function to produce the other one.
• The validity constraints (is that the right term?) for invoking either function are effectively mutual.

[RalfJung]

The thing is, these steps are not separate though. It's a single equation:

self.offset_from(origin) == Ok(n) <-> origin.offset(n) == Ok(self)

This cannot be factored into two equations. Or at least I don't see how. To even talk about origin.offset(n) you need to know n but you only get that after assuming that offset_from is not UB, and vice versa.

[workingjubilee]

It's one equation but the sequent looks like
A, B ⊢ C
doesn't it?

[RalfJung]

No, it's A ⊣⊢ B. It's completely symmetric.

[RalfJung]

We can split the two directions of course:

• If self.offset_from(origin) is well-defined with result n, then origin.offset(n) is well-defined with result self.
• If origin.offset(n) is well-defined with result self, then self.offset_from(origin) is well-defined with result n.

But I don't see how that helps.

[RalfJung]

Following #95851 I have removed the note about the "inverse" entirely, and replaced it by

/// This is equivalent to `(self as isize - origin as isize) / (mem::size_of::<T>() as isize)`,
/// except that it has a lot more opportunities for UB, in exchange for the compiler
/// better understanding what you are doing.

[RalfJung]

r? libs-api

[workingjubilee]

r? @workingjubilee

[workingjubilee]

Reviewing this again... Would it be correct to strengthen this claim to something more like "allocations don't necessarily have addresses during CTFE, just offsets from their base, so there is no such thing as a distance between two allocations"?

I know it amounts to the same, but after looking at it a few times, maybe I'm just experiencing semantic satiation, but I feel like "do not have a known distance" is slightly ambiguous, and this is basically my understanding of how it works. We should be clearer that the semantics of CTFE are allowed to be incomprehensible where we can, to dissuade anyone who imagines some "like a flat address space" model applies.

[RalfJung]

Yeah both of these are correct ways to explain the situation. I don't know which one works better for most people.
We have existing guidance that is printed by the compiler when e.g. you try to transmute a pointer to an integer, which reads as follows:

this code performed an operation that depends on the underlying bytes representing a pointer
the absolute address of a pointer is not known at compile-time, so such operations are not supported

So I went with the same idea of "address is not known yet" here. We could also go with "the address has not been assigned yet" or something like that, but then we should do it consistently in the libs docs and compiler output, I think.

[workingjubilee]

Yeah, doing it consistently is a good point so that should be a separate issue probably.

[RalfJung]

I guess the alternative would be to do something like #95851, and remove the comment about it being an "inverse" entirely.

[workingjubilee]

That does settle it I suppose, yes.

[workingjubilee]

@bors r+

[bors]

📌 Commit 9b7f9c4 has been approved by workingjubilee

It is now in the queue for this repository.

[bors]

⌛ Testing commit 9b7f9c4 with merge a6dfd89...

[bors]

☀️ Test successful - checks-actions
Approved by: workingjubilee
Pushing a6dfd89 to master...

[rust-timer]

Finished benchmarking commit (a6dfd89): comparison URL.

Overall result: ✅ improvements - no action needed

@rustbot label: -perf-regression

Instruction count

This is a highly reliable metric that was used to determine the overall result at the top of this comment.

	mean	range	count
Regressions ❌ (primary)	-	-	0
Regressions ❌ (secondary)	-	-	0
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-0.3%	[-0.3%, -0.3%]	3
All ❌✅ (primary)	-	-	0

Max RSS (memory usage)

This benchmark run did not return any relevant results for this metric.

Cycles

This benchmark run did not return any relevant results for this metric.

Binary size

This benchmark run did not return any relevant results for this metric.

Bootstrap: 634.388s -> 631.332s (-0.48%)
Artifact size: 317.38 MiB -> 317.36 MiB (-0.00%)