Update to current gtest/gmock.

testing/gmock/test/gmock-matchers_test.cc

 // Copyright 2007, Google Inc.
 // All rights reserved.
 //
 // Redistribution and use in source and binary forms, with or without
 // modification, are permitted provided that the following conditions are
 // met:
 //
 //     * Redistributions of source code must retain the above copyright
 // notice, this list of conditions and the following disclaimer.
 //     * Redistributions in binary form must reproduce the above
@@ skipping 19 matching lines @@
 // Author: wan@google.com (Zhanyong Wan)
 
 // Google Mock - a framework for writing C++ mock classes.
 //
 // This file tests some commonly used argument matchers.
 
 #include <gmock/gmock-matchers.h>
 
 #include <string.h>
 #include <functional>
+#include <iostream>
 #include <list>
 #include <map>
 #include <set>
 #include <sstream>
 #include <string>
 #include <utility>
 #include <vector>
 #include <gmock/gmock.h>
 #include <gtest/gtest.h>
 #include <gtest/gtest-spi.h>
@@ skipping 31 matching lines @@
 using testing::IsNull;
 using testing::Key;
 using testing::Le;
 using testing::Lt;
 using testing::MakeMatcher;
 using testing::MakePolymorphicMatcher;
 using testing::Matcher;
 using testing::MatcherCast;
 using testing::MatcherInterface;
 using testing::Matches;
+using testing::ExplainMatchResult;
+using testing::MatchResultListener;
 using testing::NanSensitiveDoubleEq;
 using testing::NanSensitiveFloatEq;
 using testing::Ne;
 using testing::Not;
 using testing::NotNull;
 using testing::Pair;
 using testing::Pointee;
 using testing::PolymorphicMatcher;
 using testing::Property;
 using testing::Ref;
 using testing::ResultOf;
 using testing::StartsWith;
 using testing::StrCaseEq;
 using testing::StrCaseNe;
 using testing::StrEq;
 using testing::StrNe;
 using testing::Truly;
 using testing::TypedEq;
 using testing::Value;
 using testing::_;
+using testing::internal::DummyMatchResultListener;
 using testing::internal::FloatingEqMatcher;
 using testing::internal::FormatMatcherDescriptionSyntaxError;
 using testing::internal::GetParamIndex;
 using testing::internal::Interpolation;
 using testing::internal::Interpolations;
 using testing::internal::JoinAsTuple;
 using testing::internal::SkipPrefix;
+using testing::internal::StreamMatchResultListener;
 using testing::internal::String;
 using testing::internal::Strings;
+using testing::internal::StringMatchResultListener;
 using testing::internal::ValidateMatcherDescription;
 using testing::internal::kInvalidInterpolation;
 using testing::internal::kPercentInterpolation;
 using testing::internal::kTupleInterpolation;
 using testing::internal::linked_ptr;
 using testing::internal::scoped_ptr;
 using testing::internal::string;
 
-#ifdef GMOCK_HAS_REGEX
 using testing::ContainsRegex;
 using testing::MatchesRegex;
 using testing::internal::RE;
-#endif  // GMOCK_HAS_REGEX
 
 // For testing ExplainMatchResultTo().
 class GreaterThanMatcher : public MatcherInterface<int> {
  public:
   explicit GreaterThanMatcher(int rhs) : rhs_(rhs) {}
 
-  virtual bool Matches(int lhs) const { return lhs > rhs_; }
-
   virtual void DescribeTo(::std::ostream* os) const {
     *os << "is greater than " << rhs_;
   }
 
-  virtual void ExplainMatchResultTo(int lhs, ::std::ostream* os) const {
+  virtual bool MatchAndExplain(int lhs,
+                               MatchResultListener* listener) const {
     const int diff = lhs - rhs_;
     if (diff > 0) {
-      *os << "is " << diff << " more than " << rhs_;
+      *listener << "which is " << diff << " more than " << rhs_;
     } else if (diff == 0) {
-      *os << "is the same as " << rhs_;
+      *listener << "which is the same as " << rhs_;
     } else {
-      *os << "is " << -diff << " less than " << rhs_;
+      *listener << "which is " << -diff << " less than " << rhs_;
     }
+
+    return lhs > rhs_;
   }
 
  private:
   int rhs_;
 };
 
 Matcher<int> GreaterThan(int n) {
   return MakeMatcher(new GreaterThanMatcher(n));
 }
 
@@ skipping 14 matching lines @@
 }
 
 // Returns the reason why x matches, or doesn't match, m.
 template <typename MatcherType, typename Value>
 string Explain(const MatcherType& m, const Value& x) {
   stringstream ss;
   m.ExplainMatchResultTo(x, &ss);
   return ss.str();
 }
 
+TEST(MatchResultListenerTest, StreamingWorks) {
+  StringMatchResultListener listener;
+  listener << "hi" << 5;
+  EXPECT_EQ("hi5", listener.str());
+
+  // Streaming shouldn't crash when the underlying ostream is NULL.
+  DummyMatchResultListener dummy;
+  dummy << "hi" << 5;
+}
+
+TEST(MatchResultListenerTest, CanAccessUnderlyingStream) {
+  EXPECT_TRUE(DummyMatchResultListener().stream() == NULL);
+  EXPECT_TRUE(StreamMatchResultListener(NULL).stream() == NULL);
+
+  EXPECT_EQ(&std::cout, StreamMatchResultListener(&std::cout).stream());
+}
+
+TEST(MatchResultListenerTest, IsInterestedWorks) {
+  EXPECT_TRUE(StringMatchResultListener().IsInterested());
+  EXPECT_TRUE(StreamMatchResultListener(&std::cout).IsInterested());
+
+  EXPECT_FALSE(DummyMatchResultListener().IsInterested());
+  EXPECT_FALSE(StreamMatchResultListener(NULL).IsInterested());
+}
+
 // Makes sure that the MatcherInterface<T> interface doesn't
 // change.
 class EvenMatcherImpl : public MatcherInterface<int> {
  public:
-  virtual bool Matches(int x) const { return x % 2 == 0; }
+  virtual bool MatchAndExplain(int x,
+                               MatchResultListener* /* listener */) const {
+    return x % 2 == 0;
+  }
 
   virtual void DescribeTo(::std::ostream* os) const {
     *os << "is an even number";
   }
 
   // We deliberately don't define DescribeNegationTo() and
   // ExplainMatchResultTo() here, to make sure the definition of these
   // two methods is optional.
 };
 
-TEST(MatcherInterfaceTest, CanBeImplemented) {
+// Makes sure that the MatcherInterface API doesn't change.
+TEST(MatcherInterfaceTest, CanBeImplementedUsingPublishedAPI) {
   EvenMatcherImpl m;
 }
 
+// Tests implementing a monomorphic matcher using MatchAndExplain().
+
+class NewEvenMatcherImpl : public MatcherInterface<int> {
+ public:
+  virtual bool MatchAndExplain(int x, MatchResultListener* listener) const {
+    const bool match = x % 2 == 0;
+    // Verifies that we can stream to a listener directly.
+    *listener << "value % " << 2;
+    if (listener->stream() != NULL) {
+      // Verifies that we can stream to a listener's underlying stream
+      // too.
+      *listener->stream() << " == " << (x % 2);
+    }
+    return match;
+  }
+
+  virtual void DescribeTo(::std::ostream* os) const {
+    *os << "is an even number";
+  }
+};
+
+TEST(MatcherInterfaceTest, CanBeImplementedUsingNewAPI) {
+  Matcher<int> m = MakeMatcher(new NewEvenMatcherImpl);
+  EXPECT_TRUE(m.Matches(2));
+  EXPECT_FALSE(m.Matches(3));
+  EXPECT_EQ("value % 2 == 0", Explain(m, 2));
+  EXPECT_EQ("value % 2 == 1", Explain(m, 3));
+}
+
 // Tests default-constructing a matcher.
 TEST(MatcherTest, CanBeDefaultConstructed) {
   Matcher<double> m;
 }
 
 // Tests that Matcher<T> can be constructed from a MatcherInterface<T>*.
 TEST(MatcherTest, CanBeConstructedFromMatcherInterface) {
   const MatcherInterface<int>* impl = new EvenMatcherImpl;
   Matcher<int> m(impl);
   EXPECT_TRUE(m.Matches(4));
@@ skipping 28 matching lines @@
   EXPECT_FALSE(m1.Matches(false));
 }
 
 // Tests that Matcher<T>::DescribeTo() calls
 // MatcherInterface<T>::DescribeTo().
 TEST(MatcherTest, CanDescribeItself) {
   EXPECT_EQ("is an even number",
             Describe(Matcher<int>(new EvenMatcherImpl)));
 }
 
+// Tests Matcher<T>::MatchAndExplain().
+TEST(MatcherTest, MatchAndExplain) {
+  Matcher<int> m = GreaterThan(0);
+  StringMatchResultListener listener1;
+  EXPECT_TRUE(m.MatchAndExplain(42, &listener1));
+  EXPECT_EQ("which is 42 more than 0", listener1.str());
+
+  StringMatchResultListener listener2;
+  EXPECT_FALSE(m.MatchAndExplain(-9, &listener2));
+  EXPECT_EQ("which is 9 less than 0", listener2.str());
+}
+
 // Tests that a C-string literal can be implicitly converted to a
 // Matcher<string> or Matcher<const string&>.
 TEST(StringMatcherTest, CanBeImplicitlyConstructedFromCStringLiteral) {
   Matcher<string> m1 = "hi";
   EXPECT_TRUE(m1.Matches("hi"));
   EXPECT_FALSE(m1.Matches("hello"));
 
   Matcher<const string&> m2 = "hi";
   EXPECT_TRUE(m2.Matches("hi"));
   EXPECT_FALSE(m2.Matches("hello"));
@@ skipping 12 matching lines @@
 }
 
 // Tests that MakeMatcher() constructs a Matcher<T> from a
 // MatcherInterface* without requiring the user to explicitly
 // write the type.
 TEST(MakeMatcherTest, ConstructsMatcherFromMatcherInterface) {
   const MatcherInterface<int>* dummy_impl = NULL;
   Matcher<int> m = MakeMatcher(dummy_impl);
 }
 
-// Tests that MakePolymorphicMatcher() constructs a polymorphic
-// matcher from its implementation.
+// Tests that MakePolymorphicMatcher() can construct a polymorphic
+// matcher from its implementation using the old API.
 const int bar = 1;
 class ReferencesBarOrIsZeroImpl {
  public:
   template <typename T>
-  bool Matches(const T& x) const {
+  bool MatchAndExplain(const T& x,
+                       MatchResultListener* /* listener */) const {
     const void* p = &x;
     return p == &bar || x == 0;
   }
 
   void DescribeTo(::std::ostream* os) const { *os << "bar or zero"; }
 
   void DescribeNegationTo(::std::ostream* os) const {
     *os << "doesn't reference bar and is not zero";
   }
 };
 
 // This function verifies that MakePolymorphicMatcher() returns a
 // PolymorphicMatcher<T> where T is the argument's type.
 PolymorphicMatcher<ReferencesBarOrIsZeroImpl> ReferencesBarOrIsZero() {
   return MakePolymorphicMatcher(ReferencesBarOrIsZeroImpl());
 }
 
-TEST(MakePolymorphicMatcherTest, ConstructsMatcherFromImpl) {
+TEST(MakePolymorphicMatcherTest, ConstructsMatcherUsingOldAPI) {
   // Using a polymorphic matcher to match a reference type.
   Matcher<const int&> m1 = ReferencesBarOrIsZero();
   EXPECT_TRUE(m1.Matches(0));
   // Verifies that the identity of a by-reference argument is preserved.
   EXPECT_TRUE(m1.Matches(bar));
   EXPECT_FALSE(m1.Matches(1));
   EXPECT_EQ("bar or zero", Describe(m1));
 
   // Using a polymorphic matcher to match a value type.
   Matcher<double> m2 = ReferencesBarOrIsZero();
   EXPECT_TRUE(m2.Matches(0.0));
   EXPECT_FALSE(m2.Matches(0.1));
   EXPECT_EQ("bar or zero", Describe(m2));
 }
 
+// Tests implementing a polymorphic matcher using MatchAndExplain().
+
+class PolymorphicIsEvenImpl {
+ public:
+  void DescribeTo(::std::ostream* os) const { *os << "is even"; }
+
+  void DescribeNegationTo(::std::ostream* os) const {
+    *os << "is odd";
+  }
+
+  template <typename T>
+  bool MatchAndExplain(const T& x, MatchResultListener* listener) const {
+    // Verifies that we can stream to the listener directly.
+    *listener << "% " << 2;
+    if (listener->stream() != NULL) {
+      // Verifies that we can stream to the listener's underlying stream
+      // too.
+      *listener->stream() << " == " << (x % 2);
+    }
+    return (x % 2) == 0;
+  }
+};
+
+PolymorphicMatcher<PolymorphicIsEvenImpl> PolymorphicIsEven() {
+  return MakePolymorphicMatcher(PolymorphicIsEvenImpl());
+}
+
+TEST(MakePolymorphicMatcherTest, ConstructsMatcherUsingNewAPI) {
+  // Using PolymorphicIsEven() as a Matcher<int>.
+  const Matcher<int> m1 = PolymorphicIsEven();
+  EXPECT_TRUE(m1.Matches(42));
+  EXPECT_FALSE(m1.Matches(43));
+  EXPECT_EQ("is even", Describe(m1));
+
+  const Matcher<int> not_m1 = Not(m1);
+  EXPECT_EQ("is odd", Describe(not_m1));
+
+  EXPECT_EQ("% 2 == 0", Explain(m1, 42));
+
+  // Using PolymorphicIsEven() as a Matcher<char>.
+  const Matcher<char> m2 = PolymorphicIsEven();
+  EXPECT_TRUE(m2.Matches('\x42'));
+  EXPECT_FALSE(m2.Matches('\x43'));
+  EXPECT_EQ("is even", Describe(m2));
+
+  const Matcher<char> not_m2 = Not(m2);
+  EXPECT_EQ("is odd", Describe(not_m2));
+
+  EXPECT_EQ("% 2 == 0", Explain(m2, '\x42'));
+}
+
 // Tests that MatcherCast<T>(m) works when m is a polymorphic matcher.
 TEST(MatcherCastTest, FromPolymorphicMatcher) {
   Matcher<int> m = MatcherCast<int>(Eq(5));
   EXPECT_TRUE(m.Matches(5));
   EXPECT_FALSE(m.Matches(6));
 }
 
 // For testing casting matchers between compatible types.
 class IntValue {
  public:
@@ skipping 706 matching lines @@
             ", or has a second field that is not equal to 42",
             DescribeNegation(m1));
   // Double and triple negation (1 or 2 times not and description of negation).
   Matcher<const std::pair<int, int>&> m2 = Not(Pair(Not(13), 42));
   EXPECT_EQ("has a first field that is not equal to 13"
             ", and has a second field that is equal to 42",
             DescribeNegation(m2));
 }
 
 TEST(PairTest, CanExplainMatchResultTo) {
-  const Matcher<std::pair<int, int> > m0 = Pair(0, 0);
-  EXPECT_EQ("", Explain(m0, std::make_pair(25, 42)));
+  // If neither field matches, Pair() should explain about the first
+  // field.
+  const Matcher<std::pair<int, int> > m = Pair(GreaterThan(0), GreaterThan(0));
+  EXPECT_EQ("whose first field does not match, which is 1 less than 0",
+            Explain(m, std::make_pair(-1, -2)));
 
-  const Matcher<std::pair<int, int> > m1 = Pair(GreaterThan(0), 0);
-  EXPECT_EQ("the first field is 25 more than 0",
-            Explain(m1, std::make_pair(25, 42)));
+  // If the first field matches but the second doesn't, Pair() should
+  // explain about the second field.
+  EXPECT_EQ("whose second field does not match, which is 2 less than 0",
+            Explain(m, std::make_pair(1, -2)));
 
-  const Matcher<std::pair<int, int> > m2 = Pair(0, GreaterThan(0));
-  EXPECT_EQ("the second field is 42 more than 0",
-            Explain(m2, std::make_pair(25, 42)));
+  // If the first field doesn't match but the second does, Pair()
+  // should explain about the first field.
+  EXPECT_EQ("whose first field does not match, which is 1 less than 0",
+            Explain(m, std::make_pair(-1, 2)));
 
-  const Matcher<std::pair<int, int> > m3 = Pair(GreaterThan(0), GreaterThan(0));
-  EXPECT_EQ("the first field is 25 more than 0"
-            ", and the second field is 42 more than 0",
-            Explain(m3, std::make_pair(25, 42)));
+  // If both fields match, Pair() should explain about them both.
+  EXPECT_EQ("whose both fields match, where the first field is a value "
+            "which is 1 more than 0, and the second field is a value "
+            "which is 2 more than 0",
+            Explain(m, std::make_pair(1, 2)));
+
+  // If only the first match has an explanation, only this explanation should
+  // be printed.
+  const Matcher<std::pair<int, int> > explain_first = Pair(GreaterThan(0), 0);
+  EXPECT_EQ("whose both fields match, where the first field is a value "
+            "which is 1 more than 0",
+            Explain(explain_first, std::make_pair(1, 0)));
+
+  // If only the second match has an explanation, only this explanation should
+  // be printed.
+  const Matcher<std::pair<int, int> > explain_second = Pair(0, GreaterThan(0));
+  EXPECT_EQ("whose both fields match, where the second field is a value "
+            "which is 1 more than 0",
+            Explain(explain_second, std::make_pair(0, 1)));
 }
 
 TEST(PairTest, MatchesCorrectly) {
   std::pair<int, std::string> p(25, "foo");
 
   // Both fields match.
   EXPECT_THAT(p, Pair(25, "foo"));
   EXPECT_THAT(p, Pair(Ge(20), HasSubstr("o")));
 
   // 'first' doesnt' match, but 'second' matches.
@@ skipping 65 matching lines @@
   EXPECT_TRUE(m2.Matches("Super Hi"));
   EXPECT_FALSE(m2.Matches("i"));
   EXPECT_FALSE(m2.Matches("Hi "));
 }
 
 TEST(EndsWithTest, CanDescribeSelf) {
   Matcher<const std::string> m = EndsWith("Hi");
   EXPECT_EQ("ends with \"Hi\"", Describe(m));
 }
 
-#ifdef GMOCK_HAS_REGEX
-
 // Tests MatchesRegex().
 
 TEST(MatchesRegexTest, MatchesStringMatchingGivenRegex) {
   const Matcher<const char*> m1 = MatchesRegex("a.*z");
   EXPECT_TRUE(m1.Matches("az"));
   EXPECT_TRUE(m1.Matches("abcz"));
   EXPECT_FALSE(m1.Matches(NULL));
 
   const Matcher<const string&> m2 = MatchesRegex(new RE("a.*z"));
   EXPECT_TRUE(m2.Matches("azbz"));
   EXPECT_FALSE(m2.Matches("az1"));
   EXPECT_FALSE(m2.Matches("1az"));
 }
 
 TEST(MatchesRegexTest, CanDescribeSelf) {
   Matcher<const std::string> m1 = MatchesRegex(string("Hi.*"));
   EXPECT_EQ("matches regular expression \"Hi.*\"", Describe(m1));
 
-  Matcher<const char*> m2 = MatchesRegex(new RE("[a-z].*"));
-  EXPECT_EQ("matches regular expression \"[a-z].*\"", Describe(m2));
+  Matcher<const char*> m2 = MatchesRegex(new RE("a.*"));
+  EXPECT_EQ("matches regular expression \"a.*\"", Describe(m2));
 }
 
 // Tests ContainsRegex().
 
 TEST(ContainsRegexTest, MatchesStringContainingGivenRegex) {
   const Matcher<const char*> m1 = ContainsRegex(string("a.*z"));
   EXPECT_TRUE(m1.Matches("az"));
   EXPECT_TRUE(m1.Matches("0abcz1"));
   EXPECT_FALSE(m1.Matches(NULL));
 
   const Matcher<const string&> m2 = ContainsRegex(new RE("a.*z"));
   EXPECT_TRUE(m2.Matches("azbz"));
   EXPECT_TRUE(m2.Matches("az1"));
   EXPECT_FALSE(m2.Matches("1a"));
 }
 
 TEST(ContainsRegexTest, CanDescribeSelf) {
   Matcher<const std::string> m1 = ContainsRegex("Hi.*");
   EXPECT_EQ("contains regular expression \"Hi.*\"", Describe(m1));
 
-  Matcher<const char*> m2 = ContainsRegex(new RE("[a-z].*"));
-  EXPECT_EQ("contains regular expression \"[a-z].*\"", Describe(m2));
+  Matcher<const char*> m2 = ContainsRegex(new RE("a.*"));
+  EXPECT_EQ("contains regular expression \"a.*\"", Describe(m2));
 }
-#endif  // GMOCK_HAS_REGEX
 
 // Tests for wide strings.
 #if GTEST_HAS_STD_WSTRING
 TEST(StdWideStrEqTest, MatchesEqual) {
   Matcher<const wchar_t*> m = StrEq(::std::wstring(L"Hello"));
   EXPECT_TRUE(m.Matches(L"Hello"));
   EXPECT_FALSE(m.Matches(L"hello"));
   EXPECT_FALSE(m.Matches(NULL));
 
   Matcher<const ::std::wstring&> m2 = StrEq(L"Hello");
@@ skipping 733 matching lines @@
   const Matcher<int> is_zero = Eq(0);
   EXPECT_TRUE(Value(0, is_zero));
   EXPECT_FALSE(Value('a', is_zero));
 
   int n = 0;
   const Matcher<const int&> ref_n = Ref(n);
   EXPECT_TRUE(Value(n, ref_n));
   EXPECT_FALSE(Value(1, ref_n));
 }
 
+TEST(ExplainMatchResultTest, WorksWithPolymorphicMatcher) {
+  StringMatchResultListener listener1;
+  EXPECT_TRUE(ExplainMatchResult(PolymorphicIsEven(), 42, &listener1));
+  EXPECT_EQ("% 2 == 0", listener1.str());
+
+  StringMatchResultListener listener2;
+  EXPECT_FALSE(ExplainMatchResult(Ge(42), 1.5, &listener2));
+  EXPECT_EQ("", listener2.str());
+}
+
+TEST(ExplainMatchResultTest, WorksWithMonomorphicMatcher) {
+  const Matcher<int> is_even = PolymorphicIsEven();
+  StringMatchResultListener listener1;
+  EXPECT_TRUE(ExplainMatchResult(is_even, 42, &listener1));
+  EXPECT_EQ("% 2 == 0", listener1.str());
+
+  const Matcher<const double&> is_zero = Eq(0);
+  StringMatchResultListener listener2;
+  EXPECT_FALSE(ExplainMatchResult(is_zero, 1.5, &listener2));
+  EXPECT_EQ("", listener2.str());
+}
+
+MATCHER_P(Really, inner_matcher, "") {
+  return ExplainMatchResult(inner_matcher, arg, result_listener);
+}
+
+TEST(ExplainMatchResultTest, WorksInsideMATCHER) {
+  EXPECT_THAT(0, Really(Eq(0)));
+}
+
 TEST(AllArgsTest, WorksForTuple) {
   EXPECT_THAT(make_tuple(1, 2L), AllArgs(Lt()));
   EXPECT_THAT(make_tuple(2L, 1), Not(AllArgs(Lt())));
 }
 
 TEST(AllArgsTest, WorksForNonTuple) {
   EXPECT_THAT(42, AllArgs(Gt(0)));
   EXPECT_THAT('a', Not(AllArgs(Eq('b'))));
 }
 
@@ skipping 72 matching lines @@
                        "Actual: 0 (is located @");
 }
 
 #if !GTEST_OS_SYMBIAN
 // Tests that ASSERT_THAT() and EXPECT_THAT() work when the matcher is
 // monomorphic.
 
 // ASSERT_THAT("hello", starts_with_he) fails to compile with Nokia's
 // Symbian compiler: it tries to compile
 // template<T, U> class MatcherCastImpl { ...
-//   virtual bool Matches(T x) const {
-//     return source_matcher_.Matches(static_cast<U>(x));
+//   virtual bool MatchAndExplain(T x, ...) const {
+//     return source_matcher_.MatchAndExplain(static_cast<U>(x), ...);
 // with U == string and T == const char*
 // With ASSERT_THAT("hello"...) changed to ASSERT_THAT(string("hello") ... )
 // the compiler silently crashes with no output.
 // If MatcherCastImpl is changed to use U(x) instead of static_cast<U>(x)
 // the code compiles but the converted string is bogus.
 TEST(MatcherAssertionTest, WorksForMonomorphicMatcher) {
   Matcher<const char*> starts_with_he = StartsWith("he");
   ASSERT_THAT("hello", starts_with_he);
 
   Matcher<const string&> ends_with_ok = EndsWith("ok");
@@ skipping 322 matching lines @@
             DescribeNegation(m));
 }
 
 TEST(PointeeTest, CanExplainMatchResult) {
   const Matcher<const string*> m = Pointee(StartsWith("Hi"));
 
   EXPECT_EQ("", Explain(m, static_cast<const string*>(NULL)));
 
   const Matcher<int*> m2 = Pointee(GreaterThan(1));
   int n = 3;
-  EXPECT_EQ("points to a value that is 2 more than 1", Explain(m2, &n));
+  EXPECT_EQ("which points to 3, which is 2 more than 1",
+            Explain(m2, &n));
+}
+
+TEST(PointeeTest, AlwaysExplainsPointee) {
+  const Matcher<int*> m = Pointee(0);
+  int n = 42;
+  EXPECT_EQ("which points to 42", Explain(m, &n));
 }
 
 // An uncopyable class.
 class Uncopyable {
  public:
   explicit Uncopyable(int a_value) : value_(a_value) {}
 
   int value() const { return value_; }
  private:
   const int value_;
@@ skipping 106 matching lines @@
   AStruct a;
   EXPECT_TRUE(m.Matches(a));
   a.x = -1;
   EXPECT_FALSE(m.Matches(a));
 }
 
 // Tests that Field() can describe itself.
 TEST(FieldTest, CanDescribeSelf) {
   Matcher<const AStruct&> m = Field(&AStruct::x, Ge(0));
 
-  EXPECT_EQ("the given field is greater than or equal to 0", Describe(m));
-  EXPECT_EQ("the given field is not greater than or equal to 0",
+  EXPECT_EQ("is an object whose given field is greater than or equal to 0",
+            Describe(m));
+  EXPECT_EQ("is an object whose given field is not greater than or equal to 0",
             DescribeNegation(m));
 }
 
 // Tests that Field() can explain the match result.
 TEST(FieldTest, CanExplainMatchResult) {
   Matcher<const AStruct&> m = Field(&AStruct::x, Ge(0));
 
   AStruct a;
   a.x = 1;
-  EXPECT_EQ("", Explain(m, a));
+  EXPECT_EQ("whose given field is 1", Explain(m, a));
 
   m = Field(&AStruct::x, GreaterThan(0));
-  EXPECT_EQ("the given field is 1 more than 0", Explain(m, a));
+  EXPECT_EQ("whose given field is 1, which is 1 more than 0", Explain(m, a));
 }
 
 // Tests that Field() works when the argument is a pointer to const.
 TEST(FieldForPointerTest, WorksForPointerToConst) {
   Matcher<const AStruct*> m = Field(&AStruct::x, Ge(0));
 
   AStruct a;
   EXPECT_TRUE(m.Matches(&a));
   a.x = -1;
   EXPECT_FALSE(m.Matches(&a));
 }
 
 // Tests that Field() works when the argument is a pointer to non-const.
 TEST(FieldForPointerTest, WorksForPointerToNonConst) {
   Matcher<AStruct*> m = Field(&AStruct::x, Ge(0));
 
   AStruct a;
   EXPECT_TRUE(m.Matches(&a));
   a.x = -1;
   EXPECT_FALSE(m.Matches(&a));
 }
 
+// Tests that Field() works when the argument is a reference to a const pointer.
+TEST(FieldForPointerTest, WorksForReferenceToConstPointer) {
+  Matcher<AStruct* const&> m = Field(&AStruct::x, Ge(0));
+
+  AStruct a;
+  EXPECT_TRUE(m.Matches(&a));
+  a.x = -1;
+  EXPECT_FALSE(m.Matches(&a));
+}
+
 // Tests that Field() does not match the NULL pointer.
 TEST(FieldForPointerTest, DoesNotMatchNull) {
   Matcher<const AStruct*> m = Field(&AStruct::x, _);
   EXPECT_FALSE(m.Matches(NULL));
 }
 
 // Tests that Field(&Foo::field, ...) works when the argument's type
 // is a sub-type of const Foo*.
 TEST(FieldForPointerTest, WorksForArgumentOfSubType) {
   // Note that the matcher expects DerivedStruct but we say AStruct
   // inside Field().
   Matcher<DerivedStruct*> m = Field(&AStruct::x, Ge(0));
 
   DerivedStruct d;
   EXPECT_TRUE(m.Matches(&d));
   d.x = -1;
   EXPECT_FALSE(m.Matches(&d));
 }
 
 // Tests that Field() can describe itself when used to match a pointer.
 TEST(FieldForPointerTest, CanDescribeSelf) {
   Matcher<const AStruct*> m = Field(&AStruct::x, Ge(0));
 
-  EXPECT_EQ("the given field is greater than or equal to 0", Describe(m));
-  EXPECT_EQ("the given field is not greater than or equal to 0",
+  EXPECT_EQ("is an object whose given field is greater than or equal to 0",
+            Describe(m));
+  EXPECT_EQ("is an object whose given field is not greater than or equal to 0",
             DescribeNegation(m));
 }
 
 // Tests that Field() can explain the result of matching a pointer.
 TEST(FieldForPointerTest, CanExplainMatchResult) {
   Matcher<const AStruct*> m = Field(&AStruct::x, Ge(0));
 
   AStruct a;
   a.x = 1;
   EXPECT_EQ("", Explain(m, static_cast<const AStruct*>(NULL)));
-  EXPECT_EQ("", Explain(m, &a));
+  EXPECT_EQ("which points to an object whose given field is 1", Explain(m, &a));
 
   m = Field(&AStruct::x, GreaterThan(0));
-  EXPECT_EQ("the given field is 1 more than 0", Explain(m, &a));
+  EXPECT_EQ("which points to an object whose given field is 1, "
+            "which is 1 more than 0", Explain(m, &a));
 }
 
 // A user-defined class for testing Property().
 class AClass {
  public:
   AClass() : n_(0) {}
 
   // A getter that returns a non-reference.
   int n() const { return n_; }
 
@@ skipping 98 matching lines @@
   AClass a;
   EXPECT_TRUE(m.Matches(a));
   a.set_n(-1);
   EXPECT_FALSE(m.Matches(a));
 }
 
 // Tests that Property() can describe itself.
 TEST(PropertyTest, CanDescribeSelf) {
   Matcher<const AClass&> m = Property(&AClass::n, Ge(0));
 
-  EXPECT_EQ("the given property is greater than or equal to 0", Describe(m));
-  EXPECT_EQ("the given property is not greater than or equal to 0",
-            DescribeNegation(m));
+  EXPECT_EQ("is an object whose given property is greater than or equal to 0",
+            Describe(m));
+  EXPECT_EQ("is an object whose given property "
+            "is not greater than or equal to 0", DescribeNegation(m));
 }
 
 // Tests that Property() can explain the match result.
 TEST(PropertyTest, CanExplainMatchResult) {
   Matcher<const AClass&> m = Property(&AClass::n, Ge(0));
 
   AClass a;
   a.set_n(1);
-  EXPECT_EQ("", Explain(m, a));
+  EXPECT_EQ("whose given property is 1", Explain(m, a));
 
   m = Property(&AClass::n, GreaterThan(0));
-  EXPECT_EQ("the given property is 1 more than 0", Explain(m, a));
+  EXPECT_EQ("whose given property is 1, which is 1 more than 0", Explain(m, a));
 }
 
 // Tests that Property() works when the argument is a pointer to const.
 TEST(PropertyForPointerTest, WorksForPointerToConst) {
   Matcher<const AClass*> m = Property(&AClass::n, Ge(0));
 
   AClass a;
   a.set_n(1);
   EXPECT_TRUE(m.Matches(&a));
 
   a.set_n(-1);
   EXPECT_FALSE(m.Matches(&a));
 }
 
 // Tests that Property() works when the argument is a pointer to non-const.
 TEST(PropertyForPointerTest, WorksForPointerToNonConst) {
   Matcher<AClass*> m = Property(&AClass::s, StartsWith("hi"));
 
   AClass a;
   a.set_s("hill");
   EXPECT_TRUE(m.Matches(&a));
 
   a.set_s("hole");
   EXPECT_FALSE(m.Matches(&a));
 }
 
+// Tests that Property() works when the argument is a reference to a
+// const pointer.
+TEST(PropertyForPointerTest, WorksForReferenceToConstPointer) {
+  Matcher<AClass* const&> m = Property(&AClass::s, StartsWith("hi"));
+
+  AClass a;
+  a.set_s("hill");
+  EXPECT_TRUE(m.Matches(&a));
+
+  a.set_s("hole");
+  EXPECT_FALSE(m.Matches(&a));
+}
+
 // Tests that Property() does not match the NULL pointer.
 TEST(PropertyForPointerTest, WorksForReferenceToNonConstProperty) {
   Matcher<const AClass*> m = Property(&AClass::x, _);
   EXPECT_FALSE(m.Matches(NULL));
 }
 
 // Tests that Property(&Foo::property, ...) works when the argument's
 // type is a sub-type of const Foo*.
 TEST(PropertyForPointerTest, WorksForArgumentOfSubType) {
   // The matcher expects a DerivedClass, but inside the Property() we
   // say AClass.
   Matcher<const DerivedClass*> m = Property(&AClass::n, Ge(0));
 
   DerivedClass d;
   d.set_n(1);
   EXPECT_TRUE(m.Matches(&d));
 
   d.set_n(-1);
   EXPECT_FALSE(m.Matches(&d));
 }
 
 // Tests that Property() can describe itself when used to match a pointer.
 TEST(PropertyForPointerTest, CanDescribeSelf) {
   Matcher<const AClass*> m = Property(&AClass::n, Ge(0));
 
-  EXPECT_EQ("the given property is greater than or equal to 0", Describe(m));
-  EXPECT_EQ("the given property is not greater than or equal to 0",
-            DescribeNegation(m));
+  EXPECT_EQ("is an object whose given property is greater than or equal to 0",
+            Describe(m));
+  EXPECT_EQ("is an object whose given property "
+            "is not greater than or equal to 0", DescribeNegation(m));
 }
 
 // Tests that Property() can explain the result of matching a pointer.
 TEST(PropertyForPointerTest, CanExplainMatchResult) {
   Matcher<const AClass*> m = Property(&AClass::n, Ge(0));
 
   AClass a;
   a.set_n(1);
   EXPECT_EQ("", Explain(m, static_cast<const AClass*>(NULL)));
-  EXPECT_EQ("", Explain(m, &a));
+  EXPECT_EQ("which points to an object whose given property is 1",
+            Explain(m, &a));
 
   m = Property(&AClass::n, GreaterThan(0));
-  EXPECT_EQ("the given property is 1 more than 0", Explain(m, &a));
+  EXPECT_EQ("which points to an object whose given property is 1, "
+            "which is 1 more than 0", Explain(m, &a));
 }
 
 // Tests ResultOf.
 
 // Tests that ResultOf(f, ...) compiles and works as expected when f is a
 // function pointer.
 string IntToStringFunction(int input) { return input == 1 ? "foo" : "bar"; }
 
 TEST(ResultOfTest, WorksForFunctionPointers) {
   Matcher<int> matcher = ResultOf(&IntToStringFunction, Eq(string("foo")));
 
   EXPECT_TRUE(matcher.Matches(1));
   EXPECT_FALSE(matcher.Matches(2));
 }
 
 // Tests that ResultOf() can describe itself.
 TEST(ResultOfTest, CanDescribeItself) {
   Matcher<int> matcher = ResultOf(&IntToStringFunction, StrEq("foo"));
 
-  EXPECT_EQ("result of the given callable is equal to \"foo\"",
-            Describe(matcher));
-  EXPECT_EQ("result of the given callable is not equal to \"foo\"",
-            DescribeNegation(matcher));
+  EXPECT_EQ("is mapped by the given callable to a value that "
+            "is equal to \"foo\"", Describe(matcher));
+  EXPECT_EQ("is mapped by the given callable to a value that "
+            "is not equal to \"foo\"", DescribeNegation(matcher));
 }
 
 // Tests that ResultOf() can explain the match result.
 int IntFunction(int input) { return input == 42 ? 80 : 90; }
 
 TEST(ResultOfTest, CanExplainMatchResult) {
   Matcher<int> matcher = ResultOf(&IntFunction, Ge(85));
-  EXPECT_EQ("", Explain(matcher, 36));
+  EXPECT_EQ("which is mapped by the given callable to 90",
+            Explain(matcher, 36));
 
   matcher = ResultOf(&IntFunction, GreaterThan(85));
-  EXPECT_EQ("result of the given callable is 5 more than 85",
-            Explain(matcher, 36));
+  EXPECT_EQ("which is mapped by the given callable to 90, "
+            "which is 5 more than 85", Explain(matcher, 36));
 }
 
 // Tests that ResultOf(f, ...) compiles and works as expected when f(x)
 // returns a non-reference.
 TEST(ResultOfTest, WorksForNonReferenceResults) {
   Matcher<int> matcher = ResultOf(&IntFunction, Eq(80));
 
   EXPECT_TRUE(matcher.Matches(42));
   EXPECT_FALSE(matcher.Matches(36));
 }
@@ skipping 115 matching lines @@
 
   Matcher<const int&> matcher3 = ResultOf(ReferencingFunctor(), Eq(&n));
   EXPECT_TRUE(matcher3.Matches(n));
   EXPECT_FALSE(matcher3.Matches(n2));
 }
 
 class DivisibleByImpl {
  public:
   explicit DivisibleByImpl(int a_divider) : divider_(a_divider) {}
 
+  // For testing using ExplainMatchResultTo() with polymorphic matchers.
   template <typename T>
-  bool Matches(const T& n) const {
+  bool MatchAndExplain(const T& n, MatchResultListener* listener) const {
+    *listener << "is " << (n % divider_) << " modulo "
+              << divider_;
     return (n % divider_) == 0;
   }
 
   void DescribeTo(::std::ostream* os) const {
     *os << "is divisible by " << divider_;
   }
 
   void DescribeNegationTo(::std::ostream* os) const {
     *os << "is not divisible by " << divider_;
   }
 
   void set_divider(int a_divider) { divider_ = a_divider; }
   int divider() const { return divider_; }
 
  private:
   int divider_;
 };
 
-// For testing using ExplainMatchResultTo() with polymorphic matchers.
-template <typename T>
-void ExplainMatchResultTo(const DivisibleByImpl& impl, const T& n,
-                          ::std::ostream* os) {
-  *os << "is " << (n % impl.divider()) << " modulo "
-      << impl.divider();
-}
-
 PolymorphicMatcher<DivisibleByImpl> DivisibleBy(int n) {
   return MakePolymorphicMatcher(DivisibleByImpl(n));
 }
 
 // Tests that when AllOf() fails, only the first failing matcher is
 // asked to explain why.
 TEST(ExplainMatchResultTest, AllOf_False_False) {
   const Matcher<int> m = AllOf(DivisibleBy(4), DivisibleBy(3));
   EXPECT_EQ("is 1 modulo 4", Explain(m, 5));
 }
@@ skipping 19 matching lines @@
   EXPECT_EQ("is 0 modulo 2; is 0 modulo 3", Explain(m, 6));
 }
 
 TEST(ExplainMatchResultTest, AllOf_True_True_2) {
   const Matcher<int> m = AllOf(Ge(2), Le(3));
   EXPECT_EQ("", Explain(m, 2));
 }
 
 TEST(ExplainmatcherResultTest, MonomorphicMatcher) {
   const Matcher<int> m = GreaterThan(5);
-  EXPECT_EQ("is 1 more than 5", Explain(m, 6));
+  EXPECT_EQ("which is 1 more than 5", Explain(m, 6));
 }
 
 // The following two tests verify that values without a public copy
 // ctor can be used as arguments to matchers like Eq(), Ge(), and etc
 // with the help of ByRef().
 
 class NotCopyable {
  public:
   explicit NotCopyable(int a_value) : value_(a_value) {}
 
@@ skipping 289 matching lines @@
               ElementsAre());
 }
 
 TEST(ValidateMatcherDescriptionTest,
      AcceptsNonEmptyDescriptionWithNoInterpolation) {
   const char* params[] = { "foo", "bar", NULL };
   EXPECT_THAT(ValidateMatcherDescription(params, "a simple description"),
               ElementsAre());
 }
 
+// The MATCHER*() macros trigger warning C4100 (unreferenced formal
+// parameter) in MSVC with -W4.  Unfortunately they cannot be fixed in
+// the macro definition, as the warnings are generated when the macro
+// is expanded and macro expansion cannot contain #pragma.  Therefore
+// we suppress them here.
+#ifdef _MSC_VER
+#pragma warning(push)
+#pragma warning(disable:4100)
+#endif
+
 // We use MATCHER_P3() to define a matcher for testing
 // ValidateMatcherDescription(); otherwise we'll end up with much
 // plumbing code.  This is not circular as
 // ValidateMatcherDescription() doesn't affect whether the matcher
 // matches a value or not.
 MATCHER_P3(EqInterpolation, start, end, index, "equals Interpolation%(*)s") {
   return arg.start_pos == start && arg.end_pos == end &&
       arg.param_index == index;
 }
 
+#ifdef _MSC_VER
+#pragma warning(pop)
+#endif
+
 TEST(ValidateMatcherDescriptionTest, AcceptsPercentInterpolation) {
   const char* params[] = { "foo", NULL };
   const char* const desc = "one %%";
   EXPECT_THAT(ValidateMatcherDescription(params, desc),
               ElementsAre(EqInterpolation(desc + 4, desc + 6,
                                           kPercentInterpolation)));
 }
 
 TEST(ValidateMatcherDescriptionTest, AcceptsTupleInterpolation) {
   const char* params[] = { "foo", "bar", "baz", NULL };
@@ skipping 211 matching lines @@
 
 // Tests PolymorphicMatcher::impl().
 TEST(PolymorphicMatcherTest, CanAccessImpl) {
   const PolymorphicMatcher<DivisibleByImpl> m(DivisibleByImpl(42));
   const DivisibleByImpl& impl = m.impl();
   EXPECT_EQ(42, impl.divider());
 }
 
 }  // namespace gmock_matchers_test
 }  // namespace testing