Crate assertables[−][src]

assert-assume-assure: macros for Rust runtime checking

This Rust crate provides macros for Rust runtime checking. using assert…!, assume…!, assure…!, described below.

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:

assume!(a): assume a is true.
assume_eq!(a, b): assume a is equal to b.
assume_ne!(a, b): assume a is not equal to b.
assume_lt!(a, b): assume a is less than b.
assume_le!(a, b): assume a is less than or equal to b.
assume_gt!(a, b): assume a is greater than b.
assume_ge!(a, b): assume a is greater than or equal to b.

assure… macros:

assure!(a): assure a is true.
assure_eq!(a, b): assure a is equal to b.
assure_ne!(a, b): assure a is not equal to b.
assure_lt!(a, b): assure a is less than b.
assure_le!(a, b): assure a is less than or equal to b.
assure_gt!(a, b): assure a is greater than b.
assure_ge!(a, b): assure a is greater than or equal to b.

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:

assert_set_eq!(a, b): assert the set a is equal to the set b.
assert_set_ne!(a, b): assert the set a is not equal to the set b.

assume_set… macros:

assume_set_eq!(a, b): assume the set a is equal to the set b.
assume_set_ne!(a, b): assume the set a is not equal to the set b.

assure_set… macros:

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.

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:

assume_bag_eq!(a, b): assume the bag a is equal to the bag b.
assume_bag_ne!(a, b): assume the bag a is not equal to the bag b.

assure_bag… macros:

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.

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:

[assert_io!](a): assert a is true.
assert_io_eq!(a, b): assert a is equal to b.
assert_io_ne!(a, b): assert a is not equal to b.
assert_io_lt!(a, b): assert a is less than b.
assert_io_le!(a, b): assert a is less than or equal to b.
assert_io_gt!(a, b): assert a is greater than b.
assert_io_ge!(a, b): assert a is greater than or equal to b.

assume_io… macros:

assume_io!(a): assume a is true.
assume_io_eq!(a, b): assume a is equal to b.
assume_io_ne!(a, b): assume a is not equal to b.
assume_io_lt!(a, b): assume a is less than b.
assume_io_le!(a, b): assume a is less than or equal to b.
assume_io_gt!(a, b): assume a is greater than b.
assume_io_ge!(a, b): assume a is greater than or equal to b.

assure_io… macros:

assure_io!(a): assure a is true.
assure_io_eq!(a, b): assure a is equal to b.
assure_io_ne!(a, b): assure a is not equal to b.
assure_io_lt!(a, b): assure a is less than b.
assure_io_le!(a, b): assure a is less than or equal to b.
assure_io_gt!(a, b): assure a is greater than b.
assure_io_ge!(a, b): assure a is greater than or equal to b.

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.