This crate provides 3 traits, RotaryAdd, CycleAdd and SeriesAdd, with simple methods to apply cyclical or modular addition and subtraction with three unsigned integer types, u8, u16 and u32. Unlike the default + and - operators, additions and subtractions never overflow.

This trait has addition and subtraction methods that act on the whole range of an unsigned integer, e.g. from 0 to 255 for u8 or from 0 to 65535 for u16. This example with an 8-bit unsigned integer illustrates the concept with rotary_add and rotary_sub:

Addition:

let first_number: u8 = 255;
let second_number: u8 = 6;

let result = first_number.rotary_add(&second_number);
// yields 5. first_number + second_number would panic as the value would overflow

Subtraction

let first_number: u8 = 3;
let second_number: u8 = 6;
let result = first_number.rotary_sub(&second_number);
// yields 253. first_number - second_number would panic as the value would overflow

This trait provides addition and subtraction methods that let you define a custom cyclic base.

These examples show the concept:

let first_number: u8 = 22;
let second_number: u8 = 6;

let result = first_number.cycle_add(&second_number, 24);
// yields 4. We have to use u8 as a primitive data type with a higher maximum value

let first_number: u8 = 37;
let second_number: u8 = 78;
let result = first_number.cycle_sub(&second_number, 100);
// yields 59. first_number - second_number would panic as the value would overflow

Many common series start from one. The months of a year, days of a month and weekdays are commonly expressed with the numerals 1 to the maximum. Alas this does not work with modular arithmetic where additions or subtractions overflow. If 1 means Monday and 7 means Sunday, we'd expect 2 (Tue) - 3 to equal 7 (Sun) and 6 (Sat) + 1 to equal 7 (Sun). Instead we need to subtract one from the input number, that may be no lower than 1, mod it by the maximum number and then add 1 to the result. The series_add(), series_sub() and series_mod() methods avoid the need for these conversions when dealing with 1-based series.

let sample_month_1: u8 = 11;
let limit = 12; // months of the year
let result = sample_month_1.series_add(1, limit);
// yields 12. 
let sample_month_2: u8 = 3;
let result = sample_month_2.series_sub(3, limit);
// yields 12

let sample_month_value: u8 = 24; // 24th month
let result = sample_month_value.series_mod(limit);
// yields 12, but would yield 0 with 0-indexed modulus

Unlike the related Ring360 crate, this library only extends core unsigned integer types for use with cryptography, metrology and as a building block for other crates, e.g. converting characters first to u32 values and then shifting their values in one direction in the encoding stage and reversing the process in the decoding stage.

This is an alpha release, but is otherwise feature-complete.

• Added series_add(), series_sub(), series_mod() methods.