Crate nonany

Source
Expand description

§nonany

crates.io docs msrv

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.

Structs§

NonAnyI8
An integer that is known not to equal NICHE.
NonAnyI16
An integer that is known not to equal NICHE.
NonAnyI32
An integer that is known not to equal NICHE.
NonAnyI64
An integer that is known not to equal NICHE.
NonAnyI128
An integer that is known not to equal NICHE.
NonAnyIsize
An integer that is known not to equal NICHE.
NonAnyU8
An integer that is known not to equal NICHE.
NonAnyU16
An integer that is known not to equal NICHE.
NonAnyU32
An integer that is known not to equal NICHE.
NonAnyU64
An integer that is known not to equal NICHE.
NonAnyU128
An integer that is known not to equal NICHE.
NonAnyUsize
An integer that is known not to equal NICHE.

Enums§

CheckedError
An error type used to differentiate between overflow and niche errors.

Type Aliases§

NonMaxI8
An integer that is known not to equal i8::MAX.
NonMaxI16
An integer that is known not to equal i16::MAX.
NonMaxI32
An integer that is known not to equal i32::MAX.
NonMaxI64
An integer that is known not to equal i64::MAX.
NonMaxI128
An integer that is known not to equal i128::MAX.
NonMaxIsize
An integer that is known not to equal isize::MAX.
NonMaxU8
An integer that is known not to equal u8::MAX.
NonMaxU16
An integer that is known not to equal u16::MAX.
NonMaxU32
An integer that is known not to equal u32::MAX.
NonMaxU64
An integer that is known not to equal u64::MAX.
NonMaxU128
An integer that is known not to equal u128::MAX.
NonMaxUsize
An integer that is known not to equal usize::MAX.
NonMinI8
An integer that is known not to equal i8::MIN.
NonMinI16
An integer that is known not to equal i16::MIN.
NonMinI32
An integer that is known not to equal i32::MIN.
NonMinI64
An integer that is known not to equal i64::MIN.
NonMinI128
An integer that is known not to equal i128::MIN.
NonMinIsize
An integer that is known not to equal isize::MIN.
NonMinU8
An integer that is known not to equal u8::MIN.
NonMinU16
An integer that is known not to equal u16::MIN.
NonMinU32
An integer that is known not to equal u32::MIN.
NonMinU64
An integer that is known not to equal u64::MIN.
NonMinU128
An integer that is known not to equal u128::MIN.
NonMinUsize
An integer that is known not to equal usize::MIN.
NonZeroI8
An integer that is known not to equal zero.
NonZeroI16
An integer that is known not to equal zero.
NonZeroI32
An integer that is known not to equal zero.
NonZeroI64
An integer that is known not to equal zero.
NonZeroI128
An integer that is known not to equal zero.
NonZeroIsize
An integer that is known not to equal zero.
NonZeroU8
An integer that is known not to equal zero.
NonZeroU16
An integer that is known not to equal zero.
NonZeroU32
An integer that is known not to equal zero.
NonZeroU64
An integer that is known not to equal zero.
NonZeroU128
An integer that is known not to equal zero.
NonZeroUsize
An integer that is known not to equal zero.