Crate 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.

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-bit I384 and U384 types.
• i512: Add the 512-bit I512 and U512 types.
• i1024: Add the 1024-bit I1024 and U1024 types.
• stdint: Support operations with fixed-width integer types. The ULimb, 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 for u32, u64, and u128, guaranteeing API stability across all platforms.
• num-traits: Implement traits from the num-traits crate for all integer types provided by this crate. Floating-point conversion methods are unimplemented and will panic. The NumCast trait and cast function, by their nature, will not be able cast values above what’s supported by u128 or i128, even when casting between types supplied by this crate. All other traits and methods from num-traits will 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, 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 (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.

I384i386

The 384-bit signed integer type.

I512i512

The 512-bit signed integer type.

I1024i1024

The 1024-bit signed integer type.

ParseIntError

An error which can be returned when parsing an integer.

TryFromIntError

The error type returned when a checked integral type conversion fails.

U256

The 256-bit unsigned integer type.

U384i386

The 384-bit unsigned integer type.

U512i512

The 512-bit unsigned integer type.

U1024i1024

The 1024-bit unsigned integer type.

Enums

IntErrorKind

Enum to store the various types of errors that can cause parsing an integer to fail.

Type Aliases

ILimb

The same sized type of the limb as a signed integer.

IWide

A signed type double the width of the limb.

ULimb

The unsigned type used as a native “limb”.

UWide

An unsigned type double the width of the limb.

i256

The 256-bit signed integer type.

u256

The 256-bit unsigned integer type.