Expand description
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.
§Design
This contains variable-time, optimized algorithms for smaller big integers,
primarily, 256-bit integers. It supports a no_std environment, requiring
no allocation with all integers stored on the stack.
§Features
This crate is optimized for small variants of big integers, but a few additional types or functions can be enabled via the following features:
i384: Add the 384-bitI384andU384types.i512: Add the 512-bitI512andU512types.i1024: Add the 1024-bitI1024andU1024types.stdint: Support operations with fixed-width integer types. TheULimb,UWide, and other scalars defined may vary in size for optimal performance on the target architecture (64-bit multiplies, for example, are more expensive on 32-bit architectures): enabling this API adds in overloads foru32,u64, andu128, guaranteeing API stability across all platforms.num-traits: Implement traits from thenum-traitscrate for all integer types provided by this crate. Floating-point conversion methods are unimplemented and will panic. TheNumCasttrait andcastfunction, by their nature, will not be able cast values above what’s supported byu128ori128, even when casting between types supplied by this crate. All other traits and methods fromnum-traitswill behave as expected.
If you need larger integers, crypto-bigint has high-performance
addition, subtraction, and multiplication. With integers with a large
number of bits, it uses Karatsuba multiplication, which is significantly
asymptotically faster.
§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. However, using 256-bit x
64-bit multiplication, we can get a worst case scenario in 5 mul, 3 add,
and 6 sub instructions, with 2x+ better performance on both x86_64 and
aarch64.
This will, for obvious reasons, not support significantly larger type sizes. It is optimized only for a smaller number of bits.
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, orrug: 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
(variable-time calculations) and operations with native, scalar values. This
is particularly useful when doing incremental operations with native
integers, with performance improvements greater than 2 fold in many
cases,
Structs§
- I256
- The 256-bit signed integer type.
- I384
i386 - The 384-bit signed integer type.
- I512
i512 - The 512-bit signed integer type.
- I1024
i1024 - The 1024-bit signed integer type.
- Parse
IntError - An error which can be returned when parsing an integer.
- TryFrom
IntError - The error type returned when a checked integral type conversion fails.
- U256
- The 256-bit unsigned integer type.
- U384
i386 - The 384-bit unsigned integer type.
- U512
i512 - The 512-bit unsigned integer type.
- U1024
i1024 - The 1024-bit unsigned integer type.
Enums§
- IntError
Kind - Enum to store the various types of errors that can cause parsing an integer to fail.