Expand description
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)
}
sum_positive_numbers(1, 2);
//-> Ok(3)
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"
))
Modules§
- assure
- assure_
bag_ eq - assure_
bag_ ne - assure_
eq - assure_
ge - assure_
gt - assure_
io - assure_
io_ eq - assure_
io_ ge - assure_
io_ gt - assure_
io_ le - assure_
io_ lt - assure_
io_ ne - assure_
le - assure_
lt - assure_
ne - assure_
set_ eq - assure_
set_ ne
Macros§
- assure
- Assure a condition is true.
- assure_
bag_ eq - Assure two bags are equal.
- assure_
bag_ ne - Assure two bags are not equal.
- assure_
eq - Assure two values are equal.
- assure_
ge - Assure one value is greater than or equal to another value.
- assure_
gt - Assure one value is greater than another value.
- assure_
io - Assure a condition is true.
- assure_
io_ eq - Assure two values are equal.
- assure_
io_ ge - Assure one value is less than another value.
- assure_
io_ gt - Assure one value is less than another value.
- assure_
io_ le - Assure one value is less than or equal to another value.
- assure_
io_ lt - Assure one value is less than another value.
- assure_
io_ ne - Assure two values are not equal.
- assure_
le - Assure one value is less than or equal to another value.
- assure_
lt - Assure one value is less than another value.
- assure_
ne - Assure two values are not equal.
- assure_
set_ eq - Assure two sets are equal.
- assure_
set_ ne - Assure two sets are not equal.