Crate uninum

Crate uninum 

Source
Expand description

A unified numeric type system for Rust with automatic overflow handling and ergonomic primitive operations.

This crate provides the Number enum which unifies all numeric types and provides consistent behavior across operations with automatic type promotion and overflow handling.

§Key Features

  • Ergonomic operations: number + 5, 5 + number, &number + 5 all work naturally
  • Optimal string parsing: Integers use the smallest fitting type, floats use the highest precision
  • No undefined behavior: All operations are mathematically well-defined
  • Automatic type promotion: Overflow protection through intelligent type promotion
  • Cross-type operations: Mix different numeric types seamlessly
  • IEEE 754 semantics: Special values (NaN, Infinity) are preserved correctly

§Float Construction

Use the num! macro or direct construction with Float64 wrapper:

use uninum::{num, Float64, Number};

// Using num! macro (recommended):
let a = num!(2.718);

// Direct construction:
let b = Number::from(2.718_f64);

§Quick Start

use uninum::{num, Number};

let a = Number::from(10u64);
let b = num!(3.14); // Using num! macro

// Ergonomic operations with primitives
let result1 = &a + 5; // Number + i32
let result2 = 2.5 * &a; // f64 * Number
let result3 = &a + &b; // Number + Number

// Comparison operations
assert!(&a > 5); // Number > i32
assert!(15 > &a); // i32 > Number
assert!(&a == 10); // Number == i32

// String parsing with optimal type selection
let small = Number::try_from("42").unwrap(); // -> U64(42)
let large = Number::try_from("70_000").unwrap(); // -> U64(70_000)
let float = Number::try_from("3.14").unwrap(); // -> Decimal(3.14) or F64(3.14)

§Division by Zero Behavior

Division operations follow IEEE 754 inspired semantics:

  • finite / 0 returns +∞ or -∞ (signed infinity)
  • 0 / 0 returns NaN (Not a Number)
  • Integer division by zero promotes to F64 and follows IEEE 754 rules

Division operations never panic and always return a valid Number.

§Special Float Values with Decimal Feature

When the decimal feature is enabled, operations involving NaN or Infinity always use F64 to preserve IEEE 754 semantics. Additionally, float division with integer values promotes to Decimal for better precision:

  • NaN + Decimal returns F64(NaN), not Decimal(0)
  • Infinity * Decimal returns F64(Infinity), not overflow
  • num!(1.0) / num!(2.0) returns Decimal(0.5) for exact representation
  • Special values propagate correctly through all operations

Re-exports§

pub use float::Float64;
pub use math::RoundingStrategy;

Modules§

float
Custom float wrapper that implements Ord, Eq, and Hash traits
math
Mathematical operations and utilities for the Number type.
traits
Trait implementations for the Number type.

Macros§

num
A smart macro for creating Number instances with optimal type selection.

Enums§

Number
A unified numeric type that provides automatic overflow handling, type promotion, ergonomic primitive operations, and consistent cross-type operations.
ParseNumberError
Public API exports Error type for string parsing operations
TryFromNumberError
Public API exports Error type for TryFrom<Number> conversions