Module number 

Provides various number types, including small primitive-based integers, memory-sharing integer unions, and fixed-size big integers.

Introduction

This module defines the foundational numeric types used throughout the cryptocol ecosystem, categorized by their size and intended use:

• Small Numbers: Primitive-sized integers (up to 128-bit) and specialized unions for bit manipulation.
• Big Numbers: High-precision, fixed-size unsigned integers designed for cryptographic operations.

Architectural Background

Generic Programming for Primitives

Rust lacks a unified trait for all primitive numeric types (e.g., u8 through u128, usize). The SmallUInt trait provides this abstraction, enabling the implementation of generic algorithms across unsigned primitive types.

Extended Primitive Functionality

Beyond standard arithmetic, SmallUInt introduces auxiliary methods for common cryptographic and low-level tasks not natively provided by Rust primitives.

Arithmetic for Big Numbers

Cryptographic algorithms, such as RSA, require integers far exceeding the 128-bit limit of standard types. This module provides highly optimized algorithms for calculating 256-bit, 1024-bit, and even larger integers.

Documentation Policy

Parts of the documentation for this module are adapted from the Rust standard library. This applies specifically to methods that implement standard operations (e.g., arithmetic operators, from_str, to_be) to maintain consistency with familiar interfaces and semantics.

1. Small Numbers

Foundational types for Big Numbers and other cryptographic modules.

• SmallUInt: Trait providing a generic interface and additional methods for unsigned primitive integers.

Integer Unions

Unions designed for efficient type conversion and byte-level manipulation between different integer sizes and arrays.

• ShortUnion: Interop between u16, i16, [u8; 2], and [i8; 2].
• IntUnion: Interop between u32, i32, and 16/8-bit components.
• LongUnion: Interop between u64, i64, and 32/16/8-bit components.
• LongerUnion: Interop between u128, i128, and 64/32/16/8-bit components.
• SizeUnion: Interop between usize, isize, and platform-dependent components.
• SharedValues: Memory-sharing for cross-type truncation or zero-filling.
• SharedArrays: Memory-sharing for cross-type array conversions.

2. Big Numbers

Essential for Asymmetric-Key Algorithms and high-precision calculations.

• BigUInt: Fixed-size big unsigned integers with user-defined bit-widths.
• BigUInt_More: Auxiliary methods for advanced calculations.
• BigUInt_Modular: Specialized modular arithmetic operations.
• BigUInt_Panic_Free: Safe, non-panicking arithmetic operations.
• BigUInt_Prime: Methods for primality testing and generation.

Predefined Big Unsigned Types

Commonly used bit-widths are available as aliases:

• U256, U512, U1024, U2048, U3072, U4096, U5120, U6144, U7168, U8192, and U16384.
• Synonyms like UU32 (256-bit) through UU2048 (16384-bit) are also provided.

Quick Start

• For SmallUInt, see here.
• For integer unions, see their respective #quick-start sections (e.g., ShortUnion#quick-start).
• For BigUInt, see here.

Modules

big_uint_arithmetic

big_uint.rs was too big because of documentation and plenty of examples So, in order to provide documentation without docs.rs’s failing generating documentation, dummy codes were made and documentation and examples were moved to big_uint_arithmetic.rs.

big_uint_arithmetic_uint

big_uint.rs was too big because of documentation and plenty of examples So, in order to provide documentation without docs.rs’s failing generating documentation, dummy codes were made and documentation and examples were moved to big_uint_arithmetic_uint.rs.

big_uint_basic_operation

big_uint.rs was too big because of documentation and plenty of examples So, in order to provide documentation without docs.rs’s failing generating documentation, dummy codes were made and documentation and examples were moved to big_uint_basic_operation.rs.

big_uint_binary_impl

big_uint.rs was too big because of documentation and plenty of examples So, in order to provide documentation without docs.rs’s failing generating documentation, dummy codes were made and documentation and examples were moved to big_uint_binary_impl.rs.

big_uint_display_impl

big_uint.rs was too big because of documentation and plenty of examples So, in order to provide documentation without docs.rs’s failing generating documentation, dummy codes were made and documentation and examples were moved to big_uint_display_impl.rs.

big_uint_lowerexp_impl

