feat: introduce NonZeroU* types with null-pointer optimization

[hubcycle]

Description

Currently, oblux only provides U7, U15, U31, U63, U127 types and each one contains the corresponding underlying u* type. We want to introduce the following NonZero* types:

NonZeroU7
NonZeroU15
NonZeroU31
NonZeroU63
NonZeroU127

Implementation

Introduce the above types that will wrap the corresponding NonZeroU* types from the core library. We're specifically interested in the memory layout when wrapped by an Option. The implemented representation must use null pointer optimization.

Test

Add new doc tests to verify the constraints.

Acceptance Criteria

• cargo build succeeds.
• size_of::<Option<NonZeroU7>>() == size_of::<NonZeroU7>() == size_of::<U7>().
• size_of::<Option<NonZeroU15>>() == size_of::<NonZeroU15>() == size_of::<U15>().
• size_of::<Option<NonZeroU31>>() == size_of::<NonZeroU31>() == size_of::<U31>().
• size_of::<Option<NonZeroU63>>() == size_of::<NonZero63>() == size_of::<U63>().
• size_of::<Option<NonZeroU127>>() == size_of::<NonZeroU127>() == size_of::<U127>().

[ashucrma]

I want to work on this.
Can I pick it up?

[ashucrma]

I have done a small POC by building a struct first for NonZeroU7.
Here's the code:

// use std::num::NonZeroU8;   <---- not using std since oblux is a #![no_std] crate and using std will fail the crate to compile 
use core::num::NonZeroU8;     // using core instead

// #[repr(transparent)] // Can add this for layout gaurantee
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub struct NonZeroU7(NonZeroU8);

impl NonZeroU7 {

	pub const MIN: Self = Self(NonZeroU8::MIN);

	pub const MAX: Self = Self(Self::INNER_MAX);

	pub const ONE: Self = Self(NonZeroU8::new(1).unwrap());

	pub const TWO: Self = Self(NonZeroU8::new(2).unwrap());

	pub const THREE: Self = Self(NonZeroU8::new(3).unwrap());

	const INNER_MAX: NonZeroU8 = NonZeroU8::new(i8::MAX as u8).unwrap();

	pub const fn new(x: NonZeroU8) -> Option<Self> {
		if x.get() <= Self::INNER_MAX.get() {     // have to use .get() here due to rust issue: https://github.com/rust-lang/rust/issues/143874
			Some(Self(x))
		} else {
			None
		}
	}

	pub const fn from_signed(x: i8) -> Option<Self> {
		if x <= 0 { None } else { Self::new(NonZeroU8::new(x as u8).unwrap()) }
	}

    pub const fn from_unsigned(x: u8) -> Option<Self> {
		// if x == 0 { None } else { Self::new(NonZeroU8::new(x).unwrap()) }  
		if x == 0 || x > Self::INNER_MAX.get() { None } else { Self::new(NonZeroU8::new(x).unwrap()) }   // more explicit
	}

	pub const fn get(self) -> NonZeroU8 {
		self.0
	}

	pub const fn to_signed(self) -> i8 {
		self.get().get() as i8        // or can make it self.0.get()
	}

    pub const fn to_unsigned(self) -> u8 {
		self.get().get()
	}
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_non_zero_u7_constants() {
        // Test MIN (Should be NonZeroU8::MIN which is 1)
        assert_eq!(NonZeroU7::MIN.get().get(), 1);

        // Test MAX (Should be i8::MAX which is 127)
        assert_eq!(NonZeroU7::MAX.get().get(), i8::MAX as u8);

        // Test helper constants
        assert_eq!(NonZeroU7::ONE.get().get(), 1);
        assert_eq!(NonZeroU7::TWO.get().get(), 2);
        assert_eq!(NonZeroU7::THREE.get().get(), 3);
    }

