Resolve issue 16

src/assert_any/assert_any_eq.rs

@@ -0,0 +1,267 @@
+//! Assert an iter contains an element.
+//!
+//! Pseudocode:<br>
+//! (collection1 into iter) contains (item)
+//!
+//! # Example
+//!
+//! ```rust
+//! use assertables::*;
+//!
+//! let a = [1, 2];
+//! let b = 1;
+//! assert_any_eq!(&a, &b);
+//! ```
+//!
+//! This implementation uses [`::std::iter::Iterator`](https://doc.rust-lang.org/std/iter/trait.Iterator.html).
+//!
+//! # Module macros
+//!
+//! * [`assert_any_eq`](macro@crate::assert_any_eq)
+//! * [`assert_any_eq_as_result`](macro@crate::assert_any_eq_as_result)
+//! * [`debug_assert_any_eq`](macro@crate::debug_assert_any_eq)
+
+/// Assert an iter contains an element.
+///
+/// Pseudocode:<br>
+/// (collection1 into iter) contains (item)
+///
+/// * If true, return Result `Ok(())`.
+///
+/// * Otherwise, return Result `Err(message)`.
+///
+/// This macro is useful for runtime checks, such as checking parameters,
+/// or sanitizing inputs, or handling different results in different ways.
+///
+/// This implementation uses [`::std::iter::Iterator`](https://doc.rust-lang.org/std/iter/trait.Iterator.html).
+///
+/// # Module macros
+///
+/// * [`assert_any_eq`](macro@crate::assert_any_eq)
+/// * [`assert_any_eq_as_result`](macro@crate::assert_any_eq_as_result)
+/// * [`debug_assert_any_eq`](macro@crate::debug_assert_any_eq)
+///
+#[macro_export]
+macro_rules! assert_any_eq_as_result {
+    ($a_collection:expr, $b_item:expr $(,)?) => {
+        match ($a_collection, $b_item) {
+            (a_collection, b_item) => {
+                let mut a = a_collection.into_iter();
+                if a.any(|x| x == b_item) {
+                    Ok(())
+                } else {
+                    Err(format!(
+                        concat!(
+                            "assertion failed: `assert_any_eq!(a_collection, b_item)`\n",
+                            "https://docs.rs/assertables/9.8.4/assertables/macro.assert_any_eq.html\n",
+                            " a label: `{}`,\n",
+                            " a debug: `{:?}`,\n",
+                            " b label: `{}`,\n",
+                            " b debug: `{:?}`"
+                        ),
+                        stringify!($a_collection),
+                        a_collection,
+                        stringify!($b_item),
+                        b_item
+                    ))
+                }
+            }
+        }
+    };
+}
+
+#[cfg(test)]
+mod test_assert_any_eq_as_result {
+    // use std::sync::Once;
+
+    #[test]
+    fn success_int() {
+        let a = [1, 2];
+        let b = 1;
+        for _ in 0..1 {
+            let actual = assert_any_eq_as_result!(&a, &b);
+            assert_eq!(actual.unwrap(), ());
+        }
+    }
+
+    #[test]
+    fn success_struct() {
+        #[derive(Debug, PartialEq)]
+        struct Point {
+            x: i32,
+            y: i32,
+        }
+        let points: [Point; 2] = [Point { x: 1, y: 2 }, Point { x: 2, y: 3 }];
+        let point = Point { x: 1, y: 2 };
+        for _ in 0..1 {
+            let actual = assert_any_eq_as_result!(&points, &point);
+            assert_eq!(actual.unwrap(), ());
+        }
+    }
+
+    #[test]
+    fn failure() {
+        let a = [1, 2];
+        let b = 0;
+        let actual = assert_any_eq_as_result!(&a, &b);
+        let message = concat!(
+            "assertion failed: `assert_any_eq!(a_collection, b_item)`\n",
+            "https://docs.rs/assertables/9.8.4/assertables/macro.assert_any_eq.html\n",
+            " a label: `&a`,\n",
+            " a debug: `[1, 2]`,\n",
+            " b label: `&b`,\n",
+            " b debug: `0`"
+        );
+        assert_eq!(actual.unwrap_err(), message);
+    }
+}
+
+/// Assert an iterable is equal to another.
+///
+/// Pseudocode:<br>
+/// (collection1 into iter) = (collection2 into iter)
+///
+/// * If true, return `()`.
+///
+/// * Otherwise, call [`panic!`] with a message and the values of the
+///   expressions with their debug representations.
+///
+/// # Examples
+///
+/// ```rust
+/// use assertables::*;
+/// # use std::panic;
+///
+/// # fn main() {
+/// let a = [1, 2];
+/// let b = 1;
+/// assert_any_eq!(&a, &b);
+///
+/// # let result = panic::catch_unwind(|| {
+/// // This will panic
+/// let a = [1, 2];
+/// let b = 0;
+/// assert_any_eq!(&a, &b);
+/// # });
+/// // assertion failed: `assert_any_eq!(a_collection, b_item)`
+/// // https://docs.rs/assertables/…/assertables/macro.assert_any_eq.html
+/// //  a label: `&a`,
+/// //  a debug: `[1, 2]`,
+/// //  b label: `&b`,
+/// //  b debug: `0`
+/// # let actual = result.unwrap_err().downcast::<String>().unwrap().to_string();
+/// # let message = concat!(
+/// #     "assertion failed: `assert_any_eq!(a_collection, b_item)`\n",
+/// #     "https://docs.rs/assertables/9.8.4/assertables/macro.assert_any_eq.html\n",
+/// #     " a label: `&a`,\n",
+/// #     " a debug: `[1, 2]`,\n",
+/// #     " b label: `&b`,\n",
+/// #     " b debug: `0`",
+/// # );
+/// # assert_eq!(actual, message);
+/// # }
+/// ```
+///
+/// This implementation uses [`::std::iter::Iterator`](https://doc.rust-lang.org/std/iter/trait.Iterator.html).
+///
+/// # Module macros
+///
+/// * [`assert_any_eq`](macro@crate::assert_any_eq)
+/// * [`assert_any_eq_as_result`](macro@crate::assert_any_eq_as_result)
+/// * [`debug_assert_any_eq`](macro@crate::debug_assert_any_eq)
+///
+#[macro_export]
+macro_rules! assert_any_eq {
+    ($a_collection:expr, $b_item:expr $(,)?) => {
+        match $crate::assert_any_eq_as_result!($a_collection, $b_item) {
+            Ok(()) => (),
+            Err(err) => panic!("{}", err),
+        }
+    };
+    ($a_collection:expr, $b_item:expr, $($message:tt)+) => {
+        match $crate::assert_any_eq_as_result!($a_collection, $b_item) {
+            Ok(()) => (),
+            Err(err) => panic!("{}\n{}", format_args!($($message)+), err),
+        }
+    };
+}
+
+#[cfg(test)]
+mod test_assert_any_eq {
+    use std::panic;
+
+    #[test]
+    fn success() {
+        let a = [1, 2];
+        let b = 2;
+        for _ in 0..1 {
+            let actual = assert_any_eq!(&a, &b);
+            assert_eq!(actual, ());
+        }
+    }
+
+    #[test]
+    fn failure() {
+        let a = [1, 2];
+        let b = 0;
+        let result = panic::catch_unwind(|| {
+            let _actual = assert_any_eq!(&a, &b);
+        });
+        let message = concat!(
+            "assertion failed: `assert_any_eq!(a_collection, b_item)`\n",
+            "https://docs.rs/assertables/9.8.4/assertables/macro.assert_any_eq.html\n",
+            " a label: `&a`,\n",
+            " a debug: `[1, 2]`,\n",
+            " b label: `&b`,\n",
+            " b debug: `0`"
+        );
+        assert_eq!(
+            result
+                .unwrap_err()
+                .downcast::<String>()
+                .unwrap()
+                .to_string(),
+            message
+        );
+    }
+}
+
+/// Assert an iterable is equal to another.
+///
+/// Pseudocode:<br>
+/// (collection1 into iter) = (collection2 into iter)
+///
+/// This macro provides the same statements as [`assert_any_eq`](macro.assert_any_eq.html),
+/// except this macro's statements are only enabled in non-optimized
+/// builds by default. An optimized build will not execute this macro's
+/// statements unless `-C debug-assertions` is passed to the compiler.
+///
+/// This macro is useful for checks that are too expensive to be present
+/// in a release build but may be helpful during development.
+///
+/// The result of expanding this macro is always type checked.
+///
+/// An unchecked assertion allows a program in an inconsistent state to
+/// keep running, which might have unexpected consequences but does not
+/// introduce unsafety as long as this only happens in safe code. The
+/// performance cost of assertions, however, is not measurable in general.
+/// Replacing `assert*!` with `debug_assert*!` is thus only encouraged
+/// after thorough profiling, and more importantly, only in safe code!
+///
+/// This macro is intended to work in a similar way to
+/// [`::std::debug_assert`](https://doc.rust-lang.org/std/macro.debug_assert.html).
+///
+/// # Module macros
+///
+/// * [`assert_any_eq`](macro@crate::assert_any_eq)
+/// * [`assert_any_eq`](macro@crate::assert_any_eq)
+/// * [`debug_assert_any_eq`](macro@crate::debug_assert_any_eq)
+///
+#[macro_export]
+macro_rules! debug_assert_any_eq {
+    ($($arg:tt)*) => {
+        if $crate::cfg!(debug_assertions) {
+            $crate::assert_any_eq!($($arg)*);
+        }
+    };
+}