Crate i24

Source
Expand description

§i24: A 24-bit Signed Integer Type

The i24 crate provides a 24-bit signed integer type for Rust, filling the gap between i16 and i32. This type is particularly useful in audio processing, certain embedded systems, and other scenarios where 24-bit precision is required but 32 bits would be excessive.

§Features

  • Efficient 24-bit signed integer representation
  • Seamless conversion to and from i32
  • Support for basic arithmetic operations with overflow checking
  • Bitwise operations
  • Conversions from various byte representations (little-endian, big-endian, native)
  • Implements common traits like Debug, Display, PartialEq, Eq, PartialOrd, Ord, and Hash

This crate came about as a part of the Wavers project, which is a Wav file reader and writer for Rust. The i24 struct also has pyo3 bindings for use in Python. Enable the pyo3 feature to use the pyo3 bindings.

§Usage

Add this to your Cargo.toml:

[dependencies]
i24 = "2.0.0"

Then, in your Rust code:


let a = i24!(1000);
let b = i24!(2000);
let c = a + b;
assert_eq!(c.to_i32(), 3000);
assert_eq!(c, i24!(3000));

§Safety and Limitations

While i24 strives to behave similarly to Rust’s built-in integer types, there are some important considerations:

  • The valid range for i24 is [-8,388,608, 8,388,607].
  • Overflow behavior in arithmetic operations matches that of i32.
  • Bitwise operations are performed on the 24-bit representation.

Always use checked arithmetic operations when dealing with untrusted input or when overflow/underflow is a concern.

§Features

  • pyo3: Enables the pyo3 bindings for the i24 type.

§Contributing

Contributions are welcome! Please feel free to submit a Pull Request. This really needs more testing and verification.

§License

This project is licensed under MIT - see the LICENSE file for details.

Macros§

i24
creates an i24 from a constant expression will give a compile error if the expression overflows an i24

Structs§

i24
An experimental 24-bit signed integer type.

Functions§

from_str_error
negative_overflow
positive_overflow