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.