Implements container_eq(...).ignore_order() matcher.

This adds a matcher `IgnoringOrder` for the `container_eq` matcher.  It reuses the `match_matrix` library so it can apply a maximal matching.

PiperOrigin-RevId: 707634546

Author: Googler

googletest/src/matchers/container_eq_matcher.rs

@@ -14,6 +14,8 @@
 
 use crate::description::Description;
 use crate::matcher::{Matcher, MatcherBase, MatcherResult};
+use crate::matcher_support::match_matrix::internal::{MatchMatrix, Requirements};
+use crate::matchers::eq_matcher::eq;
 use std::fmt::Debug;
 
 /// Matches a container equal (in the sense of `==`) to `expected`.
@@ -153,6 +155,102 @@ fn build_explanation<T: Debug, U: Debug>(missing: Vec<T>, unexpected: Vec<U>) ->
     }
 }
 
+impl<ExpectedContainerT> ContainerEqMatcher<ExpectedContainerT> {
+    /// Match container equality, but ignoring element order.
+    pub fn ignore_order(self) -> IgnoringOrder<ExpectedContainerT> {
+        IgnoringOrder { expected: self.expected }
+    }
+}
+
+#[derive(MatcherBase)]
+pub struct IgnoringOrder<ExpectedContainerT> {
+    expected: ExpectedContainerT,
+}
+
+/// Implements a matcher that ignores the relative order of the elements.
+impl<ActualElementT, ActualContainerT, ExpectedElementT, ExpectedContainerT>
+    Matcher<ActualContainerT> for IgnoringOrder<ExpectedContainerT>
+where
+    ActualElementT: Debug + Copy + for<'a> PartialEq<&'a ExpectedElementT>,
+    ActualContainerT: Debug + Copy + IntoIterator<Item = ActualElementT>,
+    ExpectedElementT: Debug,
+    for<'a> &'a ExpectedContainerT: IntoIterator<Item = &'a ExpectedElementT>,
+{
+    fn matches(&self, actual: ActualContainerT) -> MatcherResult {
+        let expected: Vec<Box<dyn Matcher<ActualElementT>>> = self
+            .expected
+            .into_iter()
+            .map(|x| Box::new(eq(x)) as Box<dyn Matcher<ActualElementT>>)
+            .collect();
+        let match_matrix = MatchMatrix::generate(actual, &expected);
+        // TODO: investigate why Requirements::PerfectMatch and
+        // match_matrix.is_full_match is not doing what we expect
+        // here.
+        (match_matrix.is_match_for(Requirements::Subset)
+            && match_matrix.is_match_for(Requirements::Superset))
+        .into()
+    }
+
+    fn explain_match(&self, actual: ActualContainerT) -> Description {
+        // We need to materialize the collections in order to have reliable iteration
+        // order when generating our reports.
+        let expected_items: Vec<&ExpectedElementT> = self.expected.into_iter().collect();
+        let actual_items: Vec<ActualElementT> = actual.into_iter().collect();
+
+        let expected_matchers: Vec<_> = expected_items
+            .iter()
+            .map(|&x| Box::new(eq(x)) as Box<dyn Matcher<ActualElementT>>)
+            .collect();
+        let match_matrix = MatchMatrix::generate(actual_items.iter().copied(), &expected_matchers);
+
+        let best_match = match_matrix.find_best_match();
+
+        // Since we are doing equality checks, we can generate a slightly less verbose
+        // message than BestMatch::get_explanation.
+        let matches = best_match.get_matches().map(|(actual_idx, expected_idx)|{
+            Description::new().text(
+                format!(
+                    "Actual element {:?} at index {actual_idx} is equal to expected element at index {expected_idx}.",
+                    actual_items[actual_idx],
+                ))});
+
+        let unmatched_actual = best_match.get_unmatched_actual().map(|actual_idx| {
+            Description::new().text(
+                format!(
+                    "Actual element {:?} at index {actual_idx} did not match any remaining expected element.",
+                    actual_items[actual_idx],
+                ))
+        });
+
+        let unmatched_expected =
+            best_match.get_unmatched_expected().into_iter().map(|expected_idx| {
+                Description::new().text(format!(
+            "Expected element {:?} at index {expected_idx} did not match any remaining actual element.",
+                    expected_items[expected_idx]
+        ))
+            });
+
+        Description::new()
+            .text("which does not have a perfect match.  The best match found was:")
+            .collect(matches.chain(unmatched_actual).chain(unmatched_expected))
+    }
+
+    fn describe(&self, matcher_result: MatcherResult) -> Description {
+        Description::new()
+            .text(format!(
+                "{} all elements matching in any order:",
+                if matcher_result.into() { "contains" } else { "doesn't contain" },
+            ))
+            .nested(
+                self.expected
+                    .into_iter()
+                    .map(|element| format!("{:?}", element))
+                    .collect::<Description>()
+                    .bullet_list(),
+            )
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use crate::matcher::MatcherResult;
@@ -284,4 +382,135 @@ mod tests {
             displays_as(eq("which contains the unexpected element \"C\""))
         )
     }
+
+    #[test]
+    fn ignoring_order_match() -> Result<()> {
+        verify_that!(vec!["a", "b"], container_eq(["b", "a"]).ignore_order())
+    }
+
+    #[test]
+    fn ignoring_order_mismatch() -> Result<()> {
+        verify_that!(vec!["a", "b"], not(container_eq(["1", "2"]).ignore_order()))
+    }
+
+    #[test]
+    fn ignoring_order_mismatch_explain() -> Result<()> {
+        let expected_err = verify_that!(vec!["a", "b"], container_eq(["1", "2"]).ignore_order());
+        verify_that!(
+            expected_err,
+            err(displays_as(contains_substring(indoc!(
+                r#"
+                Value of: vec!["a", "b"]
+                Expected: contains all elements matching in any order:
+                  * "1"
+                  * "2"
+                Actual: ["a", "b"],
+                  which does not have a perfect match.  The best match found was:
+                    Actual element "a" at index 0 did not match any remaining expected element.
+                    Actual element "b" at index 1 did not match any remaining expected element.
+                    Expected element "1" at index 0 did not match any remaining actual element.
+                    Expected element "2" at index 1 did not match any remaining actual element.
+                "#
+            ))))
+        )
+    }
+
+    #[test]
+    fn ignoring_order_unaccounted_extra_expected() -> Result<()> {
+        verify_that!(vec!["a", "b"], not(container_eq(["a", "b", "a"]).ignore_order()))
+    }
+
+    #[test]
+    fn ignoring_order_unaccounted_extra_expected_explain() -> Result<()> {
+        let expected_err =
+            verify_that!(vec!["a", "b"], container_eq(["a", "b", "a"]).ignore_order());
+        verify_that!(
+            expected_err,
+            err(displays_as(contains_substring(indoc!(
+                r#"
+                Value of: vec!["a", "b"]
+                Expected: contains all elements matching in any order:
+                  * "a"
+                  * "b"
+                  * "a"
+                Actual: ["a", "b"],
+                  which does not have a perfect match.  The best match found was:
+                    Actual element "a" at index 0 is equal to expected element at index 0.
+                    Actual element "b" at index 1 is equal to expected element at index 1.
+                    Expected element "a" at index 2 did not match any remaining actual element.
+                "#
+            ))))
+        )
+    }
+
+    #[test]
+    fn ignoring_order_unaccounted_extra_actual() -> Result<()> {
+        verify_that!(vec!["a", "b", "a"], not(container_eq(["b", "a"]).ignore_order()))
+    }
+
+    #[test]
+    fn ignoring_order_unaccounted_extra_actual_explain() -> Result<()> {
+        let expected_err =
+            verify_that!(vec!["a", "b", "a"], container_eq(["b", "a"]).ignore_order());
+
+        verify_that!(
+            expected_err,
+            err(displays_as(contains_substring(indoc!(
+                r#"
+                Value of: vec!["a", "b", "a"]
+                Expected: contains all elements matching in any order:
+                  * "b"
+                  * "a"
+                Actual: ["a", "b", "a"],
+                  which does not have a perfect match.  The best match found was:
+                    Actual element "a" at index 0 is equal to expected element at index 1.
+                    Actual element "b" at index 1 is equal to expected element at index 0.
+                    Actual element "a" at index 2 did not match any remaining expected element.
+                "#
+            ))))
+        )
+    }
+
+    #[test]
+    fn ignoring_order_on_sets() -> Result<()> {
+        let mut actual = std::collections::HashSet::new();
+        actual.insert("b");
+        actual.insert("a");
+        actual.insert("c");
+        verify_that!(actual, container_eq(["c", "b", "a"]).ignore_order())
+    }
+
+    #[test]
+    fn ignoring_order_on_sets_explain() -> Result<()> {
+        let mut actual = std::collections::HashSet::new();
+        actual.insert("b");
+        actual.insert("a");
+        actual.insert("c");
+        let expected_err = verify_that!(actual, container_eq(["c", "a"]).ignore_order());
+        verify_that!(
+            expected_err,
+            err(displays_as(contains_regex(indoc!(
+                r#"
+                Value of: actual
+                Expected: contains all elements matching in any order:
+                  \* "c"
+                  \* "a"
+                Actual: \{"\w", "\w", "\w"\},
+                  which does not have a perfect match.  The best match found was:
+                    Actual element "\w" at index \d is equal to expected element at index \d\.
+                    Actual element "\w" at index \d is equal to expected element at index \d\.
+                    Actual element "\w" at index \d did not match any remaining expected element\.
+                "#
+            ))))
+        )
+    }
+
+    #[test]
+    fn ignoring_order_on_number_sets() -> Result<()> {
+        let mut actual = std::collections::HashSet::new();
+        actual.insert(1);
+        actual.insert(2);
+        actual.insert(3);
+        verify_that!(actual, container_eq([3, 2, 1]).ignore_order())
+    }
 }