deranged

deranged is a Rust library that provides ranged integer types — integers whose valid minimum and maximum bounds are encoded directly in the type via const generics (for example RangedU8<0, 100>). This lets the type system guarantee that a value always falls within its declared range, turning a class of runtime bugs into compile-time or checked-construction errors.

It offers a full family of RangedIN/RangedUN types, Option-optimized variants, and a macro that automatically picks the smallest inner integer type for a given range. Widely used as a dependency of the time crate, deranged is small, no_std-friendly, and integrates with serde, rand, num-traits, and quickcheck through feature flags.

What You Get

• A family of ranged integer types with const-generic minimum and maximum bounds
• Option-optimized variants that pack the niche without extra memory
• A macro that auto-selects the smallest inner integer type for a range
• Checked, saturating, and wrapping arithmetic that preserve range invariants
• no_std support and optional serde, rand, num-traits, and quickcheck integration

Common Use Cases

• Enforcing valid numeric ranges (percentages, hours, indices) at the type level
• Backing time and date components that must stay within fixed bounds (as used by the time crate)
• Eliminating bounds-check boilerplate by making out-of-range values unrepresentable
• Building space-efficient optional integers via niche optimization

Under The Hood

Architecture - deranged is a small Cargo workspace with the deranged library crate and a deranged-macros proc-macro crate. The core lib.rs defines RangedIN/RangedUN and OptionRanged* types generic over const MIN and const MAX, backed by an unsafe_wrapper module that centralizes the unchecked invariant assertions (assert_unchecked) that let the compiler optimize on the known range.

Tech Stack - Written in Rust (edition 2021, MSRV 1.85, #![no_std]), it has no required dependencies and gates optional integrations — serde, three major rand versions, num-traits, powerfmt, and quickcheck — behind cargo features. The workspace enforces a large set of deny/warn lints for correctness.

Code Quality - The crate keeps a tight surface with a dedicated tests.rs module, extensive workspace lint configuration, and careful isolation of unsafe in unsafe_wrapper.rs. Its use as a core dependency of the widely-deployed time crate (hundreds of millions of downloads) provides substantial real-world validation.

API Design - The public API mirrors standard integer methods (checked/saturating/wrapping arithmetic, conversions) so it feels familiar, while the int! and opt_int! macros remove boilerplate by computing the inner type automatically. Documentation is concise; the README frames it as a proof-of-concept, so the learning curve comes mostly from understanding const-generic bounds.