Parameterize Matcher::matches and Matcher::explain_match.

This allows the use of smart pointers for the actual value when invoking
`Matcher::matches` and `Matcher::explain_match`. The Protobuf
implementation namely uses a
[kind of smart pointer](https://github.com/protocolbuffers/protobuf/blob/62d5d9bf67d27d3b0084dabcf67bff2f8238162b/rust/proxied.rs#L113).
The lifetime on that smart pointer has no a priori relation to that of
the parameter `actual`, causing the borrow checker to complain whenever
invoking an inner matcher on the output of `as_view`.

This commit addresses the problem by allowing the `ViewProxy` -- rather
than a reference to it -- to be passed directly to `Matcher::matches`
and `Matcher::explain_match`. It does this by making those two methods
generic with respect to the input type. They must only implement
`Deref<Target = Self::ActualT>`.

The new test `googletest/tests/arena_test.rs` illustrates this with a
simplified example.

Introducing these generics unfortunately makes `Matcher` no longer
object-safe. Since several matchers construct trait objts on `Matcher`,
this also introduces an internal-only wrapper trait `ObjectSafeMatcher`
which every `Matcher` auto-implements.

While this makes some changes to how `Matcher` is defined and
implemented, it should have no effect on how it is _used_, other than
to fix the aforementioned problem. So it should not affect compatibility
for most users of the crate.

Fixes #323.

Author: hovinen

googletest/crate_docs.md

@@ -214,7 +214,7 @@ a struct holding the matcher's data and have it implement the trait
 
 ```no_run
 use googletest::{description::Description, matcher::{Matcher, MatcherResult}};
-use std::fmt::Debug;
+use std::{fmt::Debug, ops::Deref};
 
 struct MyEqMatcher<T> {
     expected: T,
@@ -223,7 +223,10 @@ struct MyEqMatcher<T> {
 impl<T: PartialEq + Debug> Matcher for MyEqMatcher<T> {
     type ActualT = T;
 
-    fn matches(&self, actual: &Self::ActualT) -> MatcherResult {
+    fn matches<ActualRefT: Deref<Target = Self::ActualT>>(
+        &self,
+        actual: ActualRefT,
+    ) -> MatcherResult {
         if self.expected == *actual {
             MatcherResult::Match
         } else {
@@ -248,7 +251,7 @@ impl<T: PartialEq + Debug> Matcher for MyEqMatcher<T> {
 
  ```no_run
  # use googletest::{description::Description, matcher::{Matcher, MatcherResult}};
- # use std::fmt::Debug;
+ # use std::{fmt::Debug, ops::Deref};
  #
  # struct MyEqMatcher<T> {
  #    expected: T,
@@ -257,7 +260,10 @@ impl<T: PartialEq + Debug> Matcher for MyEqMatcher<T> {
  # impl<T: PartialEq + Debug> Matcher for MyEqMatcher<T> {
  #    type ActualT = T;
  #
- #    fn matches(&self, actual: &Self::ActualT) -> MatcherResult {
+ #    fn matches<ActualRefT: Deref<Target = Self::ActualT>>(
+ #        &self,
+ #        actual: ActualRefT,
+ #    ) -> MatcherResult {
  #        if self.expected == *actual {
  #            MatcherResult::Match
  #        } else {
@@ -287,7 +293,7 @@ impl<T: PartialEq + Debug> Matcher for MyEqMatcher<T> {
 ```
 # use googletest::prelude::*;
 # use googletest::{description::Description, matcher::{Matcher, MatcherResult}};
-# use std::fmt::Debug;
+# use std::{fmt::Debug, ops::Deref};
 #
 # struct MyEqMatcher<T> {
 #    expected: T,
@@ -296,7 +302,10 @@ impl<T: PartialEq + Debug> Matcher for MyEqMatcher<T> {
 # impl<T: PartialEq + Debug> Matcher for MyEqMatcher<T> {
 #    type ActualT = T;
 #
-#    fn matches(&self, actual: &Self::ActualT) -> MatcherResult {
+#    fn matches<ActualRefT: Deref<Target = Self::ActualT>>(
+#        &self,
+#        actual: ActualRefT,
+#    ) -> MatcherResult {
 #        if self.expected == *actual {
 #            MatcherResult::Match
 #        } else {

googletest/src/matcher.rs

@@ -20,6 +20,7 @@ use crate::internal::test_outcome::TestAssertionFailure;
 use crate::matchers::__internal_unstable_do_not_depend_on_these::ConjunctionMatcher;
 use crate::matchers::__internal_unstable_do_not_depend_on_these::DisjunctionMatcher;
 use std::fmt::Debug;
+use std::ops::Deref;
 
 /// An interface for checking an arbitrary condition on a datum.
 ///
@@ -36,7 +37,10 @@ pub trait Matcher {
     /// matching condition is based on data stored in the matcher. For example,
     /// `eq` matches when its stored expected value is equal (in the sense of
     /// the `==` operator) to the value `actual`.
-    fn matches(&self, actual: &Self::ActualT) -> MatcherResult;
+    fn matches<ActualRefT: Deref<Target = Self::ActualT> + Clone>(
+        &self,
+        actual: ActualRefT,
+    ) -> MatcherResult;
 
     /// Returns a description of `self` or a negative description if
     /// `matcher_result` is `DoesNotMatch`.
@@ -137,7 +141,10 @@ pub trait Matcher {
     ///         .nested(self.expected.explain_match(actual.deref()))
     /// }
     /// ```
-    fn explain_match(&self, actual: &Self::ActualT) -> Description {
+    fn explain_match<ActualRefT: Deref<Target = Self::ActualT> + Clone>(
+        &self,
+        actual: ActualRefT,
+    ) -> Description {
         format!("which {}", self.describe(self.matches(actual))).into()
     }
 
@@ -205,6 +212,46 @@ pub trait Matcher {
     }
 }
 
+/// Functionality used by macros within this crate.
+///
+/// For internal use only. API stablility is not guaranteed!
+#[doc(hidden)]
+pub mod __internal_unstable_do_not_depend_on_these {
+    use super::{Matcher, MatcherResult};
+    use crate::description::Description;
+    use std::fmt::Debug;
+
+    /// A variant of [`Matcher`] which is object-safe.
+    ///
+    /// This is used in contexts where a `dyn Matcher` is required. It supplies all methods of
+    /// [`Matcher`] but without any generics on the methods.
+    pub trait ObjectSafeMatcher {
+        type ActualT: Debug + ?Sized;
+
+        fn obj_matches(&self, actual: &Self::ActualT) -> MatcherResult;
+
+        fn obj_describe(&self, matcher_result: MatcherResult) -> Description;
+
+        fn obj_explain_match(&self, actual: &Self::ActualT) -> Description;
+    }
+
+    impl<MatcherT: Matcher> ObjectSafeMatcher for MatcherT {
+        type ActualT = <Self as Matcher>::ActualT;
+
+        fn obj_matches(&self, actual: &Self::ActualT) -> MatcherResult {
+            Matcher::matches(self, actual)
+        }
+
+        fn obj_describe(&self, matcher_result: MatcherResult) -> Description {
+            Matcher::describe(self, matcher_result)
+        }
+
+        fn obj_explain_match(&self, actual: &Self::ActualT) -> Description {
+            Matcher::explain_match(self, actual)
+        }
+    }
+}
+
 /// Any actual value whose debug length is greater than this value will be
 /// pretty-printed. Otherwise, it will have normal debug output formatting.
 const PRETTY_PRINT_LENGTH_THRESHOLD: usize = 60;
@@ -249,7 +296,11 @@ pub enum MatcherResult {
 
 impl From<bool> for MatcherResult {
     fn from(b: bool) -> Self {
-        if b { MatcherResult::Match } else { MatcherResult::NoMatch }
+        if b {
+            MatcherResult::Match
+        } else {
+            MatcherResult::NoMatch
+        }
     }
 }
 
@@ -276,16 +327,22 @@ impl MatcherResult {
 impl<M: Matcher> Matcher for &M {
     type ActualT = M::ActualT;
 
-    fn matches(&self, actual: &Self::ActualT) -> MatcherResult {
-        (*self).matches(actual)
+    fn matches<ActualRefT: Deref<Target = Self::ActualT>>(
+        &self,
+        actual: ActualRefT,
+    ) -> MatcherResult {
+        (*self).matches(actual.deref())
     }
 
     fn describe(&self, matcher_result: MatcherResult) -> Description {
         (*self).describe(matcher_result)
     }
 
-    fn explain_match(&self, actual: &Self::ActualT) -> Description {
-        (*self).explain_match(actual)
+    fn explain_match<ActualRefT: Deref<Target = Self::ActualT>>(
+        &self,
+        actual: ActualRefT,
+    ) -> Description {
+        (*self).explain_match(actual.deref())
     }
 }
 

googletest/src/matchers/anything_matcher.rs

@@ -16,7 +16,7 @@ use crate::{
     description::Description,
     matcher::{Matcher, MatcherResult},
 };
-use std::{fmt::Debug, marker::PhantomData};
+use std::{fmt::Debug, marker::PhantomData, ops::Deref};
 
 /// Matches anything. This matcher always succeeds.
 ///
@@ -41,7 +41,7 @@ struct Anything<T: ?Sized>(PhantomData<T>);
 impl<T: Debug + ?Sized> Matcher for Anything<T> {
     type ActualT = T;
 
-    fn matches(&self, _: &T) -> MatcherResult {
+    fn matches<ActualRefT: Deref<Target = Self::ActualT>>(&self, _: ActualRefT) -> MatcherResult {
         MatcherResult::Match
     }
 

googletest/src/matchers/char_count_matcher.rs

@@ -16,7 +16,7 @@ use crate::{
     description::Description,
     matcher::{Matcher, MatcherResult},
 };
-use std::{fmt::Debug, marker::PhantomData};
+use std::{fmt::Debug, marker::PhantomData, ops::Deref};
 
 /// Matches a string whose number of Unicode scalars matches `expected`.
 ///
@@ -70,7 +70,10 @@ struct CharLenMatcher<T: ?Sized, E> {
 impl<T: Debug + ?Sized + AsRef<str>, E: Matcher<ActualT = usize>> Matcher for CharLenMatcher<T, E> {
     type ActualT = T;
 
-    fn matches(&self, actual: &T) -> MatcherResult {
+    fn matches<ActualRefT: Deref<Target = Self::ActualT>>(
+        &self,
+        actual: ActualRefT,
+    ) -> MatcherResult {
         self.expected.matches(&actual.as_ref().chars().count())
     }
 
@@ -89,7 +92,10 @@ impl<T: Debug + ?Sized + AsRef<str>, E: Matcher<ActualT = usize>> Matcher for Ch
         }
     }
 
-    fn explain_match(&self, actual: &T) -> Description {
+    fn explain_match<ActualRefT: Deref<Target = Self::ActualT>>(
+        &self,
+        actual: ActualRefT,
+    ) -> Description {
         let actual_size = actual.as_ref().chars().count();
         format!(
             "which has character count {}, {}",
@@ -109,6 +115,7 @@ mod tests {
     use indoc::indoc;
     use std::fmt::Debug;
     use std::marker::PhantomData;
+    use std::ops::Deref;
 
     #[test]
     fn char_count_matches_string_slice() -> Result<()> {
@@ -134,15 +141,21 @@ mod tests {
         impl<T: Debug> Matcher for TestMatcher<T> {
             type ActualT = T;
 
-            fn matches(&self, _: &T) -> MatcherResult {
+            fn matches<ActualRefT: Deref<Target = Self::ActualT>>(
+                &self,
+                _: ActualRefT,
+            ) -> MatcherResult {
                 false.into()
             }
 
             fn describe(&self, _: MatcherResult) -> Description {
                 "called described".into()
             }
 
-            fn explain_match(&self, _: &T) -> Description {
+            fn explain_match<ActualRefT: Deref<Target = Self::ActualT>>(
+                &self,
+                _: ActualRefT,
+            ) -> Description {
                 "called explain_match".into()
             }
         }

googletest/src/matchers/conjunction_matcher.rs

@@ -19,7 +19,7 @@ use crate::{
     description::Description,
     matcher::{Matcher, MatcherResult},
 };
-use std::fmt::Debug;
+use std::{fmt::Debug, ops::Deref};
 
 /// Matcher created by [`Matcher::and`] and [`all!`].
 ///
@@ -58,25 +58,31 @@ where
 {
     type ActualT = M1::ActualT;
 
-    fn matches(&self, actual: &M1::ActualT) -> MatcherResult {
-        match (self.m1.matches(actual), self.m2.matches(actual)) {
+    fn matches<ActualRefT: Deref<Target = Self::ActualT> + Clone>(
+        &self,
+        actual: ActualRefT,
+    ) -> MatcherResult {
+        match (self.m1.matches(actual.clone()), self.m2.matches(actual.clone())) {
             (MatcherResult::Match, MatcherResult::Match) => MatcherResult::Match,
             _ => MatcherResult::NoMatch,
         }
     }
 
-    fn explain_match(&self, actual: &M1::ActualT) -> Description {
-        match (self.m1.matches(actual), self.m2.matches(actual)) {
-            (MatcherResult::NoMatch, MatcherResult::Match) => self.m1.explain_match(actual),
-            (MatcherResult::Match, MatcherResult::NoMatch) => self.m2.explain_match(actual),
+    fn explain_match<ActualRefT: Deref<Target = Self::ActualT> + Clone>(
+        &self,
+        actual: ActualRefT,
+    ) -> Description {
+        match (self.m1.matches(actual.clone()), self.m2.matches(actual.clone())) {
+            (MatcherResult::NoMatch, MatcherResult::Match) => self.m1.explain_match(actual.clone()),
+            (MatcherResult::Match, MatcherResult::NoMatch) => self.m2.explain_match(actual.clone()),
             (_, _) => {
-                let m1_description = self.m1.explain_match(actual);
+                let m1_description = self.m1.explain_match(actual.clone());
                 if m1_description.is_conjunction_description() {
-                    m1_description.nested(self.m2.explain_match(actual))
+                    m1_description.nested(self.m2.explain_match(actual.clone()))
                 } else {
                     Description::new()
                         .bullet_list()
-                        .collect([m1_description, self.m2.explain_match(actual)])
+                        .collect([m1_description, self.m2.explain_match(actual.clone())])
                         .conjunction_description()
                 }
             }

googletest/src/matchers/container_eq_matcher.rs

@@ -16,6 +16,7 @@ use crate::description::Description;
 use crate::matcher::{Matcher, MatcherResult};
 use std::fmt::Debug;
 use std::marker::PhantomData;
+use std::ops::Deref;
 
 /// Matches a container equal (in the sense of `==`) to `expected`.
 ///
@@ -116,12 +117,22 @@ where
 {
     type ActualT = ActualContainerT;
 
-    fn matches(&self, actual: &ActualContainerT) -> MatcherResult {
+    fn matches<ActualRefT: Deref<Target = Self::ActualT>>(
+        &self,
+        actual: ActualRefT,
+    ) -> MatcherResult {
         (*actual == self.expected).into()
     }
 
-    fn explain_match(&self, actual: &ActualContainerT) -> Description {
-        build_explanation(self.get_missing_items(actual), self.get_unexpected_items(actual)).into()
+    fn explain_match<ActualRefT: Deref<Target = Self::ActualT>>(
+        &self,
+        actual: ActualRefT,
+    ) -> Description {
+        build_explanation(
+            self.get_missing_items(actual.deref()),
+            self.get_unexpected_items(actual.deref()),
+        )
+        .into()
     }
 
     fn describe(&self, matcher_result: MatcherResult) -> Description {
@@ -271,15 +282,15 @@ mod tests {
     }
 
     #[test]
-    fn container_eq_matches_owned_vec_of_owned_strings_with_slice_of_string_references()
-    -> Result<()> {
+    fn container_eq_matches_owned_vec_of_owned_strings_with_slice_of_string_references(
+    ) -> Result<()> {
         let vector = vec!["A string".to_string(), "Another string".to_string()];
         verify_that!(vector, container_eq(["A string", "Another string"]))
     }
 
     #[test]
-    fn container_eq_matches_owned_vec_of_owned_strings_with_shorter_slice_of_string_references()
-    -> Result<()> {
+    fn container_eq_matches_owned_vec_of_owned_strings_with_shorter_slice_of_string_references(
+    ) -> Result<()> {
         let actual = vec!["A string".to_string(), "Another string".to_string()];
         let matcher = container_eq(["A string"]);