big_uint.rs was too big because of documentation and plenty of examples So, in order to provide documentation without docs.rs’s failing generating documentation, dummy codes were made and documentation and examples were moved to big_uint_lowerexp_impl.rs.

big_uint_lowerhex_impl

big_uint.rs was too big because of documentation and plenty of examples So, in order to provide documentation without docs.rs’s failing generating documentation, dummy codes were made and documentation and examples were moved to big_uint_lowerhex_impl.rs.

big_uint_modular

big_uint.rs was too big because of documentation and plenty of examples So, in order to provide documentation without docs.rs’s failing generating documentation, dummy codes were made and documentation and examples were moved to big_uint_modular.rs.

big_uint_more

big_uint.rs was too big because of documentation and plenty of examples So, in order to provide documentation without docs.rs’s failing generating documentation, dummy codes were made and documentation and examples were moved to big_uint_more.rs.

big_uint_octal_impl

big_uint.rs was too big because of documentation and plenty of examples So, in order to provide documentation without docs.rs’s failing generating documentation, dummy codes were made and documentation and examples were moved to pub mod big_uint_octal_impl.rs.

big_uint_other_calculation

big_uint.rs was too big because of documentation and plenty of examples So, in order to provide documentation without docs.rs’s failing generating documentation, dummy codes were made and documentation and examples were moved to big_uint_other_calculation.rs.

big_uint_other_calculation_uint

big_uint.rs was too big because of documentation and plenty of examples So, in order to provide documentation without docs.rs’s failing generating documentation, dummy codes were made and documentation and examples were moved to big_uint_other_calculation_uint.rs.

big_uint_panic_free

big_uint.rs was too big because of documentation and plenty of examples So, in order to provide documentation without docs.rs’s failing generating documentation, dummy codes were made and documentation and examples were moved to big_uint_panic_free.rs.

big_uint_pointer_impl

big_uint.rs was too big because of documentation and plenty of examples So, in order to provide documentation without docs.rs’s failing generating documentation, dummy codes were made and documentation and examples were moved to big_uint_pointer_impl.rs.

big_uint_prime

big_uint.rs was too big because of documentation and plenty of examples So, in order to provide documentation without docs.rs’s failing generating documentation, dummy codes were made and documentation and examples were moved to big_uint_prime.rs.

big_uint_shift_impl

big_uint.rs was too big because of documentation and plenty of examples So, in order to provide documentation without docs.rs’s failing generating documentation, dummy codes were made and documentation and examples were moved to big_uint_shift_impl.rs.

big_uint_traits_impl

big_uint.rs was too big because of documentation and plenty of examples So, in order to provide documentation without docs.rs’s failing generating documentation, dummy codes were made and documentation and examples were moved to big_uint_traits_impl.rs.

big_uint_traits_impl_uint

big_uint.rs was too big because of documentation and plenty of examples So, in order to provide documentation without docs.rs’s failing generating documentation, dummy codes were made and documentation and examples were moved to big_uint_traits_impl_uint.rs.

big_uint_upperexp_impl

big_uint.rs was too big because of documentation and plenty of examples So, in order to provide documentation without docs.rs’s failing generating documentation, dummy codes were made and documentation and examples were moved to big_uint_upperexp_impl.rs.

big_uint_upperhex_impl

big_uint.rs was too big because of documentation and plenty of examples So, in order to provide documentation without docs.rs’s failing generating documentation, dummy codes were made and documentation and examples were moved to big_uint_upperhex_impl.rs.

Structs

BigUInt

A Generic Fixed-Size Big Unsigned Integer

Enums

NumberErr

In operation of BigUInt, BigInt, and LargeInt, errors can occur. In this case, the enumerator NumberErr will indicate what kind of error occurred.

Traits

BigUInt_Modular

Introduction

BigUInt_More

Introduction

BigUInt_Panic_Free

Introduction

BigUInt_Prime

Introduction

SmallSInt

For generic type of primitive signed integral data types for the counter part of uint.

SmallUInt

Introduction

Type Aliases

U256_with_u8

256-bit unsigned integer implemented as BigUInt<u8, 32> (comprising 32 x u8).

U256_with_u16

256-bit unsigned integer implemented as BigUInt<u16, 16> (comprising 16 x u16).

