Numeric Types

Specialized numeric types beyond the standard integer and float primitives.

Decimal

128-bit decimal type for exact arithmetic. No floating-point rounding errors. Essential for financial calculations.

let price = Decimal::new(19, 99, false);    // 19.99
let tax = Decimal::from_str("0.0825");      // 8.25%
let total = price.mul(&tax).add(&price);    // exact: 21.6392...

// No floating-point surprise
let a = Decimal::from_str("0.1");
let b = Decimal::from_str("0.2");
let c = a.add(&b);
// c == 0.3 exactly (unlike f64 where 0.1 + 0.2 != 0.3)

Methods

let d = Decimal::from_str("123.456");

// Arithmetic
d.add(&other);       d.sub(&other);
d.mul(&other);       d.div(&other);
d.rem(&other);       // remainder

// Rounding
d.round(2);          // 123.46 — round to 2 decimal places
d.floor();           // 123.0
d.ceil();            // 124.0
d.trunc();           // 123.0 — truncate toward zero

// Properties
d.abs();             // absolute value
d.neg();             // negate
d.scale();           // number of decimal places
d.mantissa();        // integer mantissa
d.is_zero();         // false
d.is_negative();     // false

// Conversion
d.to_f64();          // 123.456 (lossy)
d.to_string();       // "123.456"

Energy Cost

Decimal is ~14x more expensive than f64 arithmetic but guarantees exact results. Use it where correctness matters more than speed (finance, accounting, currency).

Complex<T>

Complex number with real and imaginary parts. Generic over the component type (typically f32 or f64).

let z = Complex::new(3.0, 4.0);     // 3 + 4i
let w = Complex::new(1.0, -2.0);    // 1 - 2i

// Arithmetic
let sum = z.add(&w);     // 4 + 2i
let prod = z.mul(&w);    // 11 + 2i
let quot = z.div(&w);    // -1 + 2i

// Properties
z.real();       // 3.0
z.imag();       // 4.0
z.abs();        // 5.0 (magnitude: sqrt(3^2 + 4^2))
z.arg();        // 0.927... (phase angle in radians)
z.conj();       // 3 - 4i (complex conjugate)
z.norm();       // 25.0 (squared magnitude)

Advanced Operations

let z = Complex::new(1.0, 1.0);

z.exp();             // e^z
z.log();             // natural logarithm
z.sqrt();            // principal square root
z.pow(&w);           // z^w

// Polar form
let polar = Complex::from_polar(5.0, 0.927);  // magnitude, angle

Energy Cost

Intern

Interned string — stored once in a global table, compared by pointer equality. Ideal for identifiers, keywords, and symbols that appear repeatedly.

let a = Intern::new("hello");
let b = Intern::new("hello");

// Pointer equality — O(1) comparison instead of O(n) string compare
a.eq(&b);         // true (same pointer)

// String access
a.as_str();       // "hello"
a.len();          // 5
a.is_empty();     // false
a.hash();         // precomputed hash value

Use Case: Compiler Symbol Tables

pub struct Symbol {
    pub name: Intern,
}

// Creating millions of Symbol values with the same name
// only stores the string once in memory
let sym1 = Symbol { name: Intern::new("x") };
let sym2 = Symbol { name: Intern::new("x") };

// Comparison is pointer equality — O(1), not O(n)
sym1.name.eq(&sym2.name);  // true, instant

Energy Cost

The 10.0 pJ cost of Intern::new is amortized over all subsequent O(1) comparisons. For strings compared frequently (like identifiers in a compiler), interning saves both energy and time.