i256

Optimized implementations of 256-bit signed and unsigned integers.

This contains a fixed-width, performant implementation for 256-bit signed and unsigned integers. This has significantly faster performance for basic math operations than comparable fixed-width integer types, since it can use optimizations from 128-bit integers on 64-bit architectures.

Use Case

i256 is for a very specific purpose: relatively high-performance, fixed-sized 256-bit integers. This is dependent on support for native 64-bit integer multiplies on the architecture, and highly benefits from 64-bit to 128-bit widening multiplies (supported on x86_64). For example, on x86_64, we can get 256-bit multiplications in at worst 10 multiplies and 15 adds, and significantly faster in most cases. Likewise, 256-bit addition/subtraction is in 6 adds/subtracts, significantly more efficient than building from smaller type sizes.

This will, for obvious reasons, not support larger type sizes. 512+ bit integers require types comprised of an array of limbs, sacrificing performance for this specific use-case in their design. If you need anything else, you probably want one of the following libraries:

bnum: Arbitrary-precision, fixed-width, big integer support.
crypto-bigint: Constant-time, arbitrary-precision, fixed-width, big integer support suitable for cryptographically secure applications.
num-bigint, malachite, or rug: Dynamic-width big integers with high-performance calculations with very large integers.

Specifically, i256 has optimizations that would be considered anti-features for these libraries: better performance for smaller values, and operations with native, scalar values. This is particularly useful when doing incremental operations with native integers.

Versioning and Version Support

Rustc Compatibility

i256 currently supports 1.59+, including stable, beta, and nightly. This aims to support at least the Rust included in the latest stable Debian release.

Please report any errors compiling a supported i256 version on a compatible Rustc version.

Versioning

i256 uses semantic versioning. Removing support for Rustc versions newer than the latest stable Debian or Ubuntu version is considered an incompatible API change, requiring a major (minor pre-1.0) version change.

Changelog

All changes are documented in CHANGELOG.

License

i256 is dual licensed under the Apache 2.0 license as well as the MIT license.

Almost all of the accessory methods in ints, such as the checked_*, unchecked_*, strict_*, and others, including their documentation, are taken directly from the Rust implementation, specifically, uint_macros and int_macros. The core algorithms under math for numeric operations, both their wrapping and overflowing forms, are not.

Contributing