use-arithmetic 0.0.6

Utility-first arithmetic primitives for RustUse
Documentation

use-arithmetic

Install

[dependencies]
use-arithmetic = "0.0.2"

Foundation

use-arithmetic provides a deliberately small operation-level arithmetic surface for primitive integers. The current slice focuses on exact common-divisor helpers, divisibility and parity checks, mathematical floor-division behavior for signed integers, and lightweight wrappers around primitive checked, saturating, and wrapping arithmetic.

This crate is about concrete arithmetic operations. It intentionally avoids integer classification, number taxonomy, rational types, real-number abstractions, or algebraic law checking.

Area Primary items Best fit
Common divisors gcd, checked_lcm, lcm Exact multiple and normalization workflows over primitive integers
Divisibility and parity checked_is_divisible_by, is_divisible_by, is_even, is_odd Small runtime checks without ad hoc % handling at every call site
Floor division checked_div_floor, checked_div_ceil, checked_mod_floor, plain variants Signed integer code that needs mathematical floor semantics
Overflow-mode operations checked_add, checked_sub, checked_mul, saturating helpers, wrapping helpers Call sites that want consistent overflow behavior across primitive integers
Neighboring crate Best fit there
use-integer Sign classification, signed integer helpers, and integer-specific concerns
use-number Broader number classification and shared numeric constants
use-rational Exact fraction types and rational arithmetic
use-real Finite-value, interval, and approximate real-number helpers
use-algebra Finite algebra law checks over caller-supplied operations

When to use directly

Choose use-arithmetic directly when operation-level helpers are the only surface you need and you want to keep that concern narrower than the full facade crate.

Scenario Use use-arithmetic directly? Why
You need exact gcd and lcm helpers over primitive unsigned integers Yes The crate stays small and focused on direct arithmetic operations
You need signed floor-division helpers with mathematical semantics Yes The division helpers make the quotient and modulo policy explicit
You want reusable checked, saturating, or wrapping wrappers Yes The free functions keep primitive overflow modes visible at the call site
You need signed classification or rational/real abstractions Usually no Those concerns already live in adjacent focused crates

Scope

  • The current surface is intentionally small and concrete.
  • The first slice focuses on primitive arithmetic operations rather than wrapper types or trait-heavy abstractions.
  • use-integer remains the home for signed classification and integer-specific descriptive helpers.
  • Slice-based statistical means, rational arithmetic, and algebraic structures belong in adjacent focused crates.

Examples

Compute gcd, lcm, divisibility, and parity

use use_arithmetic::{gcd, is_divisible_by, is_even, is_odd, lcm};

assert_eq!(gcd(54, 24), 6);
assert_eq!(lcm(6, 15), 30);
assert!(is_divisible_by(84, 7));
assert!(!is_divisible_by(84, 0));
assert!(is_even(12));
assert!(is_odd(7));

Use floor-division semantics for signed integers

use use_arithmetic::{div_ceil, div_floor, mod_floor};

assert_eq!(div_floor(-7, 3), -3);
assert_eq!(div_ceil(-7, 3), -2);
assert_eq!(mod_floor(-7, 3), 2);

Choose an overflow mode explicitly

use use_arithmetic::{checked_add, saturating_add, wrapping_mul};

assert_eq!(checked_add(u8::MAX, 1), None);
assert_eq!(saturating_add(u8::MAX, 1), u8::MAX);
assert_eq!(wrapping_mul(200_u8, 2), 144);

Status

use-arithmetic is a concrete pre-1.0 crate in the RustUse math workspace. The API remains intentionally small while adjacent numeric, integer, and algebra crates continue to grow around it.