Tracking Issue for NonMin and NonMax types.

[moonheart08]

Feature gate: #![feature(nonmin_nonmax_types)]

This is a tracking issue for rust-lang/libs-team#721

NonMin and NonMax are niche types, like NonZero, that provide niches at T::MIN and T::MAX respectively.
They are akin to NonZero in API, minus the individual aliases.

Public API

As this API is implemented for many distinct types, I'm opting to only show the impls for NonMin<isize> for demonstration purposes.
The surface area for NonMin and NonMax are identical and their behavior only differs in niche location.

// Constrained such that T is one of i8, i16, i32, i64, i128, or isize.
/// A value that is known to not be its minimum.
/// This enables some memory layout optimization. For example, `Option<NonMin<u32>>` is the same size as `u32`.
struct NonMin<T: NonMinPrimitive>;

// Constrained such that T is one of u8, u16, u32, u64, u128, or usize.
/// A value that is known to not be its maximum.
/// This enables some memory layout optimization. For example, `Option<NonMax<u32>>` is the same size as `u32`.
struct NonMax<T: NonMaxPrimitive>;

impl NonMin<isize> {
   const MIN: Self;
   const MAX: Self;
   const BITS: Self;
   
   pub const fn get(self) -> isize;
   pub const fn new(n: isize) -> Option<Self>;
   pub const unsafe fn new_unchecked(n: isize) -> Self;
   
   
   // Intent is to match the current NonZero surface area when sensible.
   // To avoid leaving an unreviewable spill of information, I will not list every method,
   // in favor of discussing them here verbally.
   // 
   // Input from https://github.com/rust-lang/libs-team/issues/721#issuecomment-3725065768
   // is to be accounted for, a lot of functions only ever shrink their input around zero
   // and will not produce the min or max value, making them obvious candidates to provide.
   //
   // The checked_ family of math functions (add, sub, mul, div) will exist, but
   // the overflowing_/wrapping_ family is not useful by definition, as they allow an operation to
   // wrap to the MIN or MAX of a type.
   // 
   // saturating_ is possible, but would need to be falliable as it can only saturate in 
   // one direction, or alternatively all three questionable families could be made to work 
   // by defining them as working within the valid space of the type.
   // 
   // The methods behind the nonzero_bitwise and nonzero_ops feature flags would also be sensible.
}

Steps / History

(Remember to update the S-tracking-* label when checking boxes.)

• ACP: NonMaxU* and NonMinI* niche counterparts libs-team#721
• Implementation: #...
• Final comment period (FCP)¹
• Stabilization PR

Maintenance remarks

Unresolved Questions

• What action should be taken for overflowing_, wrapping_, and saturating_?

Footnotes

1. https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html ↩

[moonheart08]

@rustbot claim

[Amanieu]

Could this be extended to also support NonMax for signed integers? I don't think there's a good reason to restrict it to only unsigned integers.

[moonheart08]

Could this be extended to also support NonMax for signed integers? I don't think there's a good reason to restrict it to only unsigned integers.

I'm rolling with what was approved by the lang team, anything further is another ACP which is outside my current scope. It's a question to ask when further progress has been made, I think?

[tgross35]

No need to go through the ACP process again; Amanieu is on the libs-api team an can make those calls.

They don't necessarily need to come at the same time, however, if one is simpler or already done.

[tgross35]

At some point, I think it would be good to clarify whether we could support @kennytm's suggestion of a Ranged<usize, 0, {isize::MAX as usize}> type that is flexible enough to cover this and quite a bit more (e.g. NonNegative, rust-lang/libs-team#721 (comment)).

[moonheart08]

At some point, I think it would be good to clarify whether we could support @kennytm's suggestion of a Ranged<usize, 0, {isize::MAX as usize}> type that is flexible enough to cover this and quite a bit more (e.g. NonNegative, rust-lang/libs-team#721 (comment)).

It feels to me like this overlaps significantly with what pattern types are trying to be, and will likely face a lot of the same challenges. Currently, if we wanted this, I'd need to block the implementation on #136006, which is itself blocked. (I am experimenting with blocking on it, but I think the safer answer if we want this any time soon is to not do so.)

Without that PR, and other improvements to pattern types, the described Ranged type isn't implementable with a niche, which defeats the utility of putting it in the stdlib.

[moonheart08]

No need to go through the ACP process again; Amanieu is on the libs-api team an can make those calls.

They don't necessarily need to come at the same time, however, if one is simpler or already done.

Fair enough, was not aware. Actually doing the extension is trivial, but I wonder what to do with NonMin, where for unsized types they overlap NonZero. Personally I'd say this is simply okay to document as known overlap. It'd also reduce a little bit of duplication in the implementation, anyway, so it is beneficial, I'm simply being conservative with API surface.