docs(core): clarify that signed integers use two's complement

[AudaciousAxiom]

Description

This attempts to clarify in the std documentation how signed integers (i8–i128 and isize) are encoded. I do not mean this to introduce a new stability guarantee, but only to document an already obvious (?) property, which is already documented elsewhere (mostly).

Motivation

My understanding is that signed integers are already guaranteed to be encoded in two's complement. The Reference does state this for i8–i128 (but technically does not for isize, at least not in the same place), and in documenting numeric casts and negation operators:

Remember that signed integers are always represented using two’s complement.

This therefore does not seem architecture or platform-dependent. However it is also not specified explicitly in the FLS.

In addition, I could not find this in the std documentation, while this seems required to understand the behavior of shr operations and of as casts in particular.

If this is something you think is worth documenting explicitly, the exact phrasing can likely be refined (it is currently modeled on floats'). If not, feel free to close this PR.

[rustbot]

r? @joboet

rustbot has assigned @joboet.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[RalfJung]

Yeah this is definitely guaranteed. I don't have a strong opinion on whether it makes sense to repeat lang-level guarantees in the libs docs.

while this seems required to understand the behavior of shr operations and of as casts in particular.

I would argue that as casts should be specified in a way that the representation doesn't matter (and we do it that way in MiniRust): an int-to-int as cast simply takes the input operand as mathematical value, brings that value in-bounds of the output type if needed, and then returns that mathematical value as result. This spec elegantly covers all cases without having to do a case distinction: truncation, extension, and both types having the same size.

But I understand that currently that's not how we specify as, unfortunately.

Cc @traviscross

[traviscross]

Regarding this PR specifically, even though I see that we do something a bit like this for floats, I'd prefer to not cram this bit of information into the summary line of the doc comment for the type. Putting it in the body does seem OK though.

r? traviscross

cc @ehuss

My understanding is that signed integers are already guaranteed to be encoded in two's complement. The Reference does state this for i8–i128 (but technically does not for isize, at least not in the same place)

Are you interested in making a PR to the Reference here to more cleanly make this guarantee? Probably I'd like to see the Reference guarantee this clearly before we do it in the standard library in this case.

[traviscross]

@rustbot author

[rustbot]

Reminder, once the PR becomes ready for a review, use @rustbot ready.

[AudaciousAxiom]

Are you interested in making a PR to the Reference here to more cleanly make this guarantee? Probably I'd like to see the Reference guarantee this clearly before we do it in the standard library in this case.

That makes sense, opened rust-lang/reference#2064 to this end.

[traviscross]

As mentioned in #147960 (comment):

Regarding this PR specifically, even though I see that we do something a bit like this for floats, I'd prefer to not cram this bit of information into the summary line of the doc comment for the type. Putting it in the body does seem OK though.

Other than this change, the Reference change I had asked for has now been approved by the lang team in rust-lang/reference#2064 and merged, so this PR can be merged after this editorial adjustment.

[AudaciousAxiom]

It took me a while to come back to this: I've now rebased and added a fixup commit with a new proposition for documenting this (I'll squash when you ask me before merging). As I mention, this now proposes to introduce a one-sentence section for each signed integer. I can see it giving too much importance to this small change, but I'm not sure how to introduce this into the existing docs otherwise, without cramming it into the summary paragraph.

[rustbot]

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[AudaciousAxiom]

Maybe adding a dedicated section is a bit too much, but that single-sentence paragraph looks a bit lonely otherwise, and we can't add it to the summary paragraph as it gets too long.

[AudaciousAxiom]

I'm not sure whether it should be title case (if we do keep that dedicated section, that is): most of titles in the std docs don't seem to use it, but I've still found a few that do.

[AudaciousAxiom]

I've placed this after the above paragraph because I think how the type is encoded should be documented only after its meaning is entirely defined.

[AudaciousAxiom]

@rustbot ready