U256_with_u32

256-bit unsigned integer implemented as BigUInt<u32, 8> (comprising 8 x u32).

U256_with_u64

256-bit unsigned integer implemented as BigUInt<u64, 4> (comprising 4 x u64).

U256_with_u128

256-bit unsigned integer implemented as BigUInt<u128, 2> (comprising 2 x u128).

U384_with_u8

384-bit unsigned integer implemented as BigUInt<u8, 48> (comprising 48 x u8).

U384_with_u16

384-bit unsigned integer implemented as BigUInt<u16, 24> (comprising 24 x u16).

U384_with_u32

384-bit unsigned integer implemented as BigUInt<u32, 12> (comprising 12 x u32).

U384_with_u64

384-bit unsigned integer implemented as BigUInt<u64, 6> (comprising 6 x u64).

U384_with_u128

384-bit unsigned integer implemented as BigUInt<u128, 3> (comprising 3 x u128).

U512_with_u8

512-bit unsigned integer implemented as BigUInt<u8, 64> (comprising 64 x u8).

U512_with_u16

512-bit unsigned integer implemented as BigUInt<u16, 32> (comprising 32 x u16).

U512_with_u32

512-bit unsigned integer implemented as BigUInt<u32, 16> (comprising 16 x u32).

U512_with_u64

512-bit unsigned integer implemented as BigUInt<u64, 8> (comprising 8 x u64).

U512_with_u128

512-bit unsigned integer implemented as BigUInt<u128, 4> (comprising 4 x u128).

U768_with_u8

768-bit unsigned integer implemented as BigUInt<u8, 96> (comprising 96 x u8).

U768_with_u16

768-bit unsigned integer implemented as BigUInt<u16, 48> (comprising 48 x u16).

U768_with_u32

768-bit unsigned integer implemented as BigUInt<u32, 24> (comprising 24 x u32).

U768_with_u64

768-bit unsigned integer implemented as BigUInt<u64, 12> (comprising 12 x u64).

U768_with_u128

768-bit unsigned integer implemented as BigUInt<u128, 6> (comprising 6 x u128).

U1024_with_u8

1024-bit unsigned integer implemented as BigUInt<u8, 128> (comprising 128 x u8).

U1024_with_u16

1024-bit unsigned integer implemented as BigUInt<u16, 64> (comprising 64 x u16).

U1024_with_u32

1024-bit unsigned integer implemented as BigUInt<u32, 32> (comprising 32 x u32).

U1024_with_u64

1024-bit unsigned integer implemented as BigUInt<u64, 16> (comprising 16 x u64).

U1024_with_u128

1024-bit unsigned integer implemented as BigUInt<u128, 8> (comprising 8 x u128).

U2048_with_u8

2048-bit unsigned integer implemented as BigUInt<u8, 256> (comprising 256 x u8).

U2048_with_u16

2048-bit unsigned integer implemented as BigUInt<u16, 128> (comprising 128 x u16).

U2048_with_u32

2048-bit unsigned integer implemented as BigUInt<u32, 64> (comprising 64 x u32).

U2048_with_u64

2048-bit unsigned integer implemented as BigUInt<u64, 32> (comprising 32 x u64).

U2048_with_u128

2048-bit unsigned integer implemented as BigUInt<u128, 16> (comprising 16 x u128).

U3072_with_u8

3072-bit unsigned integer implemented as BigUInt<u8, 384> (comprising 384 x u8).

U3072_with_u16

3072-bit unsigned integer implemented as BigUInt<u16, 192> (comprising 192 x u16).

U3072_with_u32

3072-bit unsigned integer implemented as BigUInt<u32, 96> (comprising 96 x u32).

U3072_with_u64

3072-bit unsigned integer implemented as BigUInt<u64, 48> (comprising 48 x u64).

U3072_with_u128

3072-bit unsigned integer implemented as BigUInt<u128, 24> (comprising 24 x u128).

U4096_with_u8

4096-bit unsigned integer implemented as BigUInt<u8, 512> (comprising 512 x u8).

U4096_with_u16

4096-bit unsigned integer implemented as BigUInt<u16, 256> (comprising 256 x u16).

U4096_with_u32

4096-bit unsigned integer implemented as BigUInt<u32, 128> (comprising 128 x u32).

U4096_with_u64

4096-bit unsigned integer implemented as BigUInt<u64, 64> (comprising 64 x u64).

U4096_with_u128

4096-bit unsigned integer implemented as BigUInt<u128, 32> (comprising 32 x u128).

U5120_with_u8

5120-bit unsigned integer implemented as BigUInt<u8, 640> (comprising 640 x u8).

U5120_with_u16

5120-bit unsigned integer implemented as BigUInt<u16, 320> (comprising 320 x u16).

U5120_with_u32

5120-bit unsigned integer implemented as BigUInt<u32, 160> (comprising 160 x u32).

U5120_with_u64

5120-bit unsigned integer implemented as BigUInt<u64, 80> (comprising 80 x u64).

U5120_with_u128

5120-bit unsigned integer implemented as BigUInt<u128, 40> (comprising 40 x u128).

U6144_with_u8

6144-bit unsigned integer implemented as BigUInt<u8, 768> (comprising 768 x u8).

U6144_with_u16

6144-bit unsigned integer implemented as BigUInt<u16, 384> (comprising 384 x u16).

U6144_with_u32

6144-bit unsigned integer implemented as BigUInt<u32, 192> (comprising 192 x u32).

U6144_with_u64

6144-bit unsigned integer implemented as BigUInt<u64, 96> (comprising 96 x u64).

U6144_with_u128

6144-bit unsigned integer implemented as BigUInt<u128, 48> (comprising 48 x u128).

U7168_with_u8

7168-bit unsigned integer implemented as BigUInt<u8, 896> (comprising 896 x u8).

U7168_with_u16

7168-bit unsigned integer implemented as BigUInt<u16, 448> (comprising 448 x u16).

U7168_with_u32

7168-bit unsigned integer implemented as BigUInt<u32, 224> (comprising 224 x u32).

U7168_with_u64

7168-bit unsigned integer implemented as BigUInt<u64, 112> (comprising 112 x u64).

U7168_with_u128

7168-bit unsigned integer implemented as BigUInt<u128, 56> (comprising 56 x u128).

U8192_with_u8

8192-bit unsigned integer implemented as BigUInt<u8, 1024> (comprising 1024 x u8).

U8192_with_u16

8192-bit unsigned integer implemented as BigUInt<u16, 512> (comprising 512 x u16).

U8192_with_u32

8192-bit unsigned integer implemented as BigUInt<u32, 256> (comprising 256 x u32).

U8192_with_u64

8192-bit unsigned integer implemented as BigUInt<u64, 128> (comprising 128 x u64).

U8192_with_u128

8192-bit unsigned integer implemented as BigUInt<u128, 64> (comprising 64 x u128).

U16384_with_u8

16384-bit unsigned integer implemented as BigUInt<u8, 2048> (comprising 2048 x u8).

U16384_with_u16

16384-bit unsigned integer implemented as BigUInt<u16, 1024> (comprising 1024 x u16).

U16384_with_u32

16384-bit unsigned integer implemented as BigUInt<u32, 512> (comprising 512 x u32).

U16384_with_u64

16384-bit unsigned integer implemented as BigUInt<u64, 256> (comprising 256 x u64).

U16384_with_u128

16384-bit unsigned integer implemented as BigUInt<u128, 128> (comprising 128 x u128).

Unions

IntUnion

A 32-bit integer union that enables bit-level slicing and seamless conversion between various primitive types, including u32, i32, u16, i16, u8, and i8.

LongUnion

A 64-bit integer union that enables bit-level slicing and seamless conversion between various primitive types, including u64, i64, u32, i32, u16, i16, u8, and i8.

LongerUnion

A 128-bit integer union that enables bit-level slicing and seamless conversion between various primitive types, including u128, i128, u64, i64, u32, i32, u16, i16, u8, and i8.

SharedArrays

union for transforming from an array of one type into another array of anther type

SharedValues

union for transforming from one type into anther type

ShortUnion

A 16-bit integer union that enables bit-level slicing and seamless conversion between various primitive types, including u16, i16, u8, and i8.

SizeUnion

A pointer-sized integer union that enables bit-level slicing and seamless conversion between various primitive types, based on the system’s architecture.