Add doc for `NonZero*` const creation by cptpiepmatz · Pull Request #146924 · rust-lang/rust

cptpiepmatz · 2025-09-23T08:54:33Z

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 · 2025-09-23T08:54:39Z

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

library/core/src/num/nonzero.rs

hkBst · 2025-09-23T11:31:26Z

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 · 2025-09-23T11:35:45Z

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 · 2025-09-24T11:32:28Z

library/core/src/num/nonzero.rs

+        /// ```
+        #[doc = concat!("use std::num::", stringify!($Ty), ";")]
+        ///
+        #[doc = concat!("const TEN: ", stringify!($Ty), " = ", stringify!($Ty) , r#"::new(10).expect("ten is non-zero");"#)]


How about using an inline-const-block here?

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

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") };"#)]

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

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

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.)

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.

library/core/src/num/nonzero.rs

joboet · 2025-09-25T14:37:34Z

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

bors · 2025-09-25T14:37:38Z

✌️ @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 · 2025-09-25T15:58:54Z

@bors r=@joboet

I hope I did that right

bors · 2025-09-25T15:58:57Z

📌 Commit 185ae69 has been approved by joboet

It is now in the queue for this repository.

…tion, r=joboet Add doc for `NonZero*` const creation 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.

Rollup of 8 pull requests Successful merges: - #116882 (rustdoc: hide `#[repr]` if it isn't part of the public ABI) - #135771 ([rustdoc] Add support for associated items in "jump to def" feature) - #141032 (avoid violating `slice::from_raw_parts` safety contract in `Vec::extract_if`) - #142401 (Add proper name mangling for pattern types) - #146293 (feat: non-panicking `Vec::try_remove`) - #146859 (BTreeMap: Don't leak allocators when initializing nodes) - #146924 (Add doc for `NonZero*` const creation) - #146933 (Make `render_example_with_highlighting` return an `impl fmt::Display`) r? `@ghost` `@rustbot` modify labels: rollup

Rollup merge of #146924 - cptpiepmatz:doc-nonzero-const-creation, r=joboet Add doc for `NonZero*` const creation 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.

Rollup of 8 pull requests Successful merges: - rust-lang/rust#116882 (rustdoc: hide `#[repr]` if it isn't part of the public ABI) - rust-lang/rust#135771 ([rustdoc] Add support for associated items in "jump to def" feature) - rust-lang/rust#141032 (avoid violating `slice::from_raw_parts` safety contract in `Vec::extract_if`) - rust-lang/rust#142401 (Add proper name mangling for pattern types) - rust-lang/rust#146293 (feat: non-panicking `Vec::try_remove`) - rust-lang/rust#146859 (BTreeMap: Don't leak allocators when initializing nodes) - rust-lang/rust#146924 (Add doc for `NonZero*` const creation) - rust-lang/rust#146933 (Make `render_example_with_highlighting` return an `impl fmt::Display`) r? `@ghost` `@rustbot` modify labels: rollup

…tion, r=joboet Add doc for `NonZero*` const creation 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.

…iaskrgr Rollup of 8 pull requests Successful merges: - rust-lang#116882 (rustdoc: hide `#[repr]` if it isn't part of the public ABI) - rust-lang#135771 ([rustdoc] Add support for associated items in "jump to def" feature) - rust-lang#141032 (avoid violating `slice::from_raw_parts` safety contract in `Vec::extract_if`) - rust-lang#142401 (Add proper name mangling for pattern types) - rust-lang#146293 (feat: non-panicking `Vec::try_remove`) - rust-lang#146859 (BTreeMap: Don't leak allocators when initializing nodes) - rust-lang#146924 (Add doc for `NonZero*` const creation) - rust-lang#146933 (Make `render_example_with_highlighting` return an `impl fmt::Display`) r? `@ghost` `@rustbot` modify labels: rollup

Rollup of 8 pull requests Successful merges: - rust-lang/rust#116882 (rustdoc: hide `#[repr]` if it isn't part of the public ABI) - rust-lang/rust#135771 ([rustdoc] Add support for associated items in "jump to def" feature) - rust-lang/rust#141032 (avoid violating `slice::from_raw_parts` safety contract in `Vec::extract_if`) - rust-lang/rust#142401 (Add proper name mangling for pattern types) - rust-lang/rust#146293 (feat: non-panicking `Vec::try_remove`) - rust-lang/rust#146859 (BTreeMap: Don't leak allocators when initializing nodes) - rust-lang/rust#146924 (Add doc for `NonZero*` const creation) - rust-lang/rust#146933 (Make `render_example_with_highlighting` return an `impl fmt::Display`) r? `@ghost` `@rustbot` modify labels: rollup

rustbot assigned ibraheemdev Sep 23, 2025

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Sep 23, 2025

clubby789 reviewed Sep 23, 2025

View reviewed changes

library/core/src/num/nonzero.rs Outdated Show resolved Hide resolved

joboet reviewed Sep 24, 2025

View reviewed changes

joboet assigned joboet and unassigned ibraheemdev Sep 24, 2025

add doc for NonZero* const creation

185ae69

cptpiepmatz force-pushed the doc-nonzero-const-creation branch from 55487c1 to 185ae69 Compare September 25, 2025 15:54

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 25, 2025

This was referenced Sep 25, 2025

Rollup of 6 pull requests #147036

Closed

Rollup of 8 pull requests #147037

Merged

bors merged commit 781f71a into rust-lang:master Sep 25, 2025
10 checks passed

rustbot added this to the 1.92.0 milestone Sep 25, 2025

	#[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") };"#)]

Uh oh!

Conversation

cptpiepmatz commented Sep 23, 2025

Uh oh!

rustbot commented Sep 23, 2025

Uh oh!

Uh oh!

hkBst commented Sep 23, 2025

Uh oh!

cptpiepmatz commented Sep 23, 2025

Uh oh!

joboet Sep 24, 2025

Choose a reason for hiding this comment

Uh oh!

cptpiepmatz Sep 24, 2025

Choose a reason for hiding this comment

Uh oh!

joboet Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cptpiepmatz Sep 24, 2025

Choose a reason for hiding this comment

Uh oh!

clubby789 Sep 24, 2025

Choose a reason for hiding this comment

Uh oh!

hkBst Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joboet Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

joboet commented Sep 25, 2025

Uh oh!

bors commented Sep 25, 2025

Uh oh!

cptpiepmatz commented Sep 25, 2025

Uh oh!

bors commented Sep 25, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

joboet Sep 24, 2025 •

edited

Loading

hkBst Sep 25, 2025 •

edited

Loading