    #[test]
    fn test_non_zero_u7_conversions() {
        // Test valid creation
        let non_zero_u8val: NonZeroU8 = NonZeroU8::new(100).unwrap();
        let non_zero_u7val = NonZeroU7::new(non_zero_u8val);
        assert!(non_zero_u7val.is_some());
        assert_eq!(non_zero_u7val.unwrap().get(), non_zero_u8val);

        // Test overflow creation (128 is > i8::MAX)
        let invalid = NonZeroU7::new(NonZeroU8::new(128).unwrap());
        assert!(invalid.is_none());

        // Test signed conversion
        let signed_val: i8 = non_zero_u7val.unwrap().to_signed();
        assert_eq!(signed_val, 100);

        // Test unsigned conversion
        let unsigned_val: u8 = non_zero_u7val.unwrap().to_unsigned();
        assert_eq!(unsigned_val, 100);

        // Test from_signed
        assert!(NonZeroU7::from_signed(127).is_some());
        assert!(NonZeroU7::from_signed(0).is_none());
        assert!(NonZeroU7::from_signed(-1).is_none());

        // Test from_unsigned
        assert!(NonZeroU7::from_unsigned(127).is_some());
        assert!(NonZeroU7::from_unsigned(234).is_none());
        assert!(NonZeroU7::from_unsigned(0).is_none());
    }

        #[test]
    fn test_non_zero_u7_size_tests() {
        // matching sizes with other related types
        assert_eq!(size_of::<Option<NonZeroU7>>(), size_of::<NonZeroU7>());
        assert_eq!(size_of::<NonZeroU7>(), size_of::<NonZeroU8>());
        assert_eq!(size_of::<Option<NonZeroU7>>(), size_of::<Option<NonZeroU8>>());

        // explicit size test
        assert_eq!(size_of::<NonZeroU7>(), 1);
        assert_eq!(size_of::<Option<NonZeroU7>>(), 1);   // <-- ensures niche optimization https://doc.rust-lang.org/std/num/struct.NonZero.html#layout-1
    }
}

It's passing all tests and the acceptance criteria:

[ashucrma]

While working on the above POC, I stumbled upon few doubts and concerns.
Can you please provide me these clarifications:

1. Do we want to use #[repr(transparent)] ?
   Reasons I think It should be included:

• NPO is the goal, but needs a formal guarantee. The whole point of wrapping NonZeroU* types is to preserve the null pointer optimization so that Option<NonZeroU7> is the same size as NonZeroU7. Without #[repr(transparent)], this holds in practice but is not guaranteed by the language spec — it's just a compiler implementation detail that could change.

• #[repr(transparent)] makes it spec-guaranteed. It formally requires the struct to have the exact same memory layout as its single non-zero-sized field, which means the niche (the zero value) of the inner NonZeroU* is preserved through the newtype. The size assertion size_of::<Option<NonZeroU7>>() == size_of::<NonZeroU7>() goes from "incidentally true" to "guaranteed by the ABI".

• Different situation from the existing U types.* The existing U7(u8) etc. don't need it because u8 has no niche to preserve. But for NonZeroU7(NonZeroU8), the niche is the entire reason the type exists, so we should protect it explicitly.

• Enables safe transmutation. #[repr(transparent)] also allows safe casting/transmutation between NonZeroU7 and NonZeroU8 via bytemuck or similar, which could be useful for interop down the line.

2. The PartialOrd on structs isn't const-stable yet ( issue #143874: Tracking Issue for RFC 3762, "Make trait methods callable in const contexts" rust-lang/rust#143874 is yet to be resolved). I've no option but to use the idiomatic .get() in a lot of places due to that.
   I'd love to know if there is a better solution to this.

3. Due to subtle differences in code of NonZero types, the macros would be separate set for these types or you want me to implement them in that same set of macros?

4. I've tried to add to extra conversions from_unsigned() and to_unsigned(), do we require them?

Once I get these clarifications. I'll proceed to macrofy the code and extend the implementation to other bit sizes.

[hubcycle]

As discussed offline, we'll close #5 first.

[ashucrma]

Restarting work on this as #5 is closed.

[ashucrma]

I’ve refactored the NonZeroU7 implementation based on our discussion to prioritize zero-cost abstractions and API minimalism. Here’s a summary of the optimizations:

1. Zero-Cost Construction (Eliminating Branching)
   I’ve replaced all instances of .unwrap() and NonZeroU8::new() with unsafe { NonZeroU8::new_unchecked() } in paths where the value is already mathematically proven to be non-zero. This removes unnecessary panic-handling blocks and redundant x == 0 CPU checks.

