Remove the need for allocation from is_utf8_string.

Previously, `IsEncodedStringMatcher` converted its actual value input to
a `Vec` and constructed a `String` out of that in order to match it.
This is because using a string slice caused problems with the borrow
checker as described in #323.

The fundamental problem is that the type against which the inner matcher
is matching is a reference whose lifetime must be named in the trait
bound:

```
impl<ActualT: AsRef<[u8]> + Debug, InnerMatcherT> Matcher
    for IsEncodedStringMatcher<ActualT, InnerMatcherT>
where
    InnerMatcherT: Matcher<ActualT = &'what str>,
                                       ^^^^ What goes here???
```

One option is just to remove the reference:

```
impl<ActualT: AsRef<[u8]> + Debug, InnerMatcherT> Matcher
    for IsEncodedStringMatcher<ActualT, InnerMatcherT>
where
    InnerMatcherT: Matcher<ActualT = str>,
```

This doesn't work when the inner matcher is `eq`, since one would then
be comparing an `str` and a string slice:

```
verify_that!("A string".as_bytes(), is_utf8_string(eq("A string"))) // Compile error: cannot compare str and &str
```

However, this problem does not occur with `StrMatcher`:

```
verify_that!("A string".as_bytes(), is_utf8_string(constains_substring("A string"))) // Passes
```

So this also introduces an easy way to obtain a `StrMatcher` to check
string equality:

```
verify_that!("A string".as_bytes(), is_utf8_string(eq_str("A string"))) // Passes
```

This is slightly inconvenient, since one must use a different matcher
to compare string equality in this case. But it is well-documented and
not too inconvenient to use. So it should be okay.

Author: hovinen

googletest/crate_docs.md

@@ -127,13 +127,15 @@ The following matchers are provided in GoogleTest Rust:
 | [`ends_with`]        | A string ending with the given suffix.                                   |
 | [`eq`]               | A value equal to the argument, in the sense of the [`PartialEq`] trait.  |
 | [`eq_deref_of`]      | A value equal to the dereferenced value of the argument.                 |
+| [`eq_str`]           | A string equal to the argument.                                          |
 | [`err`]              | A [`Result`][std::result::Result] containing an `Err` variant the argument matches. |
 | [`field!`]           | A struct or enum with a given field whose value the argument matches.    |
 | [`ge`]               | A [`PartialOrd`] value greater than or equal to the given value.         |
 | [`gt`]               | A [`PartialOrd`] value strictly greater than the given value.            |
 | [`has_entry`]        | A [`HashMap`] containing a given key whose value the argument matches.   |
 | [`is_contained_in!`] | A container each of whose elements is matched by some given matcher.     |
 | [`is_nan`]           | A floating point number which is NaN.                                    |
+| [`is_utf8_string`]   | A byte sequence representing a UTF-8 encoded string which the argument matches. |
 | [`le`]               | A [`PartialOrd`] value less than or equal to the given value.            |
 | [`len`]              | A container whose number of elements the argument matches.               |
 | [`lt`]               | A [`PartialOrd`] value strictly less than the given value.               |
@@ -169,6 +171,7 @@ The following matchers are provided in GoogleTest Rust:
 [`empty`]: matchers::empty
 [`ends_with`]: matchers::ends_with
 [`eq`]: matchers::eq
+[`eq_str`]: matchers::eq_str
 [`eq_deref_of`]: matchers::eq_deref_of
 [`err`]: matchers::err
 [`field!`]: matchers::field
@@ -177,6 +180,7 @@ The following matchers are provided in GoogleTest Rust:
 [`has_entry`]: matchers::has_entry
 [`is_contained_in!`]: matchers::is_contained_in
 [`is_nan`]: matchers::is_nan
+[`is_utf8_string`]: matchers::is_utf8_string
 [`le`]: matchers::le
 [`len`]: matchers::len
 [`lt`]: matchers::lt

googletest/src/matchers/is_encoded_string_matcher.rs

@@ -25,18 +25,21 @@ use std::{fmt::Debug, marker::PhantomData};
 ///
 /// The input may be a slice `&[u8]` or a `Vec` of bytes.
 ///
+/// When asserting the equality of the actual value with a given string, use
+/// [`eq_str`] rather than [`eq`].
+///
 /// ```
 /// # use googletest::prelude::*;
 /// # fn should_pass() -> Result<()> {
 /// let bytes: &[u8] = "A string".as_bytes();
-/// verify_that!(bytes, is_utf8_string(eq("A string")))?; // Passes
+/// verify_that!(bytes, is_utf8_string(eq_str("A string")))?; // Passes
 /// let bytes: Vec<u8> = "A string".as_bytes().to_vec();
-/// verify_that!(bytes, is_utf8_string(eq("A string")))?; // Passes
+/// verify_that!(bytes, is_utf8_string(eq_str("A string")))?; // Passes
 /// #     Ok(())
 /// # }
 /// # fn should_fail_1() -> Result<()> {
 /// # let bytes: &[u8] = "A string".as_bytes();
-/// verify_that!(bytes, is_utf8_string(eq("Another string")))?; // Fails (inner matcher does not match)
+/// verify_that!(bytes, is_utf8_string(eq_str("Another string")))?; // Fails (inner matcher does not match)
 /// #     Ok(())
 /// # }
 /// # fn should_fail_2() -> Result<()> {
@@ -48,11 +51,14 @@ use std::{fmt::Debug, marker::PhantomData};
 /// # should_fail_1().unwrap_err();
 /// # should_fail_2().unwrap_err();
 /// ```
-pub fn is_utf8_string<'a, ActualT: AsRef<[u8]> + Debug + 'a, InnerMatcherT>(
+///
+/// [`eq`]: crate::matchers::eq
+/// [`eq_str`]: crate::matchers::eq_str
+pub fn is_utf8_string<ActualT: AsRef<[u8]> + Debug, InnerMatcherT>(
     inner: InnerMatcherT,
 ) -> impl Matcher<ActualT = ActualT>
 where
-    InnerMatcherT: Matcher<ActualT = String>,
+    InnerMatcherT: Matcher<ActualT = str>,
 {
     IsEncodedStringMatcher { inner, phantom: Default::default() }
 }
@@ -62,15 +68,15 @@ struct IsEncodedStringMatcher<ActualT, InnerMatcherT> {
     phantom: PhantomData<ActualT>,
 }
 
-impl<'a, ActualT: AsRef<[u8]> + Debug + 'a, InnerMatcherT> Matcher
+impl<ActualT: AsRef<[u8]> + Debug, InnerMatcherT> Matcher
     for IsEncodedStringMatcher<ActualT, InnerMatcherT>
 where
-    InnerMatcherT: Matcher<ActualT = String>,
+    InnerMatcherT: Matcher<ActualT = str>,
 {
     type ActualT = ActualT;
 
     fn matches(&self, actual: &Self::ActualT) -> MatcherResult {
-        String::from_utf8(actual.as_ref().to_vec())
+        std::str::from_utf8(actual.as_ref())
             .map(|s| self.inner.matches(&s))
             .unwrap_or(MatcherResult::NoMatch)
     }
@@ -91,7 +97,7 @@ where
     }
 
     fn explain_match(&self, actual: &Self::ActualT) -> Description {
-        match String::from_utf8(actual.as_ref().to_vec()) {
+        match std::str::from_utf8(actual.as_ref()) {
             Ok(s) => {
                 format!("which is a UTF-8 encoded string {}", self.inner.explain_match(&s)).into()
             }
@@ -107,70 +113,70 @@ mod tests {
 
     #[test]
     fn matches_string_as_byte_slice() -> Result<()> {
-        verify_that!("A string".as_bytes(), is_utf8_string(eq("A string")))
+        verify_that!("A string".as_bytes(), is_utf8_string(eq_str("A string")))
     }
 
     #[test]
     fn matches_string_as_byte_vec() -> Result<()> {
-        verify_that!("A string".as_bytes().to_vec(), is_utf8_string(eq("A string")))
+        verify_that!("A string".as_bytes().to_vec(), is_utf8_string(eq_str("A string")))
     }
 
     #[test]
     fn matches_string_with_utf_8_encoded_sequences() -> Result<()> {
-        verify_that!("äöüÄÖÜ".as_bytes().to_vec(), is_utf8_string(eq("äöüÄÖÜ")))
+        verify_that!("äöüÄÖÜ".as_bytes().to_vec(), is_utf8_string(eq_str("äöüÄÖÜ")))
     }
 
     #[test]
     fn does_not_match_non_equal_string() -> Result<()> {
-        verify_that!("äöüÄÖÜ".as_bytes().to_vec(), not(is_utf8_string(eq("A string"))))
+        verify_that!("äöüÄÖÜ".as_bytes().to_vec(), not(is_utf8_string(eq_str("A string"))))
     }
 
     #[test]
     fn does_not_match_non_utf_8_encoded_byte_sequence() -> Result<()> {
-        verify_that!(&[192, 64, 255, 32], not(is_utf8_string(eq("A string"))))
+        verify_that!(&[192, 64, 255, 32], not(is_utf8_string(eq_str("A string"))))
     }
 
     #[test]
     fn has_correct_description_in_matched_case() -> Result<()> {
-        let matcher = is_utf8_string::<&[u8], _>(eq("A string"));
+        let matcher = is_utf8_string::<&[u8], _>(eq_str("A string"));
 
         verify_that!(
             matcher.describe(MatcherResult::Match),
-            displays_as(eq("is a UTF-8 encoded string which is equal to \"A string\""))
+            displays_as(eq_str("is a UTF-8 encoded string which is equal to \"A string\""))
         )
     }
 
     #[test]
     fn has_correct_description_in_not_matched_case() -> Result<()> {
-        let matcher = is_utf8_string::<&[u8], _>(eq("A string"));
+        let matcher = is_utf8_string::<&[u8], _>(eq_str("A string"));
 
         verify_that!(
             matcher.describe(MatcherResult::NoMatch),
-            displays_as(eq("is not a UTF-8 encoded string which is equal to \"A string\""))
+            displays_as(eq_str("is not a UTF-8 encoded string which is equal to \"A string\""))
         )
     }
 
     #[test]
     fn has_correct_explanation_in_matched_case() -> Result<()> {
-        let explanation = is_utf8_string(eq("A string")).explain_match(&"A string".as_bytes());
+        let explanation = is_utf8_string(eq_str("A string")).explain_match(&"A string".as_bytes());
 
         verify_that!(
             explanation,
-            displays_as(eq("which is a UTF-8 encoded string which is equal to \"A string\""))
+            displays_as(eq_str("which is a UTF-8 encoded string which is equal to \"A string\""))
         )
     }
 
     #[test]
     fn has_correct_explanation_when_byte_array_is_not_utf8_encoded() -> Result<()> {
-        let explanation = is_utf8_string(eq("A string")).explain_match(&&[192, 128, 0, 64]);
+        let explanation = is_utf8_string(eq_str("A string")).explain_match(&&[192, 128, 0, 64]);
 
         verify_that!(explanation, displays_as(starts_with("which is not a UTF-8 encoded string: ")))
     }
 
     #[test]
     fn has_correct_explanation_when_inner_matcher_does_not_match() -> Result<()> {
         let explanation =
-            is_utf8_string(eq("A string")).explain_match(&"Another string".as_bytes());
+            is_utf8_string(eq_str("A string")).explain_match(&"Another string".as_bytes());
 
         verify_that!(
             explanation,

googletest/src/matchers/mod.rs

@@ -85,7 +85,7 @@ pub use points_to_matcher::points_to;
 pub use predicate_matcher::{predicate, PredicateMatcher};
 pub use some_matcher::some;
 pub use str_matcher::{
-    contains_substring, ends_with, starts_with, StrMatcher, StrMatcherConfigurator,
+    contains_substring, ends_with, eq_str, starts_with, StrMatcher, StrMatcherConfigurator,
 };
 pub use subset_of_matcher::subset_of;
 pub use superset_of_matcher::superset_of;

googletest/src/matchers/str_matcher.rs

@@ -26,6 +26,43 @@ use std::fmt::Debug;
 use std::marker::PhantomData;
 use std::ops::Deref;
 
+/// Matches a string equal to the given string.
+///
+/// This has the same effect as [`eq`]. Unlike [`eq`], [`eq_str`] can be used
+/// in cases where the actual type being matched is `str`. In paticular, one
+/// can use [`eq_str`] together with [`is_utf8_string`].
+///
+/// ```
+/// # use googletest::prelude::*;
+/// # fn should_pass_1() -> Result<()> {
+/// verify_that!("Some value", eq_str("Some value"))?;  // Passes
+/// verify_that!("Some value".to_string(), eq_str("Some value"))?;  // Passes
+/// #     Ok(())
+/// # }
+/// # fn should_fail() -> Result<()> {
+/// verify_that!("Another value", eq_str("Some value"))?;   // Fails
+/// #     Ok(())
+/// # }
+/// # fn should_pass_2() -> Result<()> {
+/// let value_as_bytes = "Some value".as_bytes();
+/// verify_that!(value_as_bytes, is_utf8_string(eq_str("Some value")))?;   // Passes
+/// #     Ok(())
+/// # }
+/// # should_pass_1().unwrap();
+/// # should_fail().unwrap_err();
+/// # should_pass_2().unwrap();
+/// ```
+///
+/// [`eq`]: crate::matchers::eq
+/// [`is_utf8_string`]: crate::matchers::is_utf8_string
+pub fn eq_str<A: ?Sized, T>(expected: T) -> StrMatcher<A, T> {
+    StrMatcher {
+        configuration: Configuration { mode: MatchMode::Equals, ..Default::default() },
+        expected,
+        phantom: Default::default(),
+    }
+}
+
 /// Matches a string containing a given substring.
 ///
 /// Both the actual value and the expected substring may be either a `String` or