created_at2021-05-22 02:36:03.8351
updated_at2024-02-21 05:16:49.220955
descriptionArbitrary width integers
Aaron Kutch (AaronKutch)



Arbitrary Width Integers

This system of crates together forms a kind of big-integer library with separated storage and functional structs, manually controlled bitwidth, and bitwidth dependent operations. Instead of one struct that has all of the allocation and functional capabilities, there are 3 storage types which manage allocation: InlAwi, ExtAwi, and Awi. There is a common Bits reference type that manages fixed width arithmetical functionality. Most operations on Bits are const and have no allocations. Bits backed by InlAwi can perform big-integer arithmetic both at compile time and in a no-std runtime without any allocator at all. Bits backed by ExtAwi can use dynamic bitwidths at runtime. Awi has capacity and cheap bitwidth resizing. If a function is written purely in terms of Bits, then any mix of InlAwis, ExtAwis, and Awis can be used as arguments to that function with the help of their Deref<Target = Bits> impls.

A generic FP struct for fixed point numbers is also included, adding more functions for it is currently a WIP. In the future, Awi should also be able to have automatic resizing functions like in traditional bigint libraries.

Bits and InlAwi are provided by the awint_core crate. ExtAwi, Awi, and FP are provided by the awint_ext crate. The reason for this split is to provide maximum flexibility to no-std and no-alloc use cases. ExtAwi is not within awint_core under a feature flag, because if a no-alloc project depended on both awint_core and awint_macros (which requires ExtAwi), the flag would be activated for the common compilation of awint_core. The awint_macros crate is a proc-macro crate with several construction utilities. The awint_dag crate supplies a way to use awint types as a DSL (Domain Specific Language) for combinational logic. The awint crate compiles these interfaces together and enables or disables different parts of the system depending on these feature flags:

  • "const_support" turns on nightly features that are needed for many functions to be const
  • "alloc" turns on parts that require an allocator
  • "std" turns on parts that require std
  • "dag" turns on awint_dag
  • "try_support" turns on some features required for dag::Option and dag::Result to fully work
  • "debug" turns on some developer functions
  • "rand_support" turns on a dependency to rand_core without its default features
  • "serde_support" turns on a dependency to serde without its default features
  • "zeroize_support" turns on a dependency to zeroize without its default features

Note: By default, "std" and "try_support" is turned on, use default-features = false and select specific features to be more specific.

NOTE: As of Rust 1.70, if you try to use "const_support" with the macros you may get strange "erroneous constant used" and "deref_mut" errors unless you add all of


to all of the crate roots where you use the macros in const contexts.

NOTE: As of some versions of Rust starting around 1.70, "const_support" is unfortunately broken on nightly (see

Planned Features

These are currently unimplemented because of other developments and improvements that are being prioritized. Please open an issue or PR if you would like these implemented faster.

  • We need a macro for optimizing 2 input, 1 output functions to our inplace style functions. The base inplace assignment functions can have virtual counterparts (e.g. x.add_(y) would have the alternative z = x.add(y) or z = x + y) and the macro optimizes storage creation and routing.
  • Add some missing functions to the mimicking primitives in awint_dag
  • There are many things more to be done with awint_dag
  • Add more functions to FP
  • Some kind of matching macro
  • Add traditional big-integer library functions to Awi
  • Add a const Karatsuba algorithm to multiplication if possible, or add a fast_mul function to awint_ext
  • Better string serialization and deserialization performance. Most basic numerical functions are well optimized, but the serialization performance is currently very bad compared to what is possible.
  • Add custom allocator parameter to ExtAwi
  • Certain formatting and serialization trait impls need more work.
  • Make "const_support" compile on stable. Almost every unstable feature used by these crates is some kind of const feature, and will hopefully be stabilized soon.
Commit count: 218

cargo fmt