Crate assure

Crate assure 

Source
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) returns Result with Ok(x) or Err("assure").

  • assure_eq(x, y) returns Result with Ok(x) or Err("assure_eq left:1 right:2")).

For comparison assert macros work like this:

  • assert!(x) returns successfully or calls panic!.

  • assert_eq!(x, y) returns successfully or calls panic!.

§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) returns Err("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") returns Err("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:

Macros for value comparison:

§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 set a is equal to the set b.

  • [assure_set_ne](a, b): assure the set a is not equal to the set b.

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 bag a is equal to the bag b.

  • [assure_bag_ne](a, b): assure the bag a is not equal to the bag b.

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}")

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:

Macros for value comparison:

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.