1 unstable release
0.1.0 | May 15, 2023 |
---|
#4 in #unsigned
4,212 downloads per month
Used in 10 crates
(2 directly)
100KB
2K
SLoC
[2]: https://github.com/Robbepop/intx/actions/workflows/rust.yml [4]: https://docs.rs/intx [6]: https://crates.io/crates/intx
Continuous Integration | Documentation | Crates.io |
---|---|---|
[][2] | [][4] | [][6] |
intx
- Non-standard fixed bitwidth integers for Rust
WARNING: This crate is not yet production ready as it is missing lots of tests.
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
andTryFrom
implementations:- All provided integer types have a very rich set of
From
andTryFrom
trait implementations to efficiently convert between different integer types and Rust built-in integers.
- All provided integer types have a very rich set of
Usage
The focus of this crate is data layout, alignment and space-optization.
It was crafted as an experiment when the wasmi
interpreter
required a more memory efficient representation of its internal bytecode.
For example using a 3 bytes sized U24
instead of a 4 byte sized u32
in certain places allows the Rust
compiler to pack data structures more efficiently in some cases,
especially when using enum
types.
If your primary focus is on the logical side where you are mostly interested in
arithmetic operations on integer types with non-standard but fixed bitwidths then
maybe the ux
crate is a better fit for you.
Alternatives
The alternative ux
crate provides non-standard
and fixed bitwidth integers as well but the focus of both crates is very different.
Property | intx |
ux |
---|---|---|
size_of |
All integer types require the minimum number of bytes for their representation. For example, size_of<intx::U24>() == 3 |
All integer types have the same size_of as the next biggest Rust built-in integer primitive. For example, size_of<ux::u24>() == size_of<u32>() == 4 |
align_of |
All integer types have an alignment of 1. If another alignment is needed it is possible to wrap the integer type in a newtype and enforce another alignment via #[align(N)] |
All integer types have the same align_of as the next biggest Rust built-in integer primitive. For example align_of<ux::u24>() == align_of<u32> == 4 . |
Focus | Data layout and alignment of packed data structures using integers. | Arithmetic operations on non-standard bitwidth integer types. |
API | Integer types provide a minimal API surface. Mostly From and TryFrom impls between integers and Rust primitives as well as endian-aware byte conversions known from Rust primitives such as to_ne_bytes and from_le_bytes . |
Integer types try to mimick Rust built-in integer types providing a fair amount of arithmetic operations on them. |
Both crates provide rich support for conversions between different integer types and Rust primitives.
License
Licensed under either of
-
Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
-
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
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.