Expand description
§use-arithmetic
Small arithmetic primitives for `RustUse`.
Exact gcd and lcm helpers, divisibility and parity checks, floor-division helpers, and lightweight checked, saturating, and wrapping arithmetic wrappers over primitive integers.
§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.
Common-divisor helpersgcd, checked_lcm, and lcm keep exact divisor and multiple calculations explicit.
|
Division semanticsdiv_floor, div_ceil, and mod_floor follow mathematical floor semantics instead of Rust's truncating signed division.
|
Overflow-mode wrappers The checked, saturating, and wrapping helpers make primitive integer overflow behavior explicit without forcing callers to reach for methods directly. |
| 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-integerremains 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.
Arithmetic primitives for RustUse.
Re-exports§
pub use checked::CheckedArithmetic;pub use checked::checked_add;pub use checked::checked_mul;pub use checked::checked_sub;pub use divisibility::checked_is_divisible_by;pub use divisibility::is_divisible_by;pub use division::checked_div_ceil;pub use division::checked_div_floor;pub use division::checked_mod_floor;pub use division::div_ceil;pub use division::div_floor;pub use division::mod_floor;pub use gcd::gcd;pub use lcm::checked_lcm;pub use lcm::lcm;pub use parity::is_even;pub use parity::is_odd;pub use saturating::SaturatingArithmetic;pub use saturating::saturating_add;pub use saturating::saturating_mul;pub use saturating::saturating_sub;pub use wrapping::WrappingArithmetic;pub use wrapping::wrapping_add;pub use wrapping::wrapping_mul;pub use wrapping::wrapping_sub;