4 releases
0.2.3 | Nov 24, 2022 |
---|---|
0.2.2 | Aug 19, 2022 |
0.2.0 | Jul 11, 2022 |
0.1.2 |
|
#1009 in Algorithms
205KB
2.5K
SLoC
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.
Dependencies
~1.5MB
~37K SLoC