Crate ranch 

Ranged integer types and math

Do you ever need to restrict a u8 from 0 to 100 or restrict any other integer type to any other range? Then this crate is for you! The ranges are encoded in the type system, so you only need to validate the range once (and it can even be at compile time!). This crate is sort of like a combination of similar crates deranged and ux.

This crate heavily leverages the type system to allow for powerful ranged integer mathematics, covering arbitrary i{N} / u{N} types, unit integers, non-zero divisions, ASCII, and const operations. Enable the serde feature for range-validated deserialization / serialization (implements Serialize and Deserialize for Ranged* types).

Types of operations

Like the std library, ranch provide strict, checked, and saturating integer operations. In addition, ranch also provides constant and ranged operations, which modify the output ranges.

Strict

Strict operations panic when out of range, or a division by nonzero occurs. This is exposed in ranch with +, -, /, *, %. Using the other provided operation methods will never result in UB (even if unsafe is used to set the inner value to something out of range), but may result in logic bugs and panics on invalid bit patterns.

assert_eq!(
    RangedI32::<2, 7>::new::<2>() + 5,
    RangedI32::<2, 7>::new::<7>(),
);

Panics:

let _ = RangedI32::<2, 7>::new::<2>() + 6;

Checked

Checked operations are methods starting with checked_; They return an Option (unsigned) or Result (signed). Divisions by zero-able types additionally wrap the result in a Quotient.

assert_eq!(
    RangedI32::<2, 7>::new::<2>().checked_add(5).unwrap(),
    RangedI32::<2, 7>::new::<7>(),
);
RangedI32::<2, 7>::new::<2>().checked_add(6).unwrap_err();

Saturating

Saturating operations are similar to checked, except that the Option and Result are stripped and Self::MIN or Self::MAX is returned on overflow.

assert_eq!(
    RangedI32::<2, 7>::new::<2>().saturating_add(5),
    RangedI32::<2, 7>::new::<7>(),
);
assert_eq!(
    RangedI32::<2, 7>::new::<2>().saturating_add(6),
    RangedI32::<2, 7>::new::<7>(),
);

Constant

Constant operations add a constant value and modify the output’s range accordingly. Due to limitations in Rust, you have to specify the output range, but ranch will check your work and tell you if you’re wrong.

assert_eq!(
    RangedI32::<2, 7>::new::<2>().add::<5, 7, 12>(),
    RangedI32::<7, 12>::new::<7>(),
);
assert_eq!(
    RangedI32::<2, 7>::new::<2>().add::<6, 8, 13>(),
    RangedI32::<8, 13>::new::<8>(),
);

Ranged

Similar to constant operations, these modify the output’s range, but also allow for some runtime variation. In this example, the value added to a number between 2 and 7 can be either 6 or 7:

assert_eq!(
    RangedI32::<2, 7>::new::<2>()
        .add_ranged(RangedI32::<6, 7>::new::<6>()),
    RangedI32::<8, 14>::new::<8>(),
);
assert_eq!(
    RangedI32::<2, 7>::new::<2>()
        .add_ranged(RangedI32::<6, 7>::new::<7>()),
    RangedI32::<8, 14>::new::<9>(),
);

Modules

ascii

ASCII Types

bitwise

Aliases for bitwise ranges (integers with arbitrary bit widths)

parsing

Error types related to parsing

range

Range utilities

unit

Aliases for unit (single value ranged) integers

Structs

RangedI8

i8 with a specified minimum and maximum value

RangedI16

i16 with a specified minimum and maximum value

RangedI32

i32 with a specified minimum and maximum value

RangedI64

i64 with a specified minimum and maximum value

RangedI128

i128 with a specified minimum and maximum value

RangedNonZeroI8

i8 not to equal zero with a specified minimum and maximum value

RangedNonZeroI16

i16 not to equal zero with a specified minimum and maximum value

RangedNonZeroI32

i32 not to equal zero with a specified minimum and maximum value

RangedNonZeroI64

i64 not to equal zero with a specified minimum and maximum value

RangedNonZeroI128

i128 not to equal zero with a specified minimum and maximum value

RangedNonZeroU8

u8 not to equal zero with a specified minimum and maximum value

RangedNonZeroU16

u16 not to equal zero with a specified minimum and maximum value

RangedNonZeroU32

u32 not to equal zero with a specified minimum and maximum value

RangedNonZeroU64

u64 not to equal zero with a specified minimum and maximum value

RangedNonZeroU128

u128 not to equal zero with a specified minimum and maximum value

RangedU8

u8 with a specified minimum and maximum value

RangedU16

u16 with a specified minimum and maximum value

RangedU32

u32 with a specified minimum and maximum value

RangedU64

u64 with a specified minimum and maximum value

RangedU128

u128 with a specified minimum and maximum value

Enums

Error

Error creating ranged integer

Quotient

The result of a division

Type Aliases

Result

Creating ranged integer result