Constants: ONE, TWO, THREE, and INNER_MAX now use new_unchecked.
Conversions: In from_signed, once the bounds check passes, we wrap the value immediately without re-validating the "non-zero" property.

2. Optimized from_signed Logic
   I realized that for an i8, if x > 0, it is logically impossible for x to exceed 127.

The Optimization: I removed the upper-bound check entirely for from_signed. It now performs a single comparison (x > 0), making it the fastest possible way to construct this type from a signed integer.

3. Thoughtful API & Integration
   To keep the crate focused on its core value (one-bit-less types) while encouraging integration with the standard library:

Lean get(): The get() method returns the underlying NonZeroU8. This allows users to access all standard NonZero methods (like bitwise operations or TrailingZeros) without us having to duplicate that API surface.

Removed to_unsigned(): I’ve removed this to avoid API bloat. Since get() returns a NonZeroU8, users can simply chain .get().get() if they need the raw primitive.

Kept to_signed(): I retained this as it remains the primary use case for oblux—providing an infallible path to signed types.

4. Layout & Safety
   Removed #[repr(transparent)]: Per your request, I’ve left this out for now to allow for further research, though the current tests confirm that the compiler is already performing niche optimization as expected.

no_std Compliance: Ensured all imports are from core to maintain compatibility with embedded environments.

Here's the code:

use core::num::NonZeroU8;  

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub struct NonZeroU7(NonZeroU8);

impl NonZeroU7 {

	pub const MIN: Self = Self(NonZeroU8::MIN);

	pub const MAX: Self = Self(Self::INNER_MAX);

	pub const ONE: Self = Self::MIN;

	pub const TWO: Self = Self(unsafe{ NonZeroU8::new_unchecked(2) });

	pub const THREE: Self = Self(unsafe{ NonZeroU8::new_unchecked(3) });

	const INNER_MAX: NonZeroU8 = unsafe{ NonZeroU8::new_unchecked(i8::MAX as u8) };

	pub const fn new(x: NonZeroU8) -> Option<Self> {
		if x.get() <= Self::INNER_MAX.get() { 
			Some(Self(x))
		} else {
			None
		}
	}

	pub const fn from_signed(x: i8) -> Option<Self> {
		if x <= 0 { None } else { Some(Self(unsafe{ NonZeroU8::new_unchecked(x as u8) })) }
	}

	pub const fn get(self) -> NonZeroU8 {
		self.0
	}

	pub const fn to_signed(self) -> i8 {
		self.0.get() as i8       
	}
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_non_zero_u7_constants() {
        // Test MIN (Should be NonZeroU8::MIN which is 1)
        assert_eq!(NonZeroU7::MIN.get().get(), 1);

        // Test MAX (Should be i8::MAX which is 127)
        assert_eq!(NonZeroU7::MAX.get().get(), i8::MAX as u8);

        // Test helper constants
        assert_eq!(NonZeroU7::ONE.get().get(), 1);
        assert_eq!(NonZeroU7::TWO.get().get(), 2);
        assert_eq!(NonZeroU7::THREE.get().get(), 3);
    }

    #[test]
    fn test_non_zero_u7_conversions() {
        // Test valid creation
        let non_zero_u8val: NonZeroU8 = NonZeroU8::new(100).unwrap();
        let non_zero_u7val = NonZeroU7::new(non_zero_u8val);
        assert!(non_zero_u7val.is_some());
        assert_eq!(non_zero_u7val.unwrap().get(), non_zero_u8val);

        // Test overflow creation (128 is > i8::MAX)
        let invalid = NonZeroU7::new(NonZeroU8::new(128).unwrap());
        assert!(invalid.is_none());

        // Test signed conversion
        let signed_val: i8 = non_zero_u7val.unwrap().to_signed();
        assert_eq!(signed_val, 100);

        // Test from_signed
        assert!(NonZeroU7::from_signed(127).is_some());
        assert!(NonZeroU7::from_signed(0).is_none());
        assert!(NonZeroU7::from_signed(-1).is_none());
    }

