Add to StrMatcher support for matching a string containing a substring a given number of times.

This is analogous to the `times` method of the `contains` matcher. The tester can now assert, for example, that a given substring appears exactly once and no more. Previously, it was only possible to assert that it appears at least once.

This works in a manor analogous to `times` in `contains`: it adds a field of type `Option<Box<dyn Matcher<usize>>>` to the configuration. If that field is None, then the behaviour is as before. If it is filled, then the matcher is respected and output in the description and match explanation. The use of a trait object avoids having to add more generics to `StrMatcher` just to support this one case, while the use of an `Option` ensures that the description and match explanation aren't affected when the test doesn't specify anything.

PiperOrigin-RevId: 517418605

Author: hovinenb

googletest/src/matchers/str_matcher.rs

@@ -18,6 +18,7 @@ use eq_matcher::EqMatcher;
 use googletest::matcher::{Matcher, MatcherResult};
 #[cfg(not(google3))]
 use googletest::matchers::eq_matcher;
+use std::borrow::Cow;
 use std::fmt::Debug;
 use std::ops::Deref;
 
@@ -88,7 +89,7 @@ pub fn ends_with<T>(expected: T) -> StrMatcher<T> {
 /// Matchers which match against string values and, through configuration,
 /// specialise to [StrMatcher] implement this trait. Currently that only
 /// includes [EqMatcher] and [StrMatcher].
-pub trait StrMatcherConfigurator<T> {
+pub trait StrMatcherConfigurator<ExpectedT> {
     /// Configures the matcher to ignore any leading whitespace in either the
     /// actual or the expected value.
     ///
@@ -104,7 +105,7 @@ pub trait StrMatcherConfigurator<T> {
     /// actual value.
     ///
     /// [`str::trim_start`]: https://doc.rust-lang.org/std/primitive.str.html#method.trim_start
-    fn ignoring_leading_whitespace(self) -> StrMatcher<T>;
+    fn ignoring_leading_whitespace(self) -> StrMatcher<ExpectedT>;
 
     /// Configures the matcher to ignore any trailing whitespace in either the
     /// actual or the expected value.
@@ -121,7 +122,7 @@ pub trait StrMatcherConfigurator<T> {
     /// actual value.
     ///
     /// [`str::trim_end`]: https://doc.rust-lang.org/std/primitive.str.html#method.trim_end
-    fn ignoring_trailing_whitespace(self) -> StrMatcher<T>;
+    fn ignoring_trailing_whitespace(self) -> StrMatcher<ExpectedT>;
 
     /// Configures the matcher to ignore both leading and trailing whitespace in
     /// either the actual or the expected value.
@@ -142,7 +143,7 @@ pub trait StrMatcherConfigurator<T> {
     /// value.
     ///
     /// [`str::trim`]: https://doc.rust-lang.org/std/primitive.str.html#method.trim
-    fn ignoring_outer_whitespace(self) -> StrMatcher<T>;
+    fn ignoring_outer_whitespace(self) -> StrMatcher<ExpectedT>;
 
     /// Configures the matcher to ignore ASCII case when comparing values.
     ///
@@ -157,7 +158,28 @@ pub trait StrMatcherConfigurator<T> {
     /// case characters outside of the codepoints 0-127 covered by ASCII.
     ///
     /// [`str::eq_ignore_ascii_case`]: https://doc.rust-lang.org/std/primitive.str.html#method.eq_ignore_ascii_case
-    fn ignoring_ascii_case(self) -> StrMatcher<T>;
+    fn ignoring_ascii_case(self) -> StrMatcher<ExpectedT>;
+
+    /// Configures the matcher to match only strings which otherwise satisfy the
+    /// conditions a number times matched by the matcher `times`.
+    ///
+    /// ```
+    /// verify_that!("Some value\nSome value", contains_substring("value").times(eq(2)))?; // Passes
+    /// verify_that!("Some value", contains_substring("value").times(eq(2)))?; // Fails
+    /// ```
+    ///
+    /// The matched substrings must be disjoint from one another to be counted.
+    /// For example:
+    ///
+    /// ```
+    /// // Fails: substrings distinct but not disjoint!
+    /// verify_that!("ababab", contains_substring("abab").times(eq(2)))?;
+    /// ```
+    ///
+    /// This is only meaningful when the matcher was constructed with
+    /// [`contains_substring`]. This method will panic when it is used with any
+    /// other matcher construction.
+    fn times(self, times: impl Matcher<usize> + 'static) -> StrMatcher<ExpectedT>;
 }
 
 /// A matcher which matches equality or containment of a string-like value in a
@@ -169,8 +191,8 @@ pub trait StrMatcherConfigurator<T> {
 ///  * [`contains_substring`],
 ///  * [`starts_with`],
 ///  * [`ends_with`].
-pub struct StrMatcher<T> {
-    expected: T,
+pub struct StrMatcher<ExpectedT> {
+    expected: ExpectedT,
     configuration: Configuration,
 }
 
@@ -192,32 +214,42 @@ where
     }
 }
 
-impl<T, MatcherT: Into<StrMatcher<T>>> StrMatcherConfigurator<T> for MatcherT {
-    fn ignoring_leading_whitespace(self) -> StrMatcher<T> {
+impl<ExpectedT, MatcherT: Into<StrMatcher<ExpectedT>>> StrMatcherConfigurator<ExpectedT>
+    for MatcherT
+{
+    fn ignoring_leading_whitespace(self) -> StrMatcher<ExpectedT> {
         let existing = self.into();
         StrMatcher {
             configuration: existing.configuration.ignoring_leading_whitespace(),
             ..existing
         }
     }
 
-    fn ignoring_trailing_whitespace(self) -> StrMatcher<T> {
+    fn ignoring_trailing_whitespace(self) -> StrMatcher<ExpectedT> {
         let existing = self.into();
         StrMatcher {
             configuration: existing.configuration.ignoring_trailing_whitespace(),
             ..existing
         }
     }
 
-    fn ignoring_outer_whitespace(self) -> StrMatcher<T> {
+    fn ignoring_outer_whitespace(self) -> StrMatcher<ExpectedT> {
         let existing = self.into();
         StrMatcher { configuration: existing.configuration.ignoring_outer_whitespace(), ..existing }
     }
 
-    fn ignoring_ascii_case(self) -> StrMatcher<T> {
+    fn ignoring_ascii_case(self) -> StrMatcher<ExpectedT> {
         let existing = self.into();
         StrMatcher { configuration: existing.configuration.ignoring_ascii_case(), ..existing }
     }
+
+    fn times(self, times: impl Matcher<usize> + 'static) -> StrMatcher<ExpectedT> {
+        let existing = self.into();
+        if !matches!(existing.configuration.mode, MatchMode::Contains) {
+            panic!("The times() configurator is only meaningful with contains_substring().");
+        }
+        StrMatcher { configuration: existing.configuration.times(times), ..existing }
+    }
 }
 
 impl<T: Deref<Target = str>> From<EqMatcher<T>> for StrMatcher<T> {
@@ -242,12 +274,13 @@ impl<T> StrMatcher<T> {
 // parameterised, saving compilation time and binary size on monomorphisation.
 //
 // The default value represents exact equality of the strings.
-#[derive(Default, Clone)]
+#[derive(Default)]
 struct Configuration {
     mode: MatchMode,
     ignore_leading_whitespace: bool,
     ignore_trailing_whitespace: bool,
     case_policy: CasePolicy,
+    times: Option<Box<dyn Matcher<usize>>>,
 }
 
 #[derive(Default, Clone)]
@@ -283,10 +316,11 @@ impl Configuration {
                 CasePolicy::IgnoreAscii => expected.eq_ignore_ascii_case(actual),
             },
             MatchMode::Contains => match self.case_policy {
-                CasePolicy::Respect => actual.contains(expected),
-                CasePolicy::IgnoreAscii => {
-                    actual.to_ascii_lowercase().contains(&expected.to_ascii_lowercase())
-                }
+                CasePolicy::Respect => self.does_containment_match(actual, expected),
+                CasePolicy::IgnoreAscii => self.does_containment_match(
+                    actual.to_ascii_lowercase().as_str(),
+                    expected.to_ascii_lowercase().as_str(),
+                ),
             },
             MatchMode::StartsWith => match self.case_policy {
                 CasePolicy::Respect => actual.starts_with(expected),
@@ -304,18 +338,35 @@ impl Configuration {
             },
         }
     }
+
+    // Returns whether actual contains expected a number of times matched by the
+    // matcher self.times. Does not take other configuration into account.
+    fn does_containment_match(&self, actual: &str, expected: &str) -> bool {
+        if let Some(times) = self.times.as_ref() {
+            // Split returns an iterator over the "boundaries" left and right of the
+            // substring to be matched, of which there is one more than the number of
+            // substrings.
+            matches!(times.matches(&(actual.split(expected).count() - 1)), MatcherResult::Matches)
+        } else {
+            actual.contains(expected)
+        }
+    }
+
     // StrMatcher::describe redirects immediately to this function.
     fn describe(&self, matcher_result: MatcherResult, expected: &str) -> String {
-        let mut addenda = Vec::with_capacity(3);
+        let mut addenda: Vec<Cow<'static, str>> = Vec::with_capacity(3);
         match (self.ignore_leading_whitespace, self.ignore_trailing_whitespace) {
-            (true, true) => addenda.push("ignoring leading and trailing whitespace"),
-            (true, false) => addenda.push("ignoring leading whitespace"),
-            (false, true) => addenda.push("ignoring trailing whitespace"),
+            (true, true) => addenda.push("ignoring leading and trailing whitespace".into()),
+            (true, false) => addenda.push("ignoring leading whitespace".into()),
+            (false, true) => addenda.push("ignoring trailing whitespace".into()),
             (false, false) => {}
         }
         match self.case_policy {
             CasePolicy::Respect => {}
-            CasePolicy::IgnoreAscii => addenda.push("ignoring ASCII case"),
+            CasePolicy::IgnoreAscii => addenda.push("ignoring ASCII case".into()),
+        }
+        if let Some(times) = self.times.as_ref() {
+            addenda.push(format!("count {}", times.describe(matcher_result)).into());
         }
         let extra =
             if !addenda.is_empty() { format!(" ({})", addenda.join(", ")) } else { "".into() };
@@ -355,6 +406,10 @@ impl Configuration {
     fn ignoring_ascii_case(self) -> Self {
         Self { case_policy: CasePolicy::IgnoreAscii, ..self }
     }
+
+    fn times(self, times: impl Matcher<usize> + 'static) -> Self {
+        Self { times: Some(Box::new(times)), ..self }
+    }
 }
 
 #[cfg(test)]
@@ -365,7 +420,7 @@ mod tests {
     #[cfg(not(google3))]
     use googletest::matchers;
     use googletest::{google_test, verify_that, Result};
-    use matchers::{eq, not};
+    use matchers::{eq, gt, not};
 
     #[google_test]
     fn matches_string_reference_with_equal_string_reference() -> Result<()> {
@@ -496,6 +551,21 @@ mod tests {
         verify_that!("Some string", contains_substring("STR").ignoring_ascii_case())
     }
 
+    #[google_test]
+    fn contains_substring_matches_correct_number_of_substrings() -> Result<()> {
+        verify_that!("Some string", contains_substring("str").times(eq(1)))
+    }
+
+    #[google_test]
+    fn contains_substring_does_not_match_incorrect_number_of_substrings() -> Result<()> {
+        verify_that!("Some string\nSome string", not(contains_substring("string").times(eq(1))))
+    }
+
+    #[google_test]
+    fn contains_substring_does_not_match_when_substrings_overlap() -> Result<()> {
+        verify_that!("ababab", not(contains_substring("abab").times(eq(2))))
+    }
+
     #[google_test]
     fn starts_with_matches_string_reference_with_prefix() -> Result<()> {
         verify_that!("Some value", starts_with("Some"))
@@ -650,6 +720,15 @@ mod tests {
         )
     }
 
+    #[google_test]
+    fn describes_itself_with_count_number() -> Result<()> {
+        let matcher = contains_substring("A string").times(gt(2));
+        verify_that!(
+            Matcher::<&str>::describe(&matcher, MatcherResult::Matches),
+            eq("contains a substring \"A string\" (count is greater than 2)")
+        )
+    }
+
     #[google_test]
     fn describes_itself_for_matching_result_in_starts_with_mode() -> Result<()> {
         let matcher = starts_with("A string");