Add doc for NonZero* const creation

[cptpiepmatz]

I ran into trouble using NonZero* values because I didn’t see any clear way to create them at compile time. At first I ended up using NonZero*::new_unchecked a lot, until I realized that Option::unwrap and Option::expect are const and can be used in a const context. With that, you can create non-zero values at compile time safely, without touching unsafe. This wasn’t obvious to me and my peers who’ve been using Rust for a while, so I thought adding a note to the docs would make it easier for others to discover.

If this should be worded differently or placed in another location, we can do that. I just want to make this more obvious.

[rustbot]

r? @ibraheemdev

rustbot has assigned @ibraheemdev.
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

[hkBst]

Since this issue is not restricted to NonZero, but more generally applies to const functions returning an Option or Result, another idea is to add such information instead to https://doc.rust-lang.org/nightly/std/keyword.const.html#compile-time-constants.

[cptpiepmatz]

Since this issue is not restricted to NonZero, but more generally applies to const functions returning an Option or Result, another idea is to add such information instead to doc.rust-lang.org/nightly/std/keyword.const.html#compile-time-constants.

True but I did not come across this issue anywhere besides non-zero values really.

[joboet]

How about using an inline-const-block here?

[cptpiepmatz]

So what @clubby789 asked to remove? #146924 (comment)

[joboet]

No, but the whole const TEN item:

Suggested change

	#[doc = concat!("const TEN: ", stringify!($Ty)," = ", stringify!($Ty),r#"::new(10).expect("ten is non-zero");"#)]
	#[doc = concat!("let ten = const { ", stringify!($Ty),r#"::new(10).expect("ten is non-zero") };"#)]

[cptpiepmatz]

I think both are fine. Why should we prefer this one?

[clubby789]

I prefer the const TEN: - we're probably documenting this to someone relatively new to the language, and a global const variable is more familiar/conceptually simpler than an inline const block imo

[hkBst]

We can have both. const X for https://doc.rust-lang.org/nightly/std/keyword.const.html#compile-time-constants and const {} for https://doc.rust-lang.org/nightly/std/keyword.const.html#compile-time-blocks. (Or do both here, but I've seen no evidence that NonZero is the dominant pattern for this.)

[joboet]

we're probably documenting this to someone relatively new to the language

That's mostly why I advocated for const-blocks – I'd like more people to be aware of them. But I don't feel strongly, the current version is fine.

[joboet]

Please squash commits and then r=me.
@bors delegate+
@bors rollup

[bors]

✌️ @cptpiepmatz, you can now approve this pull request!

If @joboet told you to "r=me" after making some further change, please make that change, then do @bors r=@joboet

[cptpiepmatz]

@bors r=@joboet

I hope I did that right

[bors]

📌 Commit 185ae69 has been approved by joboet

It is now in the queue for this repository.