Integers that are constrained within inclusive ranges

Constrained types are represented simply as primitive integers, but their values will always be contained by inclusive range bounds. The range is defined at compile time, by assigning values to appropriate const generic parameters. Constrained types provide fallible APIs for construction and value assignment, they also implement wrapping, saturating, overflowing and checked arithmetic operations for the range boundaries. See each desired type documentation for more information.

The constrained_int crate relies on the const_guards crate to define compile time constraints, which itself uses the incomplete generic_const_exprs feature. Therefore, this crate can only be compiled with nightly and, more importantly, must be considered as an experimental crate only.

This crate is no_std by default. See features section for more information.

Install

# Cargo.toml

[dependencies]
constrained_int = "0.2"

Example

use constrained_int::i8::{ConstrainedI8, ConstrainedI8Error};

// Lower bound = -5, upper bound = 10, default = -1.
type Constrained = ConstrainedI8<-5, 10, -1>;
type ConstrainedError = ConstrainedI8Error<-5, 10>;

fn main() -> Result<(), ConstrainedError> {
    // Gets the default value.
    let mut constrained = Constrained::default();
    assert_eq!(constrained.get(), -1);

    // Sets within inclusive range, succeeds.
    constrained.set(-5)?;
    assert_eq!(constrained.get(), -5);

    // Below lower bound, fails.
    assert_eq!(constrained.checked_sub(1), None);
    assert_eq!(constrained.get(), -5);

    // Saturates at the upper bound.
    constrained = constrained.saturating_add(100);
    assert_eq!(constrained.get(), 10);

    // Sets out of boundary, fails.
    assert!(constrained.set(11).is_err());

    // Wraps around the upper bound.
    constrained = constrained.wrapping_add(1);
    assert_eq!(constrained.get(), -5);

    Ok(())
}

Documentation

This project documentation is hosted at docs.rs.

Safety

This crate uses #![forbid(unsafe_code)] to ensure everything is implemented in 100% safe Rust.

Feature flags

This crate does not provide any default features. The features that can be enabled are: std and serde.

std

This crate does not link against the standard library by default, so it is suitable for no_std environments. It does provide a std feature though, that enables the standard library as a dependency. By enabling this crate's std feature, these additional features are provided:

All crate's error types will implement the std::error::Error trait.

If users already are importing the standard library on their crate, enabling std feature comes at no additional cost.

serde

The serde feature implements serde's Serialize and Deserialize traits for Wrapping, Saturating and all Constrained types. Note that construction constraints for const generic parameters are checked at runtime when values are deserialized to any of Constrained types. See each desired type documentation for more information about these constraints.

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Code review

It is recommended to always use cargo-crev to verify the trustworthiness of each of your dependencies, including this one.

constrained_int 0.2.3