num

The `num` crate in Rust is a comprehensive collection of numeric traits and types designed to extend Rust's standard library with advanced numerical capabilities. It's particularly vital for generic programming, allowing developers to write functions that operate uniformly across various numeric types (integers, floats, complex numbers, rational numbers, arbitrary-precision integers).

Key components and sub-crates within the `num` ecosystem include:

1. `num-traits`: This is the bedrock of the `num` crate. It defines fundamental numeric traits such as `Num`, `Zero`, `One`, `Bounded`, `Signed`, `Float`, `Euclid`, `CheckedAdd`, `CheckedMul`, and more. These traits enable writing highly generic code that can work with *any* type implementing them, rather than being confined to specific primitive types like `i32` or `f64`. For instance, a generic function constrained by `T: num_traits::Zero + num_traits::One + std::ops::Add` can handle any type that has a concept of zero and one, and supports addition.

2. `num-derive`: This sub-crate provides `#[derive()]` macros for certain `num-traits` traits, simplifying their implementation for custom data structures or enums. A common use case is deriving `FromPrimitive` for easy conversion from primitive integer types.

3. `num-integer`: This component offers specialized integer functions not found in Rust's standard library. Examples include `gcd` (greatest common divisor), `lcm` (least common multiple), `div_floor`, and `mod_floor`. It also defines the `Integer` trait.

4. `num-bigint`: Crucial for applications requiring numbers larger than Rust's built-in `i128` or `u128`, `num-bigint` provides arbitrary-precision integers (`BigInt` for signed and `BigUint` for unsigned). This allows calculations with numbers of virtually unlimited size.

5. `num-complex`: Implements complex numbers, represented by the `Complex<T>` type, enabling complex arithmetic.

6. `num-rational`: Provides rational numbers (`Ratio<T>`), allowing precise calculations with fractions.

Why use `num`?

* Genericity and Reusability: Write highly flexible functions that can work with any number type that meets the specified trait bounds.
* Extended Mathematical Functionality: Access a rich set of mathematical operations (like GCD, LCM, floor division) and advanced number types (big integers, complex, rational) beyond the standard library.
* Robustness: Traits like `CheckedAdd` assist in gracefully handling potential overflow scenarios, leading to more reliable code.
* Performance vs. Precision: While arbitrary-precision types introduce some overhead compared to fixed-size primitives, `num-bigint` offers an optimized implementation for scenarios where precision is paramount.

To integrate `num` into a Rust project, you typically add it as a dependency in your `Cargo.toml` file, specifying the desired features (sub-crates). For example, `num = { version = "0.4", features = ["std", "num-traits", "num-integer", "num-bigint"] }` would enable a broad range of its functionalities.

use num_traits::{Zero, One};
use num_integer::Integer;
use num_bigint::{BigInt, Sign};
use std::ops::Add;
use std::clone::Clone;

// A generic function that sums numbers up to a given limit.
// It demonstrates the use of `num-traits` for generic programming, working with any type T
// that implements Zero, One, Add, PartialOrd, and Clone.
fn sum_up_to<T>(limit: T) -> T
where
    T: Zero + One + Add<Output = T> + PartialOrd + Clone,
{
    let mut sum = T::zero();
    let mut current = T::one();

    while current <= limit {
        // We clone `current` because `Add` might consume `self`, and we need `current` for the next iteration.
        // `current.clone()` ensures types like BigInt are handled correctly.
        sum = sum + current.clone(); 
        current = current + T::one();
    }
    sum
}

fn main() {
    println!("---\n--- num-traits & generic programming ---\n");
    // Using sum_up_to with standard i32
    let s_i32 = sum_up_to(5i32);
    println!("Sum up to 5 (i32): {}", s_i32); // Expected: 1+2+3+4+5 = 15

    // Using sum_up_to with i128
    let s_i128 = sum_up_to(10i128);
    println!("Sum up to 10 (i128): {}", s_i128); // Expected: 55

    println!("\n--- num-integer for specific integer operations ---\n");
    let a = 48;
    let b = 18;
    // `gcd` (greatest common divisor) is a method from the `Integer` trait.
    let common_divisor = a.gcd(&b);
    println!("GCD of {} and {}: {}", a, b, common_divisor); // Expected: 6

    let c = 15;
    let d = 20;
    // `lcm` (least common multiple) is also from the `Integer` trait.
    let common_multiple = c.lcm(&d);
    println!("LCM of {} and {}: {}", c, d, common_multiple); // Expected: 60

    println!("\n--- num-bigint for arbitrary precision integers ---\n");
    // Parse a BigInt from a string of bytes (arbitrarily large number)
    let big_num1 = BigInt::parse_bytes(b"1234567890123456789012345678901234567890", 10).unwrap();
    // Convert a large primitive integer to BigInt
    let big_num2 = BigInt::from(98765432109876543210i128);
    // Construct a BigInt manually (less common for direct numeric values)
    let big_num3 = BigInt::new(Sign::Plus, vec![1, 2, 3]); // Internal representation, not 123.

    println!("BigInt 1: {}", big_num1);
    println!("BigInt 2: {}", big_num2);
    println!("BigInt 3 (from internal representation): {}", big_num3);

    // BigInts support standard arithmetic operations
    let sum_big = &big_num1 + &big_num2; // Operators are overloaded for BigInts (and their references)
    println!("Sum of BigInt1 and BigInt2: {}", sum_big);

    let product_big = &big_num1 * &BigInt::from(2);
    println!("Product of BigInt1 and 2: {}", product_big);

    // Using the generic sum_up_to function with BigInt
    let big_limit = BigInt::from(20);
    let big_sum = sum_up_to(big_limit.clone()); // We clone `big_limit` because `sum_up_to` consumes the value.
    println!("Sum up to 20 (BigInt): {}", big_sum);
}