Rust uint crate using const-generics
Implements [Uint<BITS, LIMBS>], the ring of numbers modulo
# use ruint::Uint;
let answer: Uint<256, 4> = Uint::from(42);
You can compute LIMBS yourself using LIMBS equals BITS divided by Uint] will panic! if you try to construct it with incorrect arguments. Ideally this would be a compile time error, but that is blocked by Rust issue #60551.
A more convenient method on stable is to use the [uint!] macro, which constructs the right [Uint] for you.
# use ruint::{Uint, uint};
let answer = uint!(42_U256);
You can also use one of the pre-computed type [aliases]:
# use ruint::Uint;
use ruint::aliases::*;
let answer: U256 = Uint::from(42);
You can of course also create your own type alias if you need a funny size:
# use ruint::Uint;
type U1337 = Uint<1337, 21>;
let answer: U1337 = Uint::from(42);
Rust nightly
If you are on nightly, you can use [Uint<BITS>][nightly::Uint] which will compute the number of limbs for you. Unfortunately this can not be made stable without generic_const_exprs support (Rust issue #76560).
# #[cfg(has_generic_const_exprs)] {
use ruint::nightly::Uint;
let answer: Uint<256> = Uint::<256>::from(42);
# }
Even on nightly, the ergonomics of Rust are limited. In the example above Rust requires explicit type annotation for [Uint::from], where it did not require it in the stable version. There are a few more subtle issues that make this less ideal than it appears. It also looks like it may take some time before these nightly features are stabilized.
Examples
use ruint::Uint;
let a: Uint<256, 4> = Uint::from(0xf00f_u64);
let b: Uint<256, 4> = Uint::from(42_u64);
let c = a + b;
assert_eq!(c, Uint::from(0xf039_u64));
There is a convenient macro [uint!] to create constants for you. It allows for arbitrary length constants using standard Rust integer syntax. The size of the [Uint] is specified with a U suffix followed by the number of bits. The standard Rust syntax of decimal, hexadecimal and even binary and octal is supported using their prefixes 0x, 0b and 0o. Literals can have underscores _ added for readability.
# use ruint::uint;
let cow = uint!(0xc85ef7d79691fe79573b1a7064c19c1a9819ebdbd1faaab1a8ec92344438aaf4_U256);
In fact, this macro recurses down the parse tree, so you can apply it to entire source files:
# use ruint::uint;
uint!{
let a = 42_U256;
let b = 0xf00f_1337_c0d3_U256;
let c = a + b;
assert_eq!(c, 263947537596669_U256);
}
Feature flags
There is support for a number of crates. These are enabled by setting the identically named feature flag.
unstableEnable sem-ver unstable features.rand: Implements sampling from theStandarddistribution, i.e.rng.gen().arbitrary: Implements theArbitrarytrait, allowing [Uint]s to be generated for fuzz testing.quickcheck: Implements theArbitrarytrait, allowing [Uint]s to be generated for property based testing.proptest: Implements theArbitrarytrait, allowing [Uint]s to be generated for property based testing. Proptest is used for theuints own test suite.serde: Implements theSerializeandDeserializetraits for [Uint] using big-endian hex in human readable formats and big-endian byte strings in machine readable formats.rlp: Implements theEncodableandDecodabletraits for [Uint] to allow serialization to/from RLP.fastrlp: Implements theEncodableandDecodabletraits for [Uint] to allow serialization to/from RLP.primitive-types: Implements the [From<_>] conversions between corresponding types.postgres: Implements theToSqltrait supporting many column types.
Building and testing
Format, lint, build and test everything (I recommend creating a shell alias for this):
cargo fmt &&\
cargo clippy --all-features --all-targets &&\
cargo test --workspace --all-features --doc -- --nocapture &&\
cargo test --workspace --all-features --all-targets -- --nocapture &&\
cargo doc --workspace --all-features --no-deps
Run benchmarks with the provided .cargo/config.toml alias
cargo criterion
Check documentation coverage
RUSTDOCFLAGS="-Z unstable-options --show-coverage" cargo doc --workspace --all-features --no-deps
To do
Goals:
- All the quality of life features one could want.
- Compatible with std
u64, etc types. See Rust's integer methods. - Builds
no-stdandwasm. - Fast platform agnostic generic algorithms.
- Target specific assembly optimizations (where available).
- Optional num-traits, etc, support.
- Adhere to Rust API Guidelines
Maybe:
- Run-time sized type with compatible interface.
- Montgomery REDC and other algo's for implementing prime fields.
63 Jan 2, 2023
51 Aug 20, 2020
12 Jul 27, 2022
14 Dec 29, 2022
40 Jun 2, 2023
8 Sep 13, 2022
68 Dec 1, 2022
93 Jan 7, 2023
126 Dec 30, 2022
194 Jan 3, 2023
14 Dec 5, 2022
2 Dec 14, 2022
229 Nov 27, 2022
1.9k Jan 7, 2023
37 Dec 18, 2022
17 Nov 28, 2022
0 Dec 19, 2022
5 Oct 31, 2022
4 Feb 9, 2023