# rust-range-check [](https://crates.io/crates/range_check) [](https://travis-ci.org/ogham/rust-range-check)
This is a little library for early returns with range and bounds checking. It works with Rust’s standard `Range` types.
### [View the Rustdoc](https://docs.rs/range_check)
# Installation
This crate works with [Cargo](https://crates.io). Add the following to your `Cargo.toml` dependencies section:
```toml
[dependencies]
range_check = "0.2"
```
# Stability
This crate requires the `collections_range` feature, which was stabilised in Rust 1.28.0.
# Examples
## Range checking in the stdlib
Rust’s standard library allows you to test whether a range contains
a specified value:
```rust
// Range checking with std::ops
assert_eq!((0..24).contains(&23), true);
assert_eq!((0..24).contains(&24), false);
```
For more information, see the
[official Rust documentation for `std::ops::RangeBounds`](https://doc.rust-lang.org/std/ops/trait.RangeBounds.html).
## Range checking with this crate
The `range_check` crate provides the `Check` trait that has a function `check_range`, which returns a `Result` instead of a `bool`.
If the value exists within the range, it will return the value as an `Ok` variant:
```rust
use range_check::Check;
assert_eq!(24680.check_range(1..99999),
Ok(24680));
```
If the value does _not_ exist within the range, it will be returned inside an `OutOfRangeError` error variant:
```rust
use range_check::Check;
assert_eq!(24680.check_range(1..9999).unwrap_err().to_string(),
"value (24680) outside of range (1..9999)");
```
## Failing early if a value is outside a range
When testing multiple values, it can sometimes be helpful to automatically return when one of them is outside a range.
In this example, we use the `?` operator to return early:
```rust
use range_check::{Check, OutOfRangeError};
struct Clock {
hour: i8,
minute: i8,
}
impl Clock {
fn new(hour: i8, minute: i8) -> Result<Clock, OutOfRangeError<i8>> {
Ok(Clock {
hour: hour.check_range(0..24)?,
minute: minute.check_range(0..60)?,
})
}
}
assert!(Clock::new(23, 59).is_ok());
assert!(Clock::new(23, 60).is_err());
assert!(Clock::new(24, 00).is_err());
```
It becomes a problem when the values being tested are of different types, as there can only be one type as the error `Result` from the function.
As long as the types can be converted using the `From` trait, you can convert the error using the `OutOfRangeError::generify` function. In the first call in this example, we convert the error from containing an `i8` to an `i16`:
```rust
use range_check::{Check, OutOfRangeError};
struct Clock {
second: i8,
millisecond: i16,
}
impl Clock {
fn new(second: i8, millisecond: i16) -> Result<Clock, OutOfRangeError<i16>> {
Ok(Clock {
second: second.check_range(0..60).map_err(OutOfRangeError::generify)?,
millisecond: millisecond.check_range(0..1000)?,
})
}
}
assert!(Clock::new(45, 576).is_ok());
assert!(Clock::new(49, 23456).is_err());
assert!(Clock::new(61, 0).is_err());
```