Consolidate all associated items on the NonZero integer types into a single impl block per type

[dtolnay]

Before:

#[repr(transparent)]
#[rustc_layout_scalar_valid_range_start(1)]
pub struct NonZeroI8(i8);

impl NonZeroI8 {
    pub const fn new(n: i8) -> Option<Self> ...
    pub const fn get(self) -> i8 ...
}

impl NonZeroI8 {
    pub const fn leading_zeros(self) -> u32 ...
    pub const fn trailing_zeros(self) -> u32 ...
}

impl NonZeroI8 {
    pub const fn abs(self) -> NonZeroI8 ...
}
...

After:

#[repr(transparent)]
#[rustc_layout_scalar_valid_range_start(1)]
pub struct NonZeroI8(i8);

impl NonZeroI8 {
    pub const fn new(n: i8) -> Option<Self> ...
    pub const fn get(self) -> i8 ...
    pub const fn leading_zeros(self) -> u32 ...
    pub const fn trailing_zeros(self) -> u32 ...
    pub const fn abs(self) -> NonZeroI8 ...
    ...
}

Having 6-7 different impl blocks per type is not such a problem in today's implementation, but becomes awful upon the switch to a generic NonZero<T> type (context: #82363 (comment)).

In the implementation from #100428, there end up being 67 impl blocks on that type.

Without the refactor to a single impl block first, introducing NonZero<T> would be a usability regression compared to today's separate pages per type. With all those blocks expanded, Ctrl+F is obnoxious because you need to skip 12× past every match you don't care about. With all the blocks collapsed, Ctrl+F is useless. Getting to a state in which exactly one type's (e.g. NonZero<u32>) impl blocks are expanded while the rest are collapsed is annoying.

After this refactor to a single impl block, we can move forward with making NonZero<T> a generic struct whose docs all go on the same rustdoc page. The rustdoc will have 12 impl blocks, one per choice of T supported by the standard library. The reader can expand a single one of those impl blocks e.g. NonZero<u32> to understand the entire API of that type.

Note that moving the API into a generic impl<T> NonZero<T> { ... } is not going to be an option until after NonZero<T> has been stabilized, which may be months or years after its introduction. During the period while generic NonZero is unstable, it will be extra important to offer good documentation on all methods demonstrating the API being used through the stable aliases such as NonZeroI8.

This PR follows a key = $value syntax for the macros which is similar to the macros we already use for producing a single large impl block on the integer primitives.

rust/library/core/src/num/mod.rs

Lines 288 to 309 in 1dd4db5

	impl i8 {
	int_impl! {
	Self = i8,
	ActualT = i8,
	UnsignedT = u8,
	BITS = 8,
	BITS_MINUS_ONE = 7,
	Min = -128,
	Max = 127,
	rot = 2,
	rot_op = "-0x7e",
	rot_result = "0xa",
	swap_op = "0x12",
	swapped = "0x12",
	reversed = "0x48",
	le_bytes = "[0x12]",
	be_bytes = "[0x12]",
	to_xe_bytes_doc = "",
	from_xe_bytes_doc = "",
	bound_condition = "",
	}
	}

Best reviewed one commit at a time.

[rustbot]

r? @m-ou-se

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

[Noratrieb]

@dtolnay asked me to take a look: https://rust-lang.zulipchat.com/#narrow/stream/219381-t-libs/topic/nils'.20reviews/near/411787682
I looked at all commits and they were all pretty simple in isolation and I think they all look correct to me. The change also looks reasonable for the purpose of unifying the impl blocks.

[bors]

☔ The latest upstream changes (presumably #119452) made this pull request unmergeable. Please resolve the merge conflicts.

[dtolnay]

• Rebased to resolve conflict with Add assume into NonZeroIntX::get #119452

[Noratrieb]

Didn't review the diff in detail again, but it should be fine

[Noratrieb]

well, diffed the two files before/after anyways, looks fine.

diff

115a116,127
>                 // FIXME: Remove this after LLVM supports `!range` metadata for function
>                 // arguments https://github.com/llvm/llvm-project/issues/76628
>                 //
>                 // Rustc can set range metadata only if it loads `self` from
>                 // memory somewhere. If the value of `self` was from by-value argument
>                 // of some not-inlined function, LLVM don't have range metadata
>                 // to understand that the value cannot be zero.
>
>                 // SAFETY: It is an invariant of this type.
>                 unsafe {
>                     intrinsics::assume(self.0 != 0);
>                 }
153c165
<                 unsafe { intrinsics::ctlz_nonzero(self.0 as $UnsignedPrimitive) as u32 }
---
>                 unsafe { intrinsics::ctlz_nonzero(self.get() as $UnsignedPrimitive) as u32 }
177c189
<                 unsafe { intrinsics::cttz_nonzero(self.0 as $UnsignedPrimitive) as u32 }
---
>                 unsafe { intrinsics::cttz_nonzero(self.get() as $UnsignedPrimitive) as u32 }
394c406,408
<                 nonzero.0
---
>                 // Call nonzero to keep information range information
>                 // from get method.
>                 nonzero.get()
760c774
<             super::int_log10::$Int(self.0)
---
>             super::int_log10::$Int(self.get())

[Noratrieb]

I guess I'm supposed to do this now :)
@bors r+ rollup

[bors]

📌 Commit cdee1fe has been approved by Nilstrieb

It is now in the queue for this repository.