Crate safe_math

Source
Expand description

Crates.io Documentation License

A procedural macro-based library that transforms standard arithmetic operations into their checked equivalents at compile time, preventing overflow, underflow, and division by zero errors.

§Overview

safe-math provides:

  • Compile-time transformation of arithmetic operations into checked variants without runtime overhead
  • Comprehensive error handling via Result types
  • Support for custom types through derive macros

§Core Functionality

§Basic Operations

The #[safe_math] attribute transforms arithmetic operations into their checked equivalents:

use safe_math::safe_math;

#[safe_math]
fn add(a: u8, b: u8) -> Result<u8, safe_math::SafeMathError> {
    Ok(a + b)  // Automatically uses checked addition
}

assert_eq!(add(10, 20), Ok(30));
assert_eq!(add(255, 1), Err(safe_math::SafeMathError::Overflow));

§Supported Operations

All basic arithmetic operations are supported:

  • Addition (+, +=)
  • Subtraction (-, -=)
  • Multiplication (*, *=)
  • Division (/, /=)
  • Remainder (%, %=)

§Error Handling

Operations return SafeMathError for exceptional cases:

pub enum SafeMathError {
    Overflow,           // Result exceeds type bounds
    DivisionByZero,    // Division or remainder by zero
    InfiniteOrNaN,    // Result is infinite or NaN (floating-point types)
    NotImplemented,    // Missing trait implementation (derive feature)
}

§Type Support

Built-in support for:

  • Unsigned integers: u8 through u128, usize
  • Signed integers: i8 through i128, isize
  • Floating point: f32, f64 (with infinity/NaN handling)

§Advanced Usage

§Custom Types

Enable the derive feature to implement safe arithmetic for custom types:

ⓘ
use safe_math::SafeMathOps;

#[derive(SafeMathOps)]
#[SafeMathOps(add, sub, mul, div, rem)]
struct MyNumber(u32);

#[safe_math]
fn calculate(a: MyNumber, b: MyNumber) -> Result<MyNumber, safe_math::SafeMathError> {
    Ok(a + b)
}

Note: For the derive to work, your type must implement both the standard arithmetic traits (like Add, Sub, Mul, Div, Rem) and their checked counterparts (like CheckedAdd, CheckedSub, CheckedMul, CheckedDiv, CheckedRem) from the num-traits crate.

This requirement exists because without knowing what a type represents, it’s impossible to determine what operations are safe to perform or what constitutes a “checked” operation.

§Block-Level Safety

Use safe_math_block! to apply checked operations to a specific block of code:

use safe_math::safe_math_block;

fn process_numbers(a: u32, b: u32, c: u32) -> Result<u32, safe_math::SafeMathError> {
    // Only this block uses checked arithmetic
    let result = safe_math_block!({
        let product = a * b;
        let sum = product + c;
        sum / b
    });
    Ok(result)
}

This is useful when you want to:

  • Apply safe arithmetic to specific expression
  • Mix checked and unchecked operations in the same function

§Roadmap

Planned upcoming features:

  • Option-returning functions
    Support for functions that return Option<T> instead of Result<T, SafeMathError>.

  • Crate-level macro support
    Ability to apply #[safe_math] to the entire crate with a single attribute:

ⓘ
// main.rs or lib.rs
#![safe_math]

fn demo(a: u32, b: u32) -> Result<u32, safe_math::SafeMathError> {
    Ok(a * b + 1)
}

§License

Licensed under either:

at your option.

§Contributing

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you shall be dual licensed as above, without any additional terms or conditions.

Macros§

safe_math_block

Enums§

SafeMathError
Error types returned by safe arithmetic operations.

Traits§

SafeAdd
Safe addition operation with overflow checking.
SafeDiv
Safe division operation with division-by-zero checking.
SafeMathOps
Unified trait providing all safe arithmetic operations.
SafeMul
Safe multiplication operation with overflow checking.
SafeRem
Safe remainder operation with division-by-zero checking.
SafeSub
Safe subtraction operation with underflow checking.

Functions§

safe_add
Performs safe addition with overflow checking.
safe_div
Performs safe division with division-by-zero checking.
safe_mul
Performs safe multiplication with overflow checking.
safe_rem
Performs safe remainder with division-by-zero checking.
safe_sub
Performs safe subtraction with underflow checking.

Attribute Macros§

safe_math