Introduce a matcher eq_deref_of.

This is similar to `eq` but accepts a reference to the expected value rather than consuming it. This is useful in cases where one wants to check equality, has only a reference to the expected value, and either:
 * the expected value is neither Copy nor Clone, or
 * cloning the expected value is perceived to be too expensive.

This change also refactors the implementation of `explain_match` in `EqMatcher` to allow it to be reused by `EqDerefOfMatcher`.

PiperOrigin-RevId: 529731930

Author: hovinenb

googletest/src/matchers/eq_deref_of_matcher.rs

@@ -0,0 +1,149 @@
+// Copyright 2023 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use crate::matcher::{MatchExplanation, Matcher, MatcherResult};
+use crate::matchers::eq_matcher::create_diff;
+use std::{fmt::Debug, marker::PhantomData, ops::Deref};
+
+/// Matches a value equal (in the sense of `==`) to the dereferenced value of
+/// `expected`.
+///
+/// This is similar to [`eq`][crate::matchers::eq] but takes a reference or
+/// smart pointer to the expected value rather than consuming it. This is useful
+/// when:
+///
+///  * one has only a reference to the expected value, and
+///  * the expected value cannot or should not be copied or cloned to create an
+///    owned value from it.
+///
+/// ```
+/// # use googletest::{matchers::eq_deref_of, verify_that};
+/// #[derive(Debug, PartialEq)]
+/// struct NonCloneableStruct(i32);
+/// let expected = NonCloneableStruct(123);
+/// verify_that!(NonCloneableStruct(123), eq_deref_of(&expected))
+/// #    .unwrap()
+/// ```
+///
+/// **Note**: while one can use `eq_deref_of` with the configuration methods of
+/// [`StrMatcherConfigurator`][crate::matchers::str_matcher::StrMatcherConfigurator]
+/// to configure string equality, it is not possible to do so when the input is
+/// a smart pointer to a string.
+///
+/// ```compile_fail
+/// # use googletest::{matchers::{eq_deref_of, str_matcher::StrMatcherConfigurator}, verify_that};
+/// verify_that!("A string", eq_deref_of(Box::new("A STRING")).ignoring_ascii_case()) // Does not compile
+/// #    .unwrap()
+/// ```
+///
+/// Otherwise, this has the same behaviour as [`eq`][crate::matchers::eq].
+pub fn eq_deref_of<ActualT: ?Sized, ExpectedRefT>(
+    expected: ExpectedRefT,
+) -> EqDerefOfMatcher<ActualT, ExpectedRefT> {
+    EqDerefOfMatcher { expected, phantom: Default::default() }
+}
+
+/// A matcher which matches a value equal to the derefenced value of `expected`.
+///
+/// See [`eq_deref_of`].
+pub struct EqDerefOfMatcher<ActualT: ?Sized, ExpectedRefT> {
+    pub(crate) expected: ExpectedRefT,
+    phantom: PhantomData<ActualT>,
+}
+
+impl<ActualT, ExpectedRefT, ExpectedT> Matcher for EqDerefOfMatcher<ActualT, ExpectedRefT>
+where
+    ActualT: Debug + ?Sized,
+    ExpectedRefT: Deref<Target = ExpectedT> + Debug,
+    ExpectedT: PartialEq<ActualT> + Debug,
+{
+    type ActualT = ActualT;
+
+    fn matches(&self, actual: &ActualT) -> MatcherResult {
+        (self.expected.deref() == actual).into()
+    }
+
+    fn describe(&self, matcher_result: MatcherResult) -> String {
+        match matcher_result {
+            MatcherResult::Matches => format!("is equal to {:?}", self.expected),
+            MatcherResult::DoesNotMatch => format!("isn't equal to {:?}", self.expected),
+        }
+    }
+
+    fn explain_match(&self, actual: &ActualT) -> MatchExplanation {
+        create_diff(
+            &format!("{:#?}", self.expected.deref()),
+            &format!("{:#?}", actual),
+            &self.describe(self.matches(actual)),
+        )
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::eq_deref_of;
+    use crate::prelude::*;
+    use indoc::indoc;
+
+    #[derive(Debug, PartialEq)]
+    struct NonCloneNonCopyStruct(i32);
+
+    #[test]
+    fn matches_value_with_ref_to_equal_value() -> Result<()> {
+        verify_that!(NonCloneNonCopyStruct(123), eq_deref_of(&NonCloneNonCopyStruct(123)))
+    }
+
+    #[test]
+    fn matches_value_with_box_of_equal_value() -> Result<()> {
+        verify_that!(NonCloneNonCopyStruct(123), eq_deref_of(Box::new(NonCloneNonCopyStruct(123))))
+    }
+
+    #[test]
+    fn does_not_match_value_with_non_equal_value() -> Result<()> {
+        verify_that!(NonCloneNonCopyStruct(123), not(eq_deref_of(&NonCloneNonCopyStruct(234))))
+    }
+
+    #[test]
+    fn shows_structured_diff() -> Result<()> {
+        #[derive(Debug, PartialEq)]
+        struct Strukt {
+            int: i32,
+            string: String,
+        }
+
+        let result = verify_that!(
+            Strukt { int: 123, string: "something".into() },
+            eq_deref_of(Box::new(Strukt { int: 321, string: "someone".into() }))
+        );
+        verify_that!(
+            result,
+            err(displays_as(contains_substring(indoc! {
+            r#"
+            Value of: Strukt { int: 123, string: "something".into() }
+            Expected: is equal to Strukt { int: 321, string: "someone" }
+            Actual: Strukt {
+                int: 123,
+                string: "something",
+            }, which isn't equal to Strukt { int: 321, string: "someone" }
+            Debug diff:
+             Strukt {
+            +    int: 123,
+            -    int: 321,
+            +    string: "something",
+            -    string: "someone",
+             }
+            "#})))
+        )
+    }
+}

googletest/src/matchers/eq_matcher.rs

@@ -95,31 +95,36 @@ impl<A: Debug + ?Sized, T: PartialEq<A> + Debug> Matcher for EqMatcher<A, T> {
     }
 
     fn explain_match(&self, actual: &A) -> MatchExplanation {
-        let actual_debug = format!("{:#?}", actual);
-        if actual_debug.lines().count() < 2 {
-            // If the actual debug is only one line, then there is no point in doing a
-            // line-by-line diff.
-            return MatchExplanation::create(format!(
-                "which {}",
-                self.describe(self.matches(actual))
-            ));
-        }
-        let expected_debug = format!("{:#?}", self.expected);
-        let edit_list = edit_distance::edit_list(actual_debug.lines(), expected_debug.lines());
+        create_diff(
+            &format!("{:#?}", self.expected),
+            &format!("{:#?}", actual),
+            &self.describe(self.matches(actual)),
+        )
+    }
+}
 
-        if edit_list.is_empty() {
-            return MatchExplanation::create(format!(
-                "which {}\nNo difference found between debug strings.",
-                self.describe(self.matches(actual))
-            ));
-        }
+pub(super) fn create_diff(
+    expected_debug: &str,
+    actual_debug: &str,
+    description: &str,
+) -> MatchExplanation {
+    if actual_debug.lines().count() < 2 {
+        // If the actual debug is only one line, then there is no point in doing a
+        // line-by-line diff.
+        return MatchExplanation::create(format!("which {description}",));
+    }
+    let edit_list = edit_distance::edit_list(actual_debug.lines(), expected_debug.lines());
 
-        MatchExplanation::create(format!(
-            "which {}\nDebug diff:{}",
-            self.describe(self.matches(actual)),
-            edit_list_summary(&edit_list)
-        ))
+    if edit_list.is_empty() {
+        return MatchExplanation::create(format!(
+            "which {description}\nNo difference found between debug strings.",
+        ));
     }
+
+    MatchExplanation::create(format!(
+        "which {description}\nDebug diff:{}",
+        edit_list_summary(&edit_list)
+    ))
 }
 
 fn edit_list_summary(edit_list: &[edit_distance::Edit<&str>]) -> String {

googletest/src/matchers/mod.rs

@@ -23,6 +23,7 @@ pub mod display_matcher;
 pub mod each_matcher;
 pub mod elements_are_matcher;
 pub mod empty_matcher;
+pub mod eq_deref_of_matcher;
 pub mod eq_matcher;
 pub mod err_matcher;
 pub mod field_matcher;
@@ -59,6 +60,7 @@ pub use disjunction_matcher::OrMatcherExt;
 pub use display_matcher::displays_as;
 pub use each_matcher::each;
 pub use empty_matcher::empty;
+pub use eq_deref_of_matcher::eq_deref_of;
 pub use eq_matcher::eq;
 pub use err_matcher::err;
 pub use ge_matcher::ge;

googletest/src/matchers/str_matcher.rs

@@ -13,8 +13,7 @@
 // limitations under the License.
 
 use crate::matcher::{Matcher, MatcherResult};
-use crate::matchers::eq_matcher;
-use eq_matcher::EqMatcher;
+use crate::matchers::{eq_deref_of_matcher::EqDerefOfMatcher, eq_matcher::EqMatcher};
 use std::borrow::Cow;
 use std::fmt::Debug;
 use std::marker::PhantomData;
@@ -350,6 +349,12 @@ impl<A: ?Sized, T: Deref<Target = str>> From<EqMatcher<A, T>> for StrMatcher<A,
     }
 }
 
+impl<A: ?Sized, T: Deref<Target = str>> From<EqDerefOfMatcher<A, T>> for StrMatcher<A, T> {
+    fn from(value: EqDerefOfMatcher<A, T>) -> Self {
+        Self::with_default_config(value.expected)
+    }
+}
+
 impl<A: ?Sized, T> StrMatcher<A, T> {
     /// Returns a [`StrMatcher`] with a default configuration to match against
     /// the given expected value.
@@ -627,6 +632,16 @@ mod tests {
         verify_that!("A string", eq("A STRING").ignoring_ascii_case())
     }
 
+    #[test]
+    fn allows_ignoring_ascii_case_from_eq_deref_of_str_slice() -> Result<()> {
+        verify_that!("A string", eq_deref_of("A STRING").ignoring_ascii_case())
+    }
+
+    #[test]
+    fn allows_ignoring_ascii_case_from_eq_deref_of_owned_string() -> Result<()> {
+        verify_that!("A string", eq_deref_of("A STRING".to_string()).ignoring_ascii_case())
+    }
+
     #[test]
     fn matches_string_containing_expected_value_in_contains_mode() -> Result<()> {
         verify_that!("Some string", contains_substring("str"))