3 unstable releases
new 0.2.0 | Apr 27, 2025 |
---|---|
0.1.5 | Jul 13, 2024 |
0.1.4 | May 6, 2024 |
0.1.3 |
|
#515 in Math
35 downloads per month
9KB
65 lines
Cyclical Arithmetic with Unsigned Integers and Arbitrary Ranges
This library crate provides an extension trait, CycleAdd
, for performing cyclical (modular) addition and subtraction with unsigned integer types (u8
, u16
, and u32
). Unlike the default +
and -
operators, these operations never overflow.
Features
- Cyclical addition and subtraction: Perform modular arithmetic without overflow.
- 1-based series support: Simplifies operations on series starting from 1 (e.g., months, weekdays).
- Lightweight and focused: Extends core unsigned integer types for cryptography, metrology, and other use cases.
Examples
Cyclical Addition
let first_number: u8 = 22;
let second_number: u8 = 6;
let result = first_number.cycle_add(&second_number, 24);
// Result: 4 (22 + 6 wraps around at 24)
Cyclical Subtraction
let first_number: u8 = 37;
let second_number: u8 = 78;
let result = first_number.cycle_sub(&second_number, 100);
// Result: 59 (37 - 78 wraps around at 100)
1-Based Series Operations
Many common series (e.g., months, weekdays) start from 1. Modular arithmetic typically assumes 0-based indexing, which can lead to unexpected results. The series_add
, series_sub
, and series_mod
methods handle these conversions for you.
let sample_month_1: u8 = 11;
let limit = 12; // Months of the year
let result = sample_month_1.series_add(1, limit);
// Result: 12 (November + 1 = December)
let sample_month_2: u8 = 3;
let result = sample_month_2.series_sub(3, limit);
// Result: 12 (March - 3 = December)
let sample_month_value: u8 = 24; // 24th month
let result = sample_month_value.series_mod(limit);
// Result: 12 (24 wraps around to December)
Comparison with Related Crates
Unlike the Ring360 crate, RotaryAdd
focuses exclusively on extending core unsigned integer types. It is designed for use cases such as:
- Cryptography
- Metrology
- Building blocks for other crates (e.g., encoding/decoding operations)
Changelog
Version 0.2.0
- Removed
T.rotary_add(&T)
andT.rotary_sub(&T)
as they were functionally equivalent toT.wrapping_add(T)
andT.wrapping_sub(T)
in the Rust core library (but with the first parameter passed by reference). - All remaining extension methods now take the first parameter by value, consistent with
wrapping_add
andwrapping_sub
.
Version 0.1.2
- Added
series_add
,series_sub
, andseries_mod
methods for 1-based series operations.
For more details, visit the documentation or the GitHub repository.