Crate assertables[][src]

Assertables: Rust crate of macros assert, assume, assure

This assertables Rust crate provides macros assert…!, assume…!, assure…!, all for runtime reliability checking, and all described below. By SixArm.com.

Crate: https://crates.io/crates/assure

Docs: https://docs.rs/assure/

Repo: https://github.com/joelparkerhenderson/assure-rust-crate/

Introduction

This Rust crate provides macros for Rust runtime checking, and each macro comes in three flavors:

  • assert…! returns () or calls panic!

  • assume…! returns Result with Ok(true) or Err(…)

  • assure…! returns Result with Ok(true) or Ok(false) or Err(…)

Examples of assert_lt!:

assert_lt!(1, 2);
//-> ()
// assert_lt!(2, 1);
//-> panic!("assertion failed: `(left == right)`\n  left: `2`,\n right: `1`")

Examples of assume_lt!:

let x = assume_lt!(1, 2);
//-> Ok(true)
let x = assume_lt!(2, 1);
//-> Err("assumption failed: `(left == right)`\n  left: `2`,\n right: `1`")

Examples of assure_lt!:

let x = assure_lt!(1, 2);
//-> Ok(true)
let x = assure_lt!(2, 1);
//-> Ok(false)

Assert

The assert… macros can be useful with Rust testing, such as with macros that Rust std does not provide.

Example:

fn sum_positive_numbers(a: i32, b: i32) -> Result<i32, String> {
    assert_lt!(0, a);
    assert_lt!(0, b);
    Ok(a + b)
}

sum_positive_numbers(1, 2);
//-> 3

// sum_positive_numbers(-1, -2);
//-> panic!("assertion failed: `(left == right)`\n  left: `0`,\n right: `-1`")

Assume

The assume… macros can be useful with the ? operator, such as with early exits in functions.

Example:

fn sum_positive_numbers(a: i32, b: i32) -> Result<i32, String> {
    assume_lt!(0, a)?;
    assume_lt!(0, b)?;
    Ok(a + b)
}

sum_positive_numbers(1, 2);
//-> Ok(3)

sum_positive_numbers(-1, -2);
//-> Err("assumption failed: `assume_lt(left, right)`\n  left: `0`,\n right: `-1`")

Assure

The assure… macros can be useful with chaining, such as with gate conditions in functions.

Example:

fn sum_positive_numbers(a: i32, b: i32) -> Result<i32, String> {
    if assure_lt!(0, a).unwrap() && assure_lt!(0, b).unwrap() {
        Ok(a + b)
    } else {
        Err(format!("please use positive numbers"))
    }
}

sum_positive_numbers(1, 2);
//-> Ok(3)

sum_positive_numbers(-1, -2);
//-> Err("must use postive numbers")

Messages

When a macro fails, it generates a failure message with the values of expressions with their debug representations, such as:

// assert_lt!(2, 1)
//-> panic!("assertion failed: `(left == right)`\n  left: `2`,\n right: `1`")

These macros have a second form where a custom message can be provided, such as:

// assert_lt!(2, 1, "my message here");
//-> panic!("my message here")

Macros for values

Examples:

let x = assume_lt!(1, 2);
//-> Ok(true)
let x = assume_lt!(2, 1);
//-> Err("assumption failed: `assert_lt(left, right)`\n  left: `2`\n right: `1`")

assert… macros:

  • assert!(a): assure a is true, provided by Rust std.

  • assert_eq!(a, b): assert a is equal to b, provided by Rust std.

  • assert_ne!(a, b): assert a is not equal to b, provided by Rust std.

  • assert_lt!(a, b): assert a is less than b.

  • assert_le!(a, b): assert a is less than or equal to b.

  • assert_gt!(a, b): assert a is greater than b.

  • assert_ge!(a, b): assert a is greater than or equal to b.

assume… macros:

assure… macros:

Macros for set checking

These 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.

Examples:

let x = assume_set_eq!([1, 2], [2, 1]);
//-> Ok(true)
let x = assume_set_eq!([1, 2], [3, 4]);
//-> Err("assertion failed: `assert_set_eq(left, right)`\n  left: `[1, 2]`\n right: `[3, 4]`")

assert_set… macros:

assume_set… macros:

assure_set… macros:

Macros for bag checking

Thes 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.

Examples:

let x = assume_bag_eq!([1, 1], [1, 1]);
//-> Ok(true)
let x = assume_bag_eq!([1, 1], [1, 1, 1]);
//-> Err("assumption failed: `assume_bag_eq(left, right)`\n  left: `[1, 1]`\n right: `[1, 1, 1]`")]

assert_bag… macros:

  • [assert_bag_eq](a, b): assert the bag a is equal to the bag b.

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

assume_bag… macros:

assure_bag… macros:

Macros for IO-related checking

These 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)).

Examples:

let x = assume_io_lt!(1, 2);
//-> Ok(true)
let x = assume_io_lt!(2, 1);
//-> Err(
//       std::io::Error::new(
//           std::io::ErrorKind::InvalidInput, 
//           "assumption failed: `assume_io_lt(left, right)`\n  left: `2`\n right: `1`")]
//       )
//   )

assert_io… macros:

assume_io… macros:

assure_io… macros:

Modules

assert
assert_bag_eq
assert_bag_ne
assert_eq
assert_ge
assert_gt
assert_io_eq
assert_io_ge
assert_io_gt
assert_io_le
assert_io_lt
assert_io_ne
assert_le
assert_lt
assert_ne
assert_set_eq
assert_set_ne
assume
assume_bag_eq
assume_bag_ne
assume_eq
assume_ge
assume_gt
assume_io
assume_io_eq
assume_io_ge
assume_io_gt
assume_io_le
assume_io_lt
assume_io_ne
assume_le
assume_lt
assume_ne
assume_set_eq
assume_set_ne
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

assert_bag_eq

Assert two bags are equal.

assert_bag_ne

Assert two bags are not equal.

assert_ge

Assert one value is greater than or equal to another value.

assert_gt

Assert one value is greater than another value.

assert_io_eq

Assert two values are equal.

assert_io_ge

Assert one value is greater than or equal to another value.

assert_io_gt

Assert one value is greater than another value.

assert_io_le

Assert one value is less than or equal to another value.

assert_io_lt

Assert one value is less than another value.

assert_io_ne

Assert two values are equal.

assert_le

Assert one value is less than or equal to another value.

assert_lt

Assert one value is less than another value.

assert_set_eq

Assert two sets are equal.

assert_set_ne

Assert two sets are not equal.

assume

Assume a condition is true.

assume_bag_eq

Assume two bags are equal.

assume_bag_ne

Assume two bags are not equal.

assume_eq

Assume two values are equal.

assume_ge

Assume one value is greater than or equal to another value.

assume_gt

Assume one value is greater than another value.

assume_io

Assume a condition is true.

assume_io_eq

Assume one value is equal to another value.

assume_io_ge

Assume one value is greater than or equal to another value.

assume_io_gt

Assume one value is greater than another value.

assume_io_le

Assume one value is less than or equal to another value.

assume_io_lt

assume one value is less than another value.

assume_io_ne

Assume one value is not equal to another value.

assume_le

Assume one value is less than or equal to another value.

assume_lt

Assume one value is less than another value.

assume_ne

Assume two values are not equal.

assume_set_eq

Assume two sets are equal.

assume_set_ne

Assume two sets are not equal.

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 one value is equal to another value.

assure_io_ge

Assure one value is greater than or equal to another value.

assure_io_gt

Assure one value is greater 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 one value is not equal to another value.

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.