        #[test]
    fn test_non_zero_u7_size_tests() {
        // matching sizes with other related types
        assert_eq!(size_of::<Option<NonZeroU7>>(), size_of::<NonZeroU7>());
        assert_eq!(size_of::<NonZeroU7>(), size_of::<NonZeroU8>());
        assert_eq!(size_of::<Option<NonZeroU7>>(), size_of::<Option<NonZeroU8>>());

        // explicit size test
        assert_eq!(size_of::<NonZeroU7>(), 1);
        assert_eq!(size_of::<Option<NonZeroU7>>(), 1);   // <-- ensures niche optimization https://doc.rust-lang.org/std/num/struct.NonZero.html#layout-1
    }
}

It's passing all tests and the acceptance criteria:

Once you verify this, I'll proceed to macrofy the code and extend the implementation to other bit sizes.

Edit:
I have one question:

1. Is the constant ONE required?
   Given that MIN also has the same value for NonZero types. I understand, it was required in U7 because there the MIN was 0. Do we really require this constant, or should I remove it?

[rotorship]

pub const TWO: Self = Self(unsafe{ NonZeroU8::new_unchecked(2) });

The const lines should not use unsafe and we can continue with the unwrap calls as this is evaluated during compile time, so we don't pay any runtime penalty.

[rotorship]

pub const fn from_signed(x: i8) -> Option<Self> {
	if x <= 0 { None } else { Some(Self(unsafe{ NonZeroU8::new_unchecked(x as u8) })) }
}

I feel this constructor should accept NonZeroI8 instead of a plain i8. This way we get push the if branch checking for non-positive value to the caller side

pub const fn from_signed(x: NonZeroI8) -> Option<Self> {
	Some(Self( unsafe { NonZeroU8::new_unchecked(x.get() as u8) }))
}

[rotorship]

I believe to_signed should also return a NonZeroI8 instead of plain i8. The user can then invoke get on the returned instance to obtain an i8.

[ashucrma]

I feel this constructor should accept NonZeroI8 instead of a plain i8. This way we get push the if branch checking for non-positive value to the caller side

That's a very thoughtful idea of taking NonZeroI8 instead of i8 — it's a much cleaner API and pushes zero-checking to the caller.

One thing I noticed though: NonZeroI8 guarantees non-zero, but not positive — values like -1 or -128 are valid NonZeroI8 instances. So if we skip the negativity check entirely as suggested:

pub const fn from_signed(x: NonZeroI8) -> Option {
Some(Self( unsafe { NonZeroU8::new_unchecked(x.get() as u8) }))
}

a caller passing -1 would cast to u8 (wrapping to 255) and then construct a NonZeroU7 with an invalid inner value, silently breaking the type invariant.

I think we still need the negativity check, but we can make it branchless and cheap:

pub const fn from_signed(x: NonZeroI8) -> Option<Self> {
    if x.get() < 0 {
        None
    } else {
        // Safety: x is non-zero (NonZeroI8 invariant) and non-negative (checked above),
        // so x is in [1, 127] which is valid for both NonZeroU8 and NonZeroU7
        Some(Self(unsafe { NonZeroU8::new_unchecked(x.get() as u8) }))
    }
}

The unsafe is still justified here since once we confirm x > 0, the value is guaranteed to be in [1, 127], which satisfies both the NonZeroU8 and NonZeroU7 invariants. We just can't skip the sign check entirely.

I verified as well, this particular testcase:

assert!(NonZeroU7::from_signed(NonZeroI8::new(-1).unwrap()).is_none());

failed when not checking the <0 case

Let me know your thoughts on this!

[ashucrma]

pub const TWO: Self = Self(unsafe{ NonZeroU8::new_unchecked(2) });

The const lines should not use unsafe and we can continue with the unwrap calls as this is evaluated during compile time, so we don't pay any runtime penalty.

Yes, you are right. Reverting the constants to unwrap() as earlier.

I believe to_signed should also return a NonZeroI8 instead of plain i8. The user can then invoke get on the returned instance to obtain an i8.

Yes, makes sense. Making this change

Here's the code with these 3 updates:

use core::num::NonZeroU8;  
use core::num::NonZeroI8; 

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub struct NonZeroU7(NonZeroU8);

impl NonZeroU7 {

	pub const MIN: Self = Self(NonZeroU8::MIN);

	pub const MAX: Self = Self(Self::INNER_MAX);

	pub const ONE: Self = Self::MIN;

	pub const TWO: Self = Self(NonZeroU8::new(2).unwrap());

	pub const THREE: Self = Self(NonZeroU8::new(3).unwrap());

	const INNER_MAX: NonZeroU8 = NonZeroU8::new(i8::MAX as u8).unwrap();

	pub const fn new(x: NonZeroU8) -> Option<Self> {
		if x.get() <= Self::INNER_MAX.get() { 
			Some(Self(x))
		} else {
			None
		}
	}

    pub const fn from_signed(x: NonZeroI8) -> Option<Self> {
        if x.get() < 0 {
            None
        } else {
            Some(Self(unsafe { NonZeroU8::new_unchecked(x.get() as u8) }))
        }
    }

	pub const fn get(self) -> NonZeroU8 {
		self.0
	}

	pub const fn to_signed(self) -> NonZeroI8 {
		unsafe { NonZeroI8::new_unchecked(self.0.get() as i8) }      
	}
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_non_zero_u7_constants() {
        // Test MIN (Should be NonZeroU8::MIN which is 1)
        assert_eq!(NonZeroU7::MIN.get().get(), 1);

        // Test MAX (Should be i8::MAX which is 127)
        assert_eq!(NonZeroU7::MAX.get().get(), i8::MAX as u8);

        // Test helper constants
        assert_eq!(NonZeroU7::ONE.get().get(), 1);
        assert_eq!(NonZeroU7::TWO.get().get(), 2);
        assert_eq!(NonZeroU7::THREE.get().get(), 3);
    }

    #[test]
    fn test_non_zero_u7_conversions() {
        // Test valid creation
        let non_zero_u8val: NonZeroU8 = NonZeroU8::new(100).unwrap();
        let non_zero_i8val: NonZeroI8 = NonZeroI8::new(100).unwrap();
        let non_zero_u7opt = NonZeroU7::new(non_zero_u8val);
        assert!(non_zero_u7opt.is_some());
        assert_eq!(non_zero_u7opt.unwrap().get(), non_zero_u8val);

        // Test overflow creation (128 is > i8::MAX)
        let invalid = NonZeroU7::new(NonZeroU8::new(128).unwrap());
        assert!(invalid.is_none());

        // Test signed conversion
        let non_zero_signed_val: NonZeroI8 = non_zero_u7opt.unwrap().to_signed();
        assert_eq!(non_zero_signed_val, non_zero_i8val);

        // Test from_signed
        assert!(NonZeroU7::from_signed(NonZeroI8::new(127).unwrap()).is_some());
        // assert!(NonZeroU7::from_signed(NonZeroI8::new(0).unwrap()).is_none());
        assert!(NonZeroU7::from_signed(NonZeroI8::new(-1).unwrap()).is_none());
    }

        #[test]
    fn test_non_zero_u7_size_tests() {
        // matching sizes with other related types
        assert_eq!(size_of::<Option<NonZeroU7>>(), size_of::<NonZeroU7>());
        assert_eq!(size_of::<NonZeroU7>(), size_of::<NonZeroU8>());
        assert_eq!(size_of::<Option<NonZeroU7>>(), size_of::<Option<NonZeroU8>>());

        // explicit size test
        assert_eq!(size_of::<NonZeroU7>(), 1);
        assert_eq!(size_of::<Option<NonZeroU7>>(), 1);   // <-- ensures niche optimization https://doc.rust-lang.org/std/num/struct.NonZero.html#layout-1
    }
}

The tests have also been updated:

It's passing all tests and the acceptance criteria:

This question got missed, can you confirm this:

I have one question:

1. Is the constant ONE required?
   Given that MIN also has the same value for NonZero types. I understand, it was required in U7 because there the MIN was 0. Do we really require this constant, or should I remove it?

Once you verify (one last time 🤞) and confirm, I'll proceed to macrofy the code and extend the implementation to other bit sizes.