14 stable releases
2.1.0 | Apr 1, 2021 |
---|---|
2.0.0 | Apr 1, 2021 |
1.11.0 | Mar 31, 2021 |
#1745 in Rust patterns
75KB
2K
SLoC
Assure: macros for Rust runtime checking
This Rust crate provides the macro assure!
and related macros.
These are intentionally similar to the macro assert!
and related macros.
Available via https://crates.io/crates/assure
Introduction
The assure
macros work like this:
-
assure!(x)
returnsResult
withOk(x)
orErr("assure")
. -
assure_eq(x, y)
returnsResult
withOk(x)
orErr("assure_eq left:1 right:2"))
.
For comparison assert
macros work like this:
-
assert!(x)
returns successfully or callspanic!
. -
assert_eq!(x, y)
returns successfully or callspanic!
.
Return Ok or Err
The assure
macros return Result
with either:
-
Ok(…)
with the leftmost macro argument. -
Err(…)
with a generated error message intended for diagnostics.
Example of Ok
:
let a = 1;
let b = 1;
assure_eq!(a, b);
//-> Ok(a)
Example of Err
:
let a = 1;
let b = 2;
assure_eq!(a, b);
//-> Err("assure_eq left:1 right:2")
Usage
The assure
macros can useful for checking with the ?
operator.
This example function uses the assure_gt!
macro, which means assure greater than:
fn sum_positive_numbers(a: i32, b: i32) -> Result<i32, String> {
assure_gt!(a, 0)?;
assure_gt!(b, 0)?;
Ok(a + b)
}
Example of Ok
:
sum_positive_numbers(1, 2);
//-> Ok(3)
Example of Err
:
sum_positive_numbers(1, -2);
//-> Err("assure_gt left:-2 right:0)
Custom error messages
The assure
macros generate a defult diagnostic error message such as:
assure_eq!(1, 2)
returnsErr("assure_eq left:1 right:2")
.
The macros have a second form, where a custom error message can be provided as the last argument:
assure_eq!(1, 2, "message")
returnsErr("message")
.
Example error message:
fn sum_positive_numbers(a: i32, b: i32) -> Result<i32, String> {
assure_gt!(a, 0, "param 1 must be postive but is {}", a)?;
assure_gt!(b, 0, "param 2 must be postive but is {}", b)?;
Ok(a + b)
}
Macros for simple values
Macro for truth checking:
assure!(a)
: assurea
is true.
Macros for value comparison:
-
assure_eq!(a, b)
: assurea
is equal tob
. -
assure_ne!(a, b)
: assurea
is not equal tob
. -
assure_lt!(a, b)
: assurea
is less thanb
. -
assure_le!(a, b)
: assurea
is less than or equal tob
. -
assure_gt!(a, b)
: assurea
is greater thanb
. -
assure_ge!(a, b)
: assurea
is greater than or equal tob
.
Macros for set checking
The assure_set…!
macros help with comparison of set parameters, such as two arrays or two vectors. where the item order does not matter, and the item count does not matter.
-
assure_set_eq(a, b)
: assure the seta
is equal to the setb
. -
assure_set_ne(a, b)
: assure the seta
is not equal to the setb
.
Example of Ok
:
let a = [1, 2];
let b = [2, 1];
assure_set_eq!(&a, &b);
//-> Ok(&a)
Example of Err
:
let a = [1, 2];
let b = [3, 4];
assure_set_eq!(&a, &b);
//-> Err("assure_set_eq left:{1, 2} right:{3, 4}")
Macros for bag checking
The assure_bag…!
macros help with comparison of bag parameters, such as comparison of two arrays or two vectors, where the item order does not matter, and the item count does matter.
-
assure_bag_eq(a, b)
: assure the baga
is equal to the bagb
. -
assure_bag_ne(a, b)
: assure the baga
is not equal to the bagb
.
Example of Ok
:
let a = [1, 1];
let b = [1, 1];
assure_set_eq!(&a, &b);
//-> Ok(&a)
Example of Err
:
let a = [1, 1];
let b = [1, 1, 1];
assure_set_eq!(&a, &b);
//-> Err("assure_bag_eq left:{1: 2} right:{1: 3}")
Macros for IO-related checking
The assure_io…!
macros help with IO-related checking, such as comparison of files, streams, etc. These macros return a Result
with Ok(true)
or Err(std::io::Error::new(std::io::ErrorKind::InvalidInput, message))
.
Macro for truth checking:
assure_io!(a)
: assurea
is true.
Macros for value comparison:
-
assure_io_eq!(a, b)
: assurea
is equal tob
. -
assure_io_ne!(a, b)
: assurea
is not equal tob
. -
assure_io_lt!(a, b)
: assurea
is less thanb
. -
assure_io_le!(a, b)
: assurea
is less than or equal tob
. -
assure_io_gt!(a, b)
: assurea
is greater thanb
. -
assure_io_ge!(a, b)
: assurea
is greater than or equal tob
.
Example of Ok
:
let a = 1;
let b = 1;
assure_io_eq!(a, b);
//-> Ok(a)
Example of Err
:
let a = 1;
let b = 2;
assure_io_eq!(a, b);
//-> Err(
// std::io::Error::new(
// std::io::ErrorKind::InvalidInput,
// "assure_io_eq left:1 right:2"
// )
// )