Document that unary negation of a signed integer literal cannot cause an overflow error

[mattheww]

This describes what's going on if you write something like -128_i8: it invokes a no-op unary negation (taking -128 to -128), which the reference currently says should panic when overflow checks are enabled.

In fact this situation is special-cased so that there is no panic.

As I understand it, it's implemented by folding the expression to a constant during conversion from HIR to THIR, before the overflow checks are inserted (when THIR is lowered to MIR).

There are comments about it here:
https://github.com/rust-lang/rust/blob/ec7b753ea91d8a5640388ea74fd231f91394ee9d/compiler/rustc_mir_build/src/thir/pattern/mod.rs#L563

[ehuss]

Thanks, this seems like a good improvement!

I want to be cognizant that my suggestion my seem like it is rewriting most of the PR. I hope it doesn't seem that way. I intended to just add a little bit to it, but that ended up shuffling the sentences around a bit.

[ehuss]

I initially found this a little confusing because this seems to focus on the "most negative" aspect without reminding the reader that all integer literals are allowed to overflow. Perhaps a change like the following could help? My thinking is that a reader interested in Rust's overflowing behavior might be reading this section. So it would be good to guide them to additional information that might make it clearer.

Suggested change

	> **Note**: The exception for literal expressions behind unary `-` means that forms such as `-128_i8` or `let j: i8 = -(128)` never cause a panic.
	>
	> In these cases, the literal expression already has the most negative value for its type (for example, `128_i8` has the value -128), and two's complement overflow conventions mean the unary negation leaves the value unchanged, so the expression as a whole has the expected value.
	>
	> In rustc, these expressions are also ignored by the `overflowing_literals` lint check.
	> **Note**: The exception for literal expressions behind unary `-` means that forms such as `-128_i8` or `let j: i8 = -(128)` never cause a panic and have the expected value of -128.
	>
	> In these cases, the literal expression already has the most negative value for its type (for example, `128_i8` has the value -128) because integer literals are truncated to their type per the description in [Integer literal expressions][literal expression].
	> Negation of these most negative values leaves the value unchanged due to two's complement overflow conventions.
	>
	> In `rustc`, these most negative expressions are also ignored by the `overflowing_literals` lint check.

[mattheww]

I agree, that's clearer. I've pushed that change.

[ehuss]

IIUC, the magic happens on this line during lowering to MIR where the unary negation is applied, and the conversion to a constant happens here I think. I think the lit_to_const you linked is only relevant for pattern matching (so that pattern ranges can handle their full ranges).

[ehuss]

Thanks!