assertables/assert_set/
mod.rs

1//! Assert for comparing set collections.
2//!
3//! These macros help with comparison of set parameters, such as two arrays or
4//! two vectors. where the item order does not matter, and the item count does
5//! not matter. These macros convert their inputs into HashSet iterators.
6//! See tutorial below.
7//!
8//! For eq & ne:
9//!
10//! * [`assert_set_eq!(collection1, collection2)`](macro@crate::assert_set_eq) ≈ set a = set b
11//!
12//! * [`assert_set_ne!(collection1, collection2)`](macro@crate::assert_set_ne) ≈ set a ≠ set b
13//!
14//! For subset & superset:
15//!
16//! * [`assert_set_subset!(collection1, collection2)`](macro@crate::assert_set_subset) ≈ set a ⊆ set b
17//!
18//! * [`assert_set_superset!(collection1, collection2)`](macro@crate::assert_set_superset) ≈ set a ⊇ set b
19//!
20//! For joint & disjoint:
21//!
22//! * [`assert_set_joint!(collection1, collection2)`](macro@crate::assert_set_joint) ≈ set a ∩ set b ≠ ∅
23//!
24//! * [`assert_set_disjoint!(collection1, collection2)`](macro@crate::assert_set_disjoint) ≈ set a ∩ set b = ∅
25//!
26//!
27//! # Example
28//!
29//! ```rust
30//! use assertables::*;
31//!
32//! let a = [1, 2];
33//! let b = [2, 1];
34//! assert_set_eq!(&a, &b);
35//! ```
36//!
37//! ## Tutorial
38//!
39//! A **set** means a collection of elements, without any ordering, without duplicate elements.
40//!
41//! A set is sometimes written by using mathematical notation, which looks like this:
42//!
43//! ```text
44//! set = {1, 2, 3}
45//! ```
46//!
47//! The definition of a set includes never having duplicate elements:
48//!
49//! ```text
50//! set = {1, 2, 3, 2} // error because the element 2 is a duplicate
51//! ```
52//!
53//! Sets are equal when they contain all the same elements in any order:
54//!
55//! ```text
56//! {1, 2, 3} = {1, 2, 3} (same order)
57//! {1, 2, 3} = {3, 2, 1} (different order)
58//! ```
59//!
60//! Sets are not equal when they contain any different elements:
61//!
62//! ```text
63//! {1, 2, 3} ≠ {1, 2}
64//! {1, 2, 3} ≠ {1, 2, 3, 4}
65//! ```
66//!
67//! To create a set using Rust, one way is to create an array or vector, then convert it into an iterator by using the method `into_iter`, then convert the elements into a set by using `std::collections::BTreeSet`:
68//!
69//! ```rust
70//! # use ::std::collections::BTreeSet;
71//! let array = [1, 2, 3];
72//! let set: BTreeSet<_> = array.into_iter().collect();
73//! ```
74//!
75//! To compare two arrays as sets, one way is to convert each array to a set, then use `assert_eq!` to compare the sets:
76//!
77//! ```rust
78//! # use ::std::collections::BTreeSet;
79//! let array1 = [1, 2, 3];
80//! let array2 = [3, 2, 1];
81//! let set1: BTreeSet<_> = array1.into_iter().collect();
82//! let set2: BTreeSet<_> = array2.into_iter().collect();
83//! assert_eq!(set1, set2);
84//! ```
85//!
86//! The `assertables` crate provides macros that do the conversion for you:
87//!
88//! ```rust
89//! # use ::std::collections::BTreeSet;
90//! # use assertables::*;
91//! let array1 = [1, 2, 3];
92//! let array2 = [3, 2, 1];
93//! assert_set_eq!(array1, array2);
94//! ```
95
96/// Assert set implementation preparation.
97#[macro_export]
98macro_rules! assert_set_impl_prep {
99    ($impl_into_iter:expr $(,)?) => {
100        match ($impl_into_iter) {
101            impl_into_iter => impl_into_iter.into_iter().collect(),
102        }
103    };
104}
105
106// Comparisons
107pub mod assert_set_eq;
108pub mod assert_set_ne;
109
110// Overlaps
111pub mod assert_set_disjoint;
112pub mod assert_set_joint;
113
114// Containers
115pub mod assert_set_subset;
116pub mod assert_set_superset;
assertables/assert_set/mod.rs

assertables/assert_set/
mod.rs
