Crate intx

This crate provides new integer types with non-standard and fixed bitwidths such as U24, I48, U96 and so forth with a focus on data layout and alignment.

• All integers provided by this crate require the minimum number of bytes for their representation. For example, U24 requires 3 bytes, I48 requires 6 bytes.
• The alignment of all integer types provided by this crate is always 1. If another alignment is required it is recommended to wrap the integer type in a newtype and enforce an alignment via #[align(N)].
• As of now the provided integers do not have a rich set of arithmetic methods defined on them. It is instead expected to convert them to Rust primitive integers, apply the computation and eventually convert the result back. This might be supported in the future if requested.
• The binary representation of integer types provided by this crate is in twos-complement just like Rust’s built-in integer types.

Data Layout

All integer types provided by this crate internally consists of a single byte array. For example, the structure of U24 is struct U24([u8; 3]); allowing for optimal memory usage and an alignment of 1 (if needed).

API

Integer types provided by this crate only have very a minimal API surface.

• Traits implemented by all of the integer types are the following:

  • Clone, Copy, Default, Eq, PartialEq, Ord, PartialOrd, Hash
    • Common traits are all implemented as efficiently as possible for every integer type.
  • Debug, Display, Binary, Octal, LowerHex, UpperHex, LowerExp, UpperExp
    • Integer types mimick the display representation of the next larger Rust built-in integer type.

• Endian-aware conversion routines are also implemented:

  • from_ne_bytes, to_ne_bytes: Convert from and to native-endian bytes. (always efficient)
  • from_le_bytes, to_le_bytes: Convert from and to little-endian bytes.
  • from_be_bytes, to_be_bytes: Convert from and to big-endian bytes.

• Rich From and TryFrom implementations:

  • All provided integer types have a very rich set of From and TryFrom trait implementations to efficiently convert between different integer types and Rust built-in integers.

Example: Packed

Here the Rust compiler wastes 3 bytes for the discriminent of the enum.

pub enum Unpacked {
    A(u32), // We only use the lowest 24-bit of the integer.
    B(i16),
}
assert_eq!(core::mem::size_of::<Unpacked>(), 8);

Using intx::U24 the Rust compiler can properly pack the enum type wasting no bytes.

pub enum Packed {
    A(intx::U24), // Now using a type that reflects our usage intent properly.
    B(i16),
}
assert_eq!(core::mem::size_of::<Packed>(), 4);

Example: Alignment

With standard alignment the enum discriminent takes up a whopping 8 bytes.

pub enum Aligned {
    A(u64),
    B(i64),
}
assert_eq!(core::mem::size_of::<Aligned>(), 16);

Using intx integers with their alignment of 1 allows to pack the enum discrimant to a single byte.

pub enum Unaligned {
    A(intx::U64),
    B(intx::I64),
}
assert_eq!(core::mem::size_of::<Unaligned>(), 9);

Structs

• I16
  16-bit signed integer with alignment of 1.
• I24
  24-bit signed integer with alignment of 1.
• I32
  32-bit signed integer with alignment of 1.
• I40
  40-bit signed integer with alignment of 1.
• I48
  48-bit signed integer with alignment of 1.
• I56
  56-bit signed integer with alignment of 1.
• I64
  64-bit signed integer with alignment of 1.
• I72
  72-bit signed integer with alignment of 1.
• I80
  80-bit signed integer with alignment of 1.
• I88
  88-bit signed integer with alignment of 1.
• I96
  96-bit signed integer with alignment of 1.
• I104
  104-bit signed integer with alignment of 1.
• I112
  112-bit signed integer with alignment of 1.
• I120
  120-bit signed integer with alignment of 1.
• I128
  128-bit signed integer with alignment of 1.
• TryFromIntError
  Error that may occur for fallible conversions between integers.
• U16
  16-bit unsigned integer with alignment of 1.
• U24
  24-bit unsigned integer with alignment of 1.
• U32
  32-bit unsigned integer with alignment of 1.
• U40
  40-bit unsigned integer with alignment of 1.
• U48
  48-bit unsigned integer with alignment of 1.
• U56
  56-bit unsigned integer with alignment of 1.
• U64
  64-bit unsigned integer with alignment of 1.
• U72
  72-bit unsigned integer with alignment of 1.
• U80
  80-bit unsigned integer with alignment of 1.
• U88
  88-bit unsigned integer with alignment of 1.
• U96
  96-bit unsigned integer with alignment of 1.
• U104
  104-bit unsigned integer with alignment of 1.
• U112
  112-bit unsigned integer with alignment of 1.
• U120
  120-bit unsigned integer with alignment of 1.
• U128
  128-bit unsigned integer with alignment of 1.