Astra-Num

Astra-Num is a Rust library providing an easy-to-use wrapper around [num-bigint], [num-integer], and [num-traits]. It offers additional utilities for handling incredibly large (astronomical) values, cryptographic operations (optional), and more. This library is suitable for projects that require arbitrary-precision arithmetic or advanced integer manipulation.

Table of Contents

• Features
• Installation
• Usage
  • Basic Example
  • Arithmetic Operations
  • Conversion Examples
  • Crypto Utilities (Feature: crypto_utils)
• Documentation
• Testing
• License

Features

1. Arbitrary-precision arithmetic based on num_bigint::BigInt.
2. Trait implementations for num_traits—allows you to use familiar methods like Zero, One, Num, and Signed.
3. Additional arithmetic methods:
   • mod_pow for efficient modular exponentiation.
   • sqrt, sqrt_precise for integer square roots.
   • Bitwise operations like AND, OR, XOR, NOT.
4. Optional cryptographic utilities (enabled via the crypto_utils feature) including:
   • Miller-Rabin primality check for probable prime testing.
   • Random prime generation of a given bit size.
5. Serde support for easy serialization/deserialization of BigNum as decimal strings.

Installation

Add the following to your Cargo.toml:

[dependencies]
astra-num = "0.1.0"

If you want the cryptographic utilities (prime checking, prime generation), enable the crypto_utils feature:

[dependencies]
astra-num = { version = "0.1.0", features = ["crypto_utils"] }

Then import in your Rust code:

use astra_num::BigNum;

Usage

Basic Example

use astra_num::BigNum;

fn main() {
    let a = BigNum::from(123u32);
    let b = BigNum::from(456u32);
    let result = a + b;
    println!("Sum = {}", result); // 579
}

Arithmetic Operations

BigNum supports common operations through both method calls and Rust’s operator overloads:

use astra_num::BigNum;

// addition: operator
let a = BigNum::from(100u32);
let b = BigNum::from(25u32);
let sum = a.clone() + b.clone(); // 125

// subtraction: method
let diff = a.sub(&b);           // 75

// multiplication: operator
let product = a * b;            // 2500

// division & remainder
let quotient = BigNum::from(24u32) / BigNum::from(4u32); // 6
let remainder = BigNum::from(29u32) % BigNum::from(4u32);// 1

println!("Sum = {}", sum);
println!("Diff = {}", diff);
println!("Product = {}", product);
println!("Quotient = {}", quotient);
println!("Remainder = {}", remainder);

Conversion Examples

use astra_num::BigNum;
use num_bigint::Sign;

// from decimal string
let bn_decimal = BigNum::from_str("999999999").expect("Invalid format");
println!("Decimal parse: {}", bn_decimal); // 999999999

// from/to little-endian bytes
let data = &[0x01, 0x02, 0x03]; // example
let bn_le = BigNum::from_bytes_le(data);
let (sign, bytes) = bn_le.to_bytes_le();
assert_eq!(sign, Sign::Plus);
assert_eq!(bytes, data);

// from f64
let approximate = BigNum::from_f64(12345.0).unwrap();
println!("From f64 = {}", approximate); // 12345

// to f64 (returns an Option<f64>)
let maybe_float = approximate.to_f64();
if let Some(f) = maybe_float {
    println!("As float = {}", f); // 12345.0
} else {
    println!("Value too large for f64!");
}

Crypto Utilities (Feature: crypto_utils)

// In Cargo.toml:
// [dependencies]
// astra-num = { version = "0.1.0", features = ["crypto_utils"] }

use astra_num::BigNum;

fn main() {
    // 1. Probable prime check using Miller-Rabin
    let num = BigNum::from(7919u32);
    let is_prime = num.probable_prime(20); 
    println!("Is 7919 prime? {}", is_prime); // Likely true

    // 2. Generate a random prime of bit length 128
    let prime_128 = BigNum::generate_prime(128);
    println!("128-bit prime = {}", prime_128);
}

Security Notice: While these utilities are educational and convenient, cryptography requires careful review and best practices (e.g., secure random number generation, safe prime generation parameters, etc.). For production-grade cryptographic applications, consider established, audited libraries.

Documentation

Comprehensive documentation for astra-num is hosted on docs.rs.

To build it locally, run:

cargo doc --open

This command will generate and open documentation in your web browser.

Testing

I included a suite of unit tests in the lib.rs file. You can run them with:

cargo test

This will:

• Build the library in test mode, and
• Execute all the tests, reporting any failures or errors.

License

This project is licensed under the MIT license. You are free to use, modify, and distribute this software, subject to the terms of the license.