nonany

nonany provides integer types with customizable niche values in stable rust. The main benefit of integer types with niches is that it enables the compiler to do memory layout optimization, such that an Option of an integer is the same size as the integer itself:

assert_eq!(
    core::mem::size_of::<Option<nonany::NonAnyU32<0xDEADBEEF>>>(),
    core::mem::size_of::<nonany::NonAnyU32<0xDEADBEEF>>());

Example

use nonany::NonAnyI8;

assert!(NonAnyI8::<20>::new(100).is_some(), "Values that aren't the niche can be stored");
assert!(NonAnyI8::<20>::new(20).is_none(), "The niche itself cannot be stored");

let foo = NonAnyI8::<20>::new(25).unwrap();
assert_eq!(foo.get(), 25, "The value can be loaded");

Provided types

nonmax defines generic types with user defined niches for all integer types, as well as type aliases common use cases:

How does it work?

Internally all NonAny* types use the NonZero* types from the standard library. When a value is stored in NonAny*, the value is stored in the internal NonZero* as an XOR of the value and the niche. Any value XORed with the niche that isn't the niche itself can never be zero, so this works out perfectly.

The upside of this technique is that it works on stable rust. The downside is that it requires an, albeit cheap, XOR operation to load and store the value. Additionally, unlike the NonZero* types, transmuting NonAny* types to their underlying integer types results in a value that was XORed with the niche, instead of the value itself.

MSRV

The MSRV is fixed at currently 1.56.0, and the intention is to keep it there at least until version 1.0 is released.

Similar libraries

• nonmax - Uses the same XOR technique to create types with an <int>::MAX niche. The equivalent in nonany would be to either use a niche of <int>::MAX, or the NonMax* type aliases.
• nook - Uses unstable rustc_ attributes to define balanced integers. The equivalent in nonany would be to either use a niche of <int>::MIN, or the NonMin* type aliases.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.