Add `Discriminant::ord` - #165443

bushrat011899 · 2026-11-04T02:40:14Z

ACP: rust-lang/libs-team#925
Tracking Issue: #165438
Alternative To: #164231

This is an implementation for Option 2 from #165438. This provides a new method Discriminant::ord which returns a new type, DiscriminantOrd, suitable for key comparison. This follows a philosophy similar to that of Path::display for providing functional through standard traits gated behind a wrapper. I've elected for the return type of Discriminant::ord to be named as was requested during the T-Libs meeting proposing this option, and I've chosen to implement all traits currently implemented by Discriminant, this could be reduced.

In comparison to #164231, this has the advantage of allowing the storage of the discriminant in a structure and the deriving a Partial/Ord implementation.

Notes

No AI tooling of any kind was used during the creation of this PR.
Chose the name ord as that appeared to be the generally preferred option, but alternatives may include unstable_ord, etc.

Method to get a ordering key on `Discriminant`

rustbot · 2026-11-04T02:40:20Z

r? @clarfonthey

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

Why was this reviewer chosen?

The reviewer was selected based on:

Owners of files modified in this PR: libs
libs expanded to 38 candidates
Random selection from JohnTitor, LawnGnome, Mark-Simulacrum, clarfonthey

clarfonthey · 2026-11-04T02:44:30Z

+    /// Returns an *unstable* ordering key for this [`Discriminant`].
+    ///
+    /// [`Discriminant`] does not implement [`PartialOrd`] or [`Ord`] as we do
+    /// not guarantee a stable ordering of discriminant values.


I would clarify here that unstable means not-stable-API, since "unstable sorting" is a dedicated term that means something else.

View changes since the review

Agreed, I initially lightly reworked the documentation as written in #164231. I've now rewritten the whole thing based on the T-Libs meeting minutes. To clear the confusion around "unstable sort" I've just linked to sort_unstable and explicitly said "not this kind of unstable".

@rustbot ready

rustbot · 2026-11-04T02:44:39Z

Reminder, once the PR becomes ready for a review, use @rustbot ready.

Based on reviewer feedback.

bushrat011899 · 2026-11-04T04:07:31Z

+    /// Returns an ordering key for this [`Discriminant`] that has an unstable
+    /// implementation with regards to *semantic versioning*. This is not the be confused
+    /// with an [*"unstable sort"*].
+    ///
+    /// Because all types have a publicly accessible [`Discriminant`], regardless
+    /// of whether the order of said type is a part of its stability guarantees,
+    /// the exact ordering of the returned [`DiscriminantOrd`] cannot be relied on
+    /// for stability across crates. This is similar to the stability of the size
+    /// of a type as returned by [`size_of`].
+    ///
+    /// Enum values will be ordered based on the source declaration and `repr` values
+    /// of their variants, consistent with derived implementations of [`PartialOrd`]
+    /// and [`Ord`]. Noting that only the discriminant and no field values are considered.
+    /// All other kinds of values have an *unspecified* ordering, but will _typically_
+    /// be trivially ordered as equivalent.
+    ///
+    /// Users of this function should instead rely on the [`Ord`] implementation
+    /// of `T` wherever possible.


@workingjubilee with regards to your comment here: I've tried to capture what I believe is a reasonable clarification around what Discriminant does and does not guarantee with regards to ordering. I believe it aligns with what you're thinking but I'd greatly appreciate your eyes on it!

View changes since the review

clarfonthey · 2026-11-04T04:32:44Z

Going to approve for now but if @workingjubilee has any doc suggestions we can either r- and re-r+ or just do those as a separate PR.

@bors r+ rollup

(Thank you!)

rust-bors · 2026-11-04T04:32:46Z

📌 Commit 7e7da83 has been tentatively approved by clarfonthey

It will be put into the queue for this repository once PR CI succeeds.

…clarfonthey Add `Discriminant::ord` ACP: rust-lang/libs-team#925 Tracking Issue: rust-lang#165438 Alternative To: rust-lang#164231 This is an implementation for Option 2 from rust-lang#165438. This provides a new method `Discriminant::ord` which returns a new type, `DiscriminantOrd`, suitable for key comparison. This follows a philosophy similar to that of `Path::display` for providing functional through standard traits gated behind a wrapper. I've elected for the return type of `Discriminant::ord` to be named as was requested during the T-Libs meeting proposing this option, and I've chosen to implement all traits currently implemented by `Discriminant`, this could be reduced. In comparison to rust-lang#164231, this has the advantage of allowing the storage of the discriminant in a structure and the deriving a `Partial/Ord` implementation. # Notes * No AI tooling of any kind was used during the creation of this PR. * Chose the name `ord` as that appeared to be the generally preferred option, but alternatives may include `unstable_ord`, etc.

…uwer Rollup of 7 pull requests Successful merges: - #164752 (Apply the Cortex-A53 843419 CC mitigation to aarch64 targets ) - #165376 (Add `Forget` trait feature gate) - #165257 (Revert FCW on lint attributes on macro calls) - #165364 (Update books) - #165424 (Update amdgpu datalayout for LLVM 24) - #165443 (Add `Discriminant::ord`) - #165445 (Add an unstable option to increase the chain depth of the next solver overflow FCW)

…clarfonthey Add `Discriminant::ord` ACP: rust-lang/libs-team#925 Tracking Issue: rust-lang#165438 Alternative To: rust-lang#164231 This is an implementation for Option 2 from rust-lang#165438. This provides a new method `Discriminant::ord` which returns a new type, `DiscriminantOrd`, suitable for key comparison. This follows a philosophy similar to that of `Path::display` for providing functional through standard traits gated behind a wrapper. I've elected for the return type of `Discriminant::ord` to be named as was requested during the T-Libs meeting proposing this option, and I've chosen to implement all traits currently implemented by `Discriminant`, this could be reduced. In comparison to rust-lang#164231, this has the advantage of allowing the storage of the discriminant in a structure and the deriving a `Partial/Ord` implementation. # Notes * No AI tooling of any kind was used during the creation of this PR. * Chose the name `ord` as that appeared to be the generally preferred option, but alternatives may include `unstable_ord`, etc.

…uwer Rollup of 17 pull requests Successful merges: - #164752 (Apply the Cortex-A53 843419 CC mitigation to aarch64 targets ) - #165011 (std: Clean up and improve errors for `is_*_feature_detected` macros) - #165376 (Add `Forget` trait feature gate) - #164482 (Remove the label starting with 0 in the test binary_asm_labels_allowed.rs) - #165201 (Move a bunch of methods out of `AttributeExt`) - #165268 (Fix constant-pattern equality suggestion spans in macros) - #165318 (Fix explicit destructor-call suggestion spans in macros) - #164440 ([Outreachy] alloc: Add test coverage for try_clone_from_ref_in (Box, Arc, Rc)) - #165001 (Document allocator swap in BinaryHeap::append) - #165257 (Revert FCW on lint attributes on macro calls) - #165330 (Impl read_le/read_be for f16 and f128) - #165364 (Update books) - #165414 (Remove unusued query key impl) - #165424 (Update amdgpu datalayout for LLVM 24) - #165440 (docker: bump node to v24.22.2 in shared script) - #165443 (Add `Discriminant::ord`) - #165445 (Add an unstable option to increase the chain depth of the next solver overflow FCW)

workingjubilee

I found some things that look like simple typos and some things which are a little more nuanced. https://github.com/rust-lang/rust/actions/runs/41867636881 is almost done though, and I'd rather this code get into a nightly so we can start getting feedback, so I think these should all be a followup PR.

View changes since this review

workingjubilee · 2026-11-04T18:53:45Z

+    /// implementation with regards to *semantic versioning*. This is not the be confused
+    /// with an [*"unstable sort"*].


typo

Suggested change

/// implementation with regards to *semantic versioning*. This is not the be confused

/// with an [*"unstable sort"*].

/// implementation with regards to *semantic versioning*. This is not to be confused

/// with an [*"unstable sort"*].

Though since we don't mention "unstable" in the name anymore, I don't think the second sentence is necessary.

Suggested change

/// implementation with regards to *semantic versioning*. This is not the be confused

/// with an [*"unstable sort"*].

/// implementation with regards to *semantic versioning*.

idk, maybe @clarfonthey disagrees? it's whatev.

Agreed on the typo, but I think I'd prefer to keep the disambiguation as that's been a pretty frequent confusion amongst the handful of T-Libs peeps that have discussed this so far.

workingjubilee · 2026-11-04T18:55:12Z

+    /// for stability across crates. This is similar to the stability of the size
+    /// of a type as returned by [`size_of`].


or do you mean the cross-crate boundary... i.e. "this isn't necessarily stable if you aren't the crate that defined the enum"?

Suggested change

/// for stability across crates. This is similar to the stability of the size

/// of a type as returned by [`size_of`].

/// for stability across crate versions. This is similar to the stability of

/// the size of a type as returned by [`size_of`].

Yeah I think I want to say cross-crate boundary. One of the usecases for this ordering is being able to expand the derived implementation of Partial/Ord, so we do want stability when its your own enum. And I believe this is already guaranteed (for the derive macro), so I don't think there's any issues with keeping that guarantee consistent here.

workingjubilee · 2026-11-04T18:55:42Z

+    /// for stability across crates. This is similar to the stability of the size
+    /// of a type as returned by [`size_of`].
+    ///
+    /// Enum values will be ordered based on the source declaration and `repr` values


I think?

Suggested change

/// Enum values will be ordered based on the source declaration and `repr` values

/// Enum values will be ordered based on the source declaration and assigned values

Yeah I wasn't sure how to describe this.

#[repr(u8)] enum Foo { A = 2, B = 1, // ^^^^ Whatever this is called }

I think "assigned" is clearer, but I feel like there must be a formal term for this. Something like "explicit tag value"?

workingjubilee · 2026-11-04T18:56:24Z

+    ///
+    /// Enum values will be ordered based on the source declaration and `repr` values
+    /// of their variants, consistent with derived implementations of [`PartialOrd`]
+    /// and [`Ord`]. Noting that only the discriminant and no field values are considered.


Suggested change

/// and [`Ord`]. Noting that only the discriminant and no field values are considered.

/// and [`Ord`]. Note that only the discriminant and no field values are considered.

workingjubilee · 2026-11-04T19:03:10Z

+    ///     Ordering::Equal,
+    /// );
+    ///
+    /// // Inequivalent arms will compare not-equal


Suggested change

/// // Inequivalent arms will compare not-equal

/// // Non-equivalent variants will compare not-equal

workingjubilee · 2026-11-04T19:10:21Z

+    /// Upstream libraries and the compiler are free to change the exact ordering
+    /// of discriminants. The below _may_ break at any time:


Maybe this is obvious?

Suggested change

/// Upstream libraries and the compiler are free to change the exact ordering

/// of discriminants. The below _may_ break at any time:

/// Upstream libraries and the compiler are free to change the exact ordering

/// of discriminants unless they are explicitly documented as stable.

/// The below _may_ break at any time:

Maybe but I think it's a good addition. Looking back at this I'm actually not sure the compiler is free to change discriminant ordering, since it's a component of Partial/Ord implementations, which are supposed to be stable.

workingjubilee · 2026-11-04T19:23:01Z

+    /// Enum values will be ordered based on the source declaration and `repr` values
+    /// of their variants, consistent with derived implementations of [`PartialOrd`]
+    /// and [`Ord`]. Noting that only the discriminant and no field values are considered.
+    /// All other kinds of values have an *unspecified* ordering, but will _typically_
+    /// be trivially ordered as equivalent.


This paragraph kinda needs more time in the stew... I think it starts off in a slightly confusing way because it talks about enum values when we already left those behind by the time we called discriminant()... but I think further cooking probably indeed warrants its own PR.

+1 for letting it stew a little longer. My current revision for this is:

Discriminants from enums will be ordered based on the source declaration
and assigned values of their variants, consistent with derived implementations
of [PartialOrd] and [Ord]. All other kinds of discriminants have an
unspecified ordering, but will typically be trivially ordered as equivalent.

I haven't mentioned it yet but I'm making these changes in a new PR which I'll open once this is merged.

workingjubilee · 2026-11-04T19:34:47Z

+    ///
+    /// enum Foo { A(i32), B(i32) }
+    ///
+    /// // Equivalent arms will compare equal regardless of contained data


The reference only uses "arms" to describe MatchArms and it is not part of Enumerations which consistently refers to these as variants.

Suggested change

/// // Equivalent arms will compare equal regardless of contained data

/// // Equivalent variants will compare equal regardless of contained data

That's much better, thanks!

…uwer Rollup of 17 pull requests Successful merges: - #164752 (Apply the Cortex-A53 843419 CC mitigation to aarch64 targets ) - #165011 (std: Clean up and improve errors for `is_*_feature_detected` macros) - #165376 (Add `Forget` trait feature gate) - #164482 (Remove the label starting with 0 in the test binary_asm_labels_allowed.rs) - #165201 (Move a bunch of methods out of `AttributeExt`) - #165268 (Fix constant-pattern equality suggestion spans in macros) - #165318 (Fix explicit destructor-call suggestion spans in macros) - #164440 ([Outreachy] alloc: Add test coverage for try_clone_from_ref_in (Box, Arc, Rc)) - #165001 (Document allocator swap in BinaryHeap::append) - #165257 (Revert FCW on lint attributes on macro calls) - #165330 (Impl read_le/read_be for f16 and f128) - #165364 (Update books) - #165414 (Remove unusued query key impl) - #165424 (Update amdgpu datalayout for LLVM 24) - #165440 (docker: bump node to v24.22.2 in shared script) - #165443 (Add `Discriminant::ord`) - #165445 (Add an unstable option to increase the chain depth of the next solver overflow FCW)

Add Discriminant::ord

effca29

Method to get a ordering key on `Discriminant`

rustbot assigned clarfonthey Nov 4, 2026

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 Nov 4, 2026

This was referenced Nov 4, 2026

Add Discriminant::unstable_cmp #164231

Closed

Tracking Issue for discriminant_ord #165438

Open

clarfonthey requested changes Nov 4, 2026

View reviewed changes

rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Nov 4, 2026

Update Discriminant::ord Documentation

7e7da83

Based on reviewer feedback.

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Nov 4, 2026

bushrat011899 commented Nov 4, 2026

View reviewed changes

rust-bors Bot 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 Nov 4, 2026

JonathanBrouwer mentioned this pull request Nov 4, 2026

Rollup of 8 pull requests #165453

Closed

JonathanBrouwer mentioned this pull request Nov 4, 2026

Rollup of 7 pull requests #165454

Closed

JonathanBrouwer mentioned this pull request Nov 4, 2026

Rollup of 17 pull requests #165464

Open

workingjubilee reviewed Nov 4, 2026

View reviewed changes

bushrat011899 mentioned this pull request Nov 4, 2026

WIP: Update Documentation for Discriminant::ord #165472

Draft

		/// implementation with regards to semantic versioning. This is not the be confused
		/// with an ["unstable sort"].

		/// for stability across crates. This is similar to the stability of the size
		/// of a type as returned by [`size_of`].

	/// Enum values will be ordered based on the source declaration and `repr` values
	/// Enum values will be ordered based on the source declaration and assigned values

	/// and [`Ord`]. Noting that only the discriminant and no field values are considered.
	/// and [`Ord`]. Note that only the discriminant and no field values are considered.

	/// // Inequivalent arms will compare not-equal
	/// // Non-equivalent variants will compare not-equal

		/// Upstream libraries and the compiler are free to change the exact ordering
		/// of discriminants. The below _may_ break at any time:

	/// // Equivalent arms will compare equal regardless of contained data
	/// // Equivalent variants will compare equal regardless of contained data

Conversation

bushrat011899 commented Nov 4, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Notes

Uh oh!

rustbot commented Nov 4, 2026

Uh oh!

clarfonthey Nov 4, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bushrat011899 Nov 4, 2026 • 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!

Choose a reason for hiding this comment

Uh oh!

rustbot commented Nov 4, 2026

Uh oh!

bushrat011899 Nov 4, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

clarfonthey commented Nov 4, 2026

Uh oh!

rust-bors Bot commented Nov 4, 2026

Uh oh!

workingjubilee left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

bushrat011899 commented Nov 4, 2026 •

edited by rustbot

Loading

clarfonthey Nov 4, 2026 •

edited by rustbot

Loading

bushrat011899 Nov 4, 2026 •

edited

Loading

bushrat011899 Nov 4, 2026 •

edited by rustbot

Loading

workingjubilee left a comment •

edited by rustbot

Loading