Add Discriminant::unstable_cmp

[bushrat011899]

Tracking Issue: Not Yet Created
Supersedes: #106418
Zulip Discussion: #t-libs > Impl Partial/Ord for Discriminant

Based on this concern on the implementation of Partial/Ord for Discriminant, I'm proposing we instead offer an unstable_cmp function. This mirrors the fN::total_cmp function used to provide Ord-like functionality to f16/32/64/128 without actually guaranteeing the type itself is Ord.

Notes

• No AI tooling of any kind was used during the creation of this PR.
• The name unstable_cmp has been chosen to explicitly document at each usage that the ordering of Discriminant values is not stable and may change.
• I have not created a tracking issue or ACP, but I'd be happy to upon request!
• The function could be trivially made const, but that requires either making DiscriminantKind::Discriminant: const Ord or adding a fairly verbose where <T as DiscriminantKind>::Discriminant: [const] Ord to unstable_cmp. As such I'm deferring its inclusion. It would remain unstable until const_cmp is stabilized anyway.

[rustbot]

r? @Mark-Simulacrum

rustbot has assigned @Mark-Simulacrum.
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 12 candidates
• Random selection from JohnTitor, Mark-Simulacrum

[asquared31415]

Is there a good way to make a non-example? Like

// !!! DONT DO THIS, this assert may or may not pass, no guarantees are provided
assert_eq!(b_discriminant.unstable_cmp(a_discriminant), Ordering::Less);

(note: i intentionally used an assert that will not pass with the current obvious implementation)

I know we have some UB non-examples in the standard library, but is there a standard for other non-examples? and if so, would it be a good idea to call this out?

View changes since the review

[bushrat011899]

Ok so what I've done is swapped the assertions to use assert!(matches!(...)) instead, since I think it's clearer to say assert!(matches!(..., Less | Greater)) than assert_ne!(..., Equal). To cover the non-example case, I've used a little hidden-line trickery to change the ordering of variants and write this as a should_panic example, so in the docs it'll get a nice red highlight saying it'll panic (only kind of a lie).