1// Copyright 2007, Google Inc.
2// All rights reserved.
3//
4// Redistribution and use in source and binary forms, with or without
5// modification, are permitted provided that the following conditions are
6// met:
7//
8// * Redistributions of source code must retain the above copyright
9// notice, this list of conditions and the following disclaimer.
10// * Redistributions in binary form must reproduce the above
11// copyright notice, this list of conditions and the following disclaimer
12// in the documentation and/or other materials provided with the
13// distribution.
14// * Neither the name of Google Inc. nor the names of its
15// contributors may be used to endorse or promote products derived from
16// this software without specific prior written permission.
17//
18// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29
30// The Google C++ Testing and Mocking Framework (Google Test)
31//
32// This file implements just enough of the matcher interface to allow
33// EXPECT_DEATH and friends to accept a matcher argument.
34
35#ifndef GOOGLETEST_INCLUDE_GTEST_GTEST_MATCHERS_H_
36#define GOOGLETEST_INCLUDE_GTEST_GTEST_MATCHERS_H_
37
38#include <atomic>
39#include <memory>
40#include <ostream>
41#include <string>
42#include <type_traits>
43
44#include "gtest/gtest-printers.h"
45#include "gtest/internal/gtest-internal.h"
46#include "gtest/internal/gtest-port.h"
47
48// MSVC warning C5046 is new as of VS2017 version 15.8.
49#if defined(_MSC_VER) && _MSC_VER >= 1915
50#define GTEST_MAYBE_5046_ 5046
51#else
52#define GTEST_MAYBE_5046_
53#endif
54
55GTEST_DISABLE_MSC_WARNINGS_PUSH_(
56 4251 GTEST_MAYBE_5046_ /* class A needs to have dll-interface to be used by
57 clients of class B */
58 /* Symbol involving type with internal linkage not defined */)
59
60#if defined(__linux__) && !defined(_LIBCPP_VERSION)
61
62// Disable deprecation warning for `has_trivial_copy_constructor`.
63#if defined(__GNUC__) && !defined(__INTEL_COMPILER)
64#pragma GCC diagnostic push
65#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
66#endif
67
68// Add detection of available trait to detect whether types has a trivial
69// copy constructor. The rationale: GNU versions 4.9 and older don't support
70// std::is_trivially_copy_constructible.
71namespace std {
72template <typename T>
73struct is_trivially_copy_constructible;
74template <typename T>
75struct has_trivial_copy_constructor;
76} // namespace std
77
78namespace {
79
80template <class T, class = void>
81struct is_complete_type {
82 static constexpr bool value = false;
83};
84
85template <class T>
86struct is_complete_type<T,
87 typename std::enable_if<(sizeof(T) > 0), void>::type> {
88 static constexpr bool value = true;
89};
90
91template <typename T>
92constexpr typename std::enable_if<
93 is_complete_type<std::is_trivially_copy_constructible<T>>::value,
94 bool>::type
95has_trivial_copy_constructor_impl(int) {
96 return std::is_trivially_copy_constructible<T>::value;
97}
98
99template <typename T>
100constexpr typename std::enable_if<
101 is_complete_type<std::has_trivial_copy_constructor<T>>::value,
102 bool>::type
103has_trivial_copy_constructor_impl(long) {
104 return std::has_trivial_copy_constructor<T>::value;
105}
106
107} // namespace
108
109#if defined(__GNUC__) && !defined(__INTEL_COMPILER)
110#pragma GCC diagnostic pop
111#endif
112
113#endif
114
115template <typename T>
116constexpr bool has_trivial_copy_constructor() {
117#if defined(__linux__) && !defined(_LIBCPP_VERSION)
118 // When both traits are available use std::is_trivially_copy_constructible.
119 return has_trivial_copy_constructor_impl<T>(0);
120#else
121 return std::is_trivially_copy_constructible<T>::value;
122#endif
123}
124// Intel's modification ends.
125
126namespace testing {
127
128// To implement a matcher Foo for type T, define:
129// 1. a class FooMatcherMatcher that implements the matcher interface:
130// using is_gtest_matcher = void;
131// bool MatchAndExplain(const T&, std::ostream*);
132// (MatchResultListener* can also be used instead of std::ostream*)
133// void DescribeTo(std::ostream*);
134// void DescribeNegationTo(std::ostream*);
135//
136// 2. a factory function that creates a Matcher<T> object from a
137// FooMatcherMatcher.
138
139class MatchResultListener {
140 public:
141 // Creates a listener object with the given underlying ostream. The
142 // listener does not own the ostream, and does not dereference it
143 // in the constructor or destructor.
144 explicit MatchResultListener(::std::ostream* os) : stream_(os) {}
145 virtual ~MatchResultListener() = 0; // Makes this class abstract.
146
147 // Streams x to the underlying ostream; does nothing if the ostream
148 // is NULL.
149 template <typename T>
150 MatchResultListener& operator<<(const T& x) {
151 if (stream_ != nullptr) *stream_ << x;
152 return *this;
153 }
154
155 // Returns the underlying ostream.
156 ::std::ostream* stream() { return stream_; }
157
158 // Returns true if and only if the listener is interested in an explanation
159 // of the match result. A matcher's MatchAndExplain() method can use
160 // this information to avoid generating the explanation when no one
161 // intends to hear it.
162 bool IsInterested() const { return stream_ != nullptr; }
163
164 private:
165 ::std::ostream* const stream_;
166
167 GTEST_DISALLOW_COPY_AND_ASSIGN_(MatchResultListener);
168};
169
170inline MatchResultListener::~MatchResultListener() {
171}
172
173// An instance of a subclass of this knows how to describe itself as a
174// matcher.
175class GTEST_API_ MatcherDescriberInterface {
176 public:
177 virtual ~MatcherDescriberInterface() {}
178
179 // Describes this matcher to an ostream. The function should print
180 // a verb phrase that describes the property a value matching this
181 // matcher should have. The subject of the verb phrase is the value
182 // being matched. For example, the DescribeTo() method of the Gt(7)
183 // matcher prints "is greater than 7".
184 virtual void DescribeTo(::std::ostream* os) const = 0;
185
186 // Describes the negation of this matcher to an ostream. For
187 // example, if the description of this matcher is "is greater than
188 // 7", the negated description could be "is not greater than 7".
189 // You are not required to override this when implementing
190 // MatcherInterface, but it is highly advised so that your matcher
191 // can produce good error messages.
192 virtual void DescribeNegationTo(::std::ostream* os) const {
193 *os << "not (";
194 DescribeTo(os);
195 *os << ")";
196 }
197};
198
199// The implementation of a matcher.
200template <typename T>
201class MatcherInterface : public MatcherDescriberInterface {
202 public:
203 // Returns true if and only if the matcher matches x; also explains the
204 // match result to 'listener' if necessary (see the next paragraph), in
205 // the form of a non-restrictive relative clause ("which ...",
206 // "whose ...", etc) that describes x. For example, the
207 // MatchAndExplain() method of the Pointee(...) matcher should
208 // generate an explanation like "which points to ...".
209 //
210 // Implementations of MatchAndExplain() should add an explanation of
211 // the match result *if and only if* they can provide additional
212 // information that's not already present (or not obvious) in the
213 // print-out of x and the matcher's description. Whether the match
214 // succeeds is not a factor in deciding whether an explanation is
215 // needed, as sometimes the caller needs to print a failure message
216 // when the match succeeds (e.g. when the matcher is used inside
217 // Not()).
218 //
219 // For example, a "has at least 10 elements" matcher should explain
220 // what the actual element count is, regardless of the match result,
221 // as it is useful information to the reader; on the other hand, an
222 // "is empty" matcher probably only needs to explain what the actual
223 // size is when the match fails, as it's redundant to say that the
224 // size is 0 when the value is already known to be empty.
225 //
226 // You should override this method when defining a new matcher.
227 //
228 // It's the responsibility of the caller (Google Test) to guarantee
229 // that 'listener' is not NULL. This helps to simplify a matcher's
230 // implementation when it doesn't care about the performance, as it
231 // can talk to 'listener' without checking its validity first.
232 // However, in order to implement dummy listeners efficiently,
233 // listener->stream() may be NULL.
234 virtual bool MatchAndExplain(T x, MatchResultListener* listener) const = 0;
235
236 // Inherits these methods from MatcherDescriberInterface:
237 // virtual void DescribeTo(::std::ostream* os) const = 0;
238 // virtual void DescribeNegationTo(::std::ostream* os) const;
239};
240
241namespace internal {
242
243struct AnyEq {
244 template <typename A, typename B>
245 bool operator()(const A& a, const B& b) const { return a == b; }
246};
247struct AnyNe {
248 template <typename A, typename B>
249 bool operator()(const A& a, const B& b) const { return a != b; }
250};
251struct AnyLt {
252 template <typename A, typename B>
253 bool operator()(const A& a, const B& b) const { return a < b; }
254};
255struct AnyGt {
256 template <typename A, typename B>
257 bool operator()(const A& a, const B& b) const { return a > b; }
258};
259struct AnyLe {
260 template <typename A, typename B>
261 bool operator()(const A& a, const B& b) const { return a <= b; }
262};
263struct AnyGe {
264 template <typename A, typename B>
265 bool operator()(const A& a, const B& b) const { return a >= b; }
266};
267
268// A match result listener that ignores the explanation.
269class DummyMatchResultListener : public MatchResultListener {
270 public:
271 DummyMatchResultListener() : MatchResultListener(nullptr) {}
272
273 private:
274 GTEST_DISALLOW_COPY_AND_ASSIGN_(DummyMatchResultListener);
275};
276
277// A match result listener that forwards the explanation to a given
278// ostream. The difference between this and MatchResultListener is
279// that the former is concrete.
280class StreamMatchResultListener : public MatchResultListener {
281 public:
282 explicit StreamMatchResultListener(::std::ostream* os)
283 : MatchResultListener(os) {}
284
285 private:
286 GTEST_DISALLOW_COPY_AND_ASSIGN_(StreamMatchResultListener);
287};
288
289struct SharedPayloadBase {
290 std::atomic<int> ref{1};
291 void Ref() { ref.fetch_add(1, std::memory_order_relaxed); }
292 bool Unref() { return ref.fetch_sub(1, std::memory_order_acq_rel) == 1; }
293};
294
295template <typename T>
296struct SharedPayload : SharedPayloadBase {
297 explicit SharedPayload(const T& v) : value(v) {}
298 explicit SharedPayload(T&& v) : value(std::move(v)) {}
299
300 static void Destroy(SharedPayloadBase* shared) {
301 delete static_cast<SharedPayload*>(shared);
302 }
303
304 T value;
305};
306
307// An internal class for implementing Matcher<T>, which will derive
308// from it. We put functionalities common to all Matcher<T>
309// specializations here to avoid code duplication.
310template <typename T>
311class MatcherBase : private MatcherDescriberInterface {
312 public:
313 // Returns true if and only if the matcher matches x; also explains the
314 // match result to 'listener'.
315 bool MatchAndExplain(const T& x, MatchResultListener* listener) const {
316 GTEST_CHECK_(vtable_ != nullptr);
317 return vtable_->match_and_explain(*this, x, listener);
318 }
319
320 // Returns true if and only if this matcher matches x.
321 bool Matches(const T& x) const {
322 DummyMatchResultListener dummy;
323 return MatchAndExplain(x, &dummy);
324 }
325
326 // Describes this matcher to an ostream.
327 void DescribeTo(::std::ostream* os) const final {
328 GTEST_CHECK_(vtable_ != nullptr);
329 vtable_->describe(*this, os, false);
330 }
331
332 // Describes the negation of this matcher to an ostream.
333 void DescribeNegationTo(::std::ostream* os) const final {
334 GTEST_CHECK_(vtable_ != nullptr);
335 vtable_->describe(*this, os, true);
336 }
337
338 // Explains why x matches, or doesn't match, the matcher.
339 void ExplainMatchResultTo(const T& x, ::std::ostream* os) const {
340 StreamMatchResultListener listener(os);
341 MatchAndExplain(x, &listener);
342 }
343
344 // Returns the describer for this matcher object; retains ownership
345 // of the describer, which is only guaranteed to be alive when
346 // this matcher object is alive.
347 const MatcherDescriberInterface* GetDescriber() const {
348 if (vtable_ == nullptr) return nullptr;
349 return vtable_->get_describer(*this);
350 }
351
352 protected:
353 MatcherBase() : vtable_(nullptr) {}
354
355 // Constructs a matcher from its implementation.
356 template <typename U>
357 explicit MatcherBase(const MatcherInterface<U>* impl) {
358 Init(impl);
359 }
360
361 template <typename M, typename = typename std::remove_reference<
362 M>::type::is_gtest_matcher>
363 MatcherBase(M&& m) { // NOLINT
364 Init(std::forward<M>(m));
365 }
366
367 MatcherBase(const MatcherBase& other)
368 : vtable_(other.vtable_), buffer_(other.buffer_) {
369 if (IsShared()) buffer_.shared->Ref();
370 }
371
372 MatcherBase& operator=(const MatcherBase& other) {
373 if (this == &other) return *this;
374 Destroy();
375 vtable_ = other.vtable_;
376 buffer_ = other.buffer_;
377 if (IsShared()) buffer_.shared->Ref();
378 return *this;
379 }
380
381 MatcherBase(MatcherBase&& other)
382 : vtable_(other.vtable_), buffer_(other.buffer_) {
383 other.vtable_ = nullptr;
384 }
385
386 MatcherBase& operator=(MatcherBase&& other) {
387 if (this == &other) return *this;
388 Destroy();
389 vtable_ = other.vtable_;
390 buffer_ = other.buffer_;
391 other.vtable_ = nullptr;
392 return *this;
393 }
394
395 ~MatcherBase() override { Destroy(); }
396
397 private:
398 struct VTable {
399 bool (*match_and_explain)(const MatcherBase&, const T&,
400 MatchResultListener*);
401 void (*describe)(const MatcherBase&, std::ostream*, bool negation);
402 // Returns the captured object if it implements the interface, otherwise
403 // returns the MatcherBase itself.
404 const MatcherDescriberInterface* (*get_describer)(const MatcherBase&);
405 // Called on shared instances when the reference count reaches 0.
406 void (*shared_destroy)(SharedPayloadBase*);
407 };
408
409 bool IsShared() const {
410 return vtable_ != nullptr && vtable_->shared_destroy != nullptr;
411 }
412
413 // If the implementation uses a listener, call that.
414 template <typename P>
415 static auto MatchAndExplainImpl(const MatcherBase& m, const T& value,
416 MatchResultListener* listener)
417 -> decltype(P::Get(m).MatchAndExplain(value, listener->stream())) {
418 return P::Get(m).MatchAndExplain(value, listener->stream());
419 }
420
421 template <typename P>
422 static auto MatchAndExplainImpl(const MatcherBase& m, const T& value,
423 MatchResultListener* listener)
424 -> decltype(P::Get(m).MatchAndExplain(value, listener)) {
425 return P::Get(m).MatchAndExplain(value, listener);
426 }
427
428 template <typename P>
429 static void DescribeImpl(const MatcherBase& m, std::ostream* os,
430 bool negation) {
431 if (negation) {
432 P::Get(m).DescribeNegationTo(os);
433 } else {
434 P::Get(m).DescribeTo(os);
435 }
436 }
437
438 template <typename P>
439 static const MatcherDescriberInterface* GetDescriberImpl(
440 const MatcherBase& m) {
441 // If the impl is a MatcherDescriberInterface, then return it.
442 // Otherwise use MatcherBase itself.
443 // This allows us to implement the GetDescriber() function without support
444 // from the impl, but some users really want to get their impl back when
445 // they call GetDescriber().
446 // We use std::get on a tuple as a workaround of not having `if constexpr`.
447 return std::get<(
448 std::is_convertible<decltype(&P::Get(m)),
449 const MatcherDescriberInterface*>::value
450 ? 1
451 : 0)>(std::make_tuple(&m, &P::Get(m)));
452 }
453
454 template <typename P>
455 const VTable* GetVTable() {
456 static constexpr VTable kVTable = {&MatchAndExplainImpl<P>,
457 &DescribeImpl<P>, &GetDescriberImpl<P>,
458 P::shared_destroy};
459 return &kVTable;
460 }
461
462 union Buffer {
463 // Add some types to give Buffer some common alignment/size use cases.
464 void* ptr;
465 double d;
466 int64_t i;
467 // And add one for the out-of-line cases.
468 SharedPayloadBase* shared;
469 };
470
471 void Destroy() {
472 if (IsShared() && buffer_.shared->Unref()) {
473 vtable_->shared_destroy(buffer_.shared);
474 }
475 }
476
477 template <typename M>
478 static constexpr bool IsInlined() {
479 return sizeof(M) <= sizeof(Buffer) && alignof(M) <= alignof(Buffer) &&
480 has_trivial_copy_constructor<M>() &&
481 std::is_trivially_destructible<M>::value;
482 }
483
484 template <typename M, bool = MatcherBase::IsInlined<M>()>
485 struct ValuePolicy {
486 static const M& Get(const MatcherBase& m) {
487 // When inlined along with Init, need to be explicit to avoid violating
488 // strict aliasing rules.
489 const M *ptr = static_cast<const M*>(
490 static_cast<const void*>(&m.buffer_));
491 return *ptr;
492 }
493 static void Init(MatcherBase& m, M impl) {
494 ::new (static_cast<void*>(&m.buffer_)) M(impl);
495 }
496 static constexpr auto shared_destroy = nullptr;
497 };
498
499 template <typename M>
500 struct ValuePolicy<M, false> {
501 using Shared = SharedPayload<M>;
502 static const M& Get(const MatcherBase& m) {
503 return static_cast<Shared*>(m.buffer_.shared)->value;
504 }
505 template <typename Arg>
506 static void Init(MatcherBase& m, Arg&& arg) {
507 m.buffer_.shared = new Shared(std::forward<Arg>(arg));
508 }
509 static constexpr auto shared_destroy = &Shared::Destroy;
510 };
511
512 template <typename U, bool B>
513 struct ValuePolicy<const MatcherInterface<U>*, B> {
514 using M = const MatcherInterface<U>;
515 using Shared = SharedPayload<std::unique_ptr<M>>;
516 static const M& Get(const MatcherBase& m) {
517 return *static_cast<Shared*>(m.buffer_.shared)->value;
518 }
519 static void Init(MatcherBase& m, M* impl) {
520 m.buffer_.shared = new Shared(std::unique_ptr<M>(impl));
521 }
522
523 static constexpr auto shared_destroy = &Shared::Destroy;
524 };
525
526 template <typename M>
527 void Init(M&& m) {
528 using MM = typename std::decay<M>::type;
529 using Policy = ValuePolicy<MM>;
530 vtable_ = GetVTable<Policy>();
531 Policy::Init(*this, std::forward<M>(m));
532 }
533
534 const VTable* vtable_;
535 Buffer buffer_;
536};
537
538} // namespace internal
539
540// A Matcher<T> is a copyable and IMMUTABLE (except by assignment)
541// object that can check whether a value of type T matches. The
542// implementation of Matcher<T> is just a std::shared_ptr to const
543// MatcherInterface<T>. Don't inherit from Matcher!
544template <typename T>
545class Matcher : public internal::MatcherBase<T> {
546 public:
547 // Constructs a null matcher. Needed for storing Matcher objects in STL
548 // containers. A default-constructed matcher is not yet initialized. You
549 // cannot use it until a valid value has been assigned to it.
550 explicit Matcher() {} // NOLINT
551
552 // Constructs a matcher from its implementation.
553 explicit Matcher(const MatcherInterface<const T&>* impl)
554 : internal::MatcherBase<T>(impl) {}
555
556 template <typename U>
557 explicit Matcher(
558 const MatcherInterface<U>* impl,
559 typename std::enable_if<!std::is_same<U, const U&>::value>::type* =
560 nullptr)
561 : internal::MatcherBase<T>(impl) {}
562
563 template <typename M, typename = typename std::remove_reference<
564 M>::type::is_gtest_matcher>
565 Matcher(M&& m) : internal::MatcherBase<T>(std::forward<M>(m)) {} // NOLINT
566
567 // Implicit constructor here allows people to write
568 // EXPECT_CALL(foo, Bar(5)) instead of EXPECT_CALL(foo, Bar(Eq(5))) sometimes
569 Matcher(T value); // NOLINT
570};
571
572// The following two specializations allow the user to write str
573// instead of Eq(str) and "foo" instead of Eq("foo") when a std::string
574// matcher is expected.
575template <>
576class GTEST_API_ Matcher<const std::string&>
577 : public internal::MatcherBase<const std::string&> {
578 public:
579 Matcher() {}
580
581 explicit Matcher(const MatcherInterface<const std::string&>* impl)
582 : internal::MatcherBase<const std::string&>(impl) {}
583
584 template <typename M, typename = typename std::remove_reference<
585 M>::type::is_gtest_matcher>
586 Matcher(M&& m) // NOLINT
587 : internal::MatcherBase<const std::string&>(std::forward<M>(m)) {}
588
589 // Allows the user to write str instead of Eq(str) sometimes, where
590 // str is a std::string object.
591 Matcher(const std::string& s); // NOLINT
592
593 // Allows the user to write "foo" instead of Eq("foo") sometimes.
594 Matcher(const char* s); // NOLINT
595};
596
597template <>
598class GTEST_API_ Matcher<std::string>
599 : public internal::MatcherBase<std::string> {
600 public:
601 Matcher() {}
602
603 explicit Matcher(const MatcherInterface<const std::string&>* impl)
604 : internal::MatcherBase<std::string>(impl) {}
605 explicit Matcher(const MatcherInterface<std::string>* impl)
606 : internal::MatcherBase<std::string>(impl) {}
607
608 template <typename M, typename = typename std::remove_reference<
609 M>::type::is_gtest_matcher>
610 Matcher(M&& m) // NOLINT
611 : internal::MatcherBase<std::string>(std::forward<M>(m)) {}
612
613 // Allows the user to write str instead of Eq(str) sometimes, where
614 // str is a string object.
615 Matcher(const std::string& s); // NOLINT
616
617 // Allows the user to write "foo" instead of Eq("foo") sometimes.
618 Matcher(const char* s); // NOLINT
619};
620
621#if GTEST_INTERNAL_HAS_STRING_VIEW
622// The following two specializations allow the user to write str
623// instead of Eq(str) and "foo" instead of Eq("foo") when a absl::string_view
624// matcher is expected.
625template <>
626class GTEST_API_ Matcher<const internal::StringView&>
627 : public internal::MatcherBase<const internal::StringView&> {
628 public:
629 Matcher() {}
630
631 explicit Matcher(const MatcherInterface<const internal::StringView&>* impl)
632 : internal::MatcherBase<const internal::StringView&>(impl) {}
633
634 template <typename M, typename = typename std::remove_reference<
635 M>::type::is_gtest_matcher>
636 Matcher(M&& m) // NOLINT
637 : internal::MatcherBase<const internal::StringView&>(std::forward<M>(m)) {
638 }
639
640 // Allows the user to write str instead of Eq(str) sometimes, where
641 // str is a std::string object.
642 Matcher(const std::string& s); // NOLINT
643
644 // Allows the user to write "foo" instead of Eq("foo") sometimes.
645 Matcher(const char* s); // NOLINT
646
647 // Allows the user to pass absl::string_views or std::string_views directly.
648 Matcher(internal::StringView s); // NOLINT
649};
650
651template <>
652class GTEST_API_ Matcher<internal::StringView>
653 : public internal::MatcherBase<internal::StringView> {
654 public:
655 Matcher() {}
656
657 explicit Matcher(const MatcherInterface<const internal::StringView&>* impl)
658 : internal::MatcherBase<internal::StringView>(impl) {}
659 explicit Matcher(const MatcherInterface<internal::StringView>* impl)
660 : internal::MatcherBase<internal::StringView>(impl) {}
661
662 template <typename M, typename = typename std::remove_reference<
663 M>::type::is_gtest_matcher>
664 Matcher(M&& m) // NOLINT
665 : internal::MatcherBase<internal::StringView>(std::forward<M>(m)) {}
666
667 // Allows the user to write str instead of Eq(str) sometimes, where
668 // str is a std::string object.
669 Matcher(const std::string& s); // NOLINT
670
671 // Allows the user to write "foo" instead of Eq("foo") sometimes.
672 Matcher(const char* s); // NOLINT
673
674 // Allows the user to pass absl::string_views or std::string_views directly.
675 Matcher(internal::StringView s); // NOLINT
676};
677#endif // GTEST_INTERNAL_HAS_STRING_VIEW
678
679// Prints a matcher in a human-readable format.
680template <typename T>
681std::ostream& operator<<(std::ostream& os, const Matcher<T>& matcher) {
682 matcher.DescribeTo(&os);
683 return os;
684}
685
686// The PolymorphicMatcher class template makes it easy to implement a
687// polymorphic matcher (i.e. a matcher that can match values of more
688// than one type, e.g. Eq(n) and NotNull()).
689//
690// To define a polymorphic matcher, a user should provide an Impl
691// class that has a DescribeTo() method and a DescribeNegationTo()
692// method, and define a member function (or member function template)
693//
694// bool MatchAndExplain(const Value& value,
695// MatchResultListener* listener) const;
696//
697// See the definition of NotNull() for a complete example.
698template <class Impl>
699class PolymorphicMatcher {
700 public:
701 explicit PolymorphicMatcher(const Impl& an_impl) : impl_(an_impl) {}
702
703 // Returns a mutable reference to the underlying matcher
704 // implementation object.
705 Impl& mutable_impl() { return impl_; }
706
707 // Returns an immutable reference to the underlying matcher
708 // implementation object.
709 const Impl& impl() const { return impl_; }
710
711 template <typename T>
712 operator Matcher<T>() const {
713 return Matcher<T>(new MonomorphicImpl<const T&>(impl_));
714 }
715
716 private:
717 template <typename T>
718 class MonomorphicImpl : public MatcherInterface<T> {
719 public:
720 explicit MonomorphicImpl(const Impl& impl) : impl_(impl) {}
721
722 void DescribeTo(::std::ostream* os) const override { impl_.DescribeTo(os); }
723
724 void DescribeNegationTo(::std::ostream* os) const override {
725 impl_.DescribeNegationTo(os);
726 }
727
728 bool MatchAndExplain(T x, MatchResultListener* listener) const override {
729 return impl_.MatchAndExplain(x, listener);
730 }
731
732 private:
733 const Impl impl_;
734 };
735
736 Impl impl_;
737};
738
739// Creates a matcher from its implementation.
740// DEPRECATED: Especially in the generic code, prefer:
741// Matcher<T>(new MyMatcherImpl<const T&>(...));
742//
743// MakeMatcher may create a Matcher that accepts its argument by value, which
744// leads to unnecessary copies & lack of support for non-copyable types.
745template <typename T>
746inline Matcher<T> MakeMatcher(const MatcherInterface<T>* impl) {
747 return Matcher<T>(impl);
748}
749
750// Creates a polymorphic matcher from its implementation. This is
751// easier to use than the PolymorphicMatcher<Impl> constructor as it
752// doesn't require you to explicitly write the template argument, e.g.
753//
754// MakePolymorphicMatcher(foo);
755// vs
756// PolymorphicMatcher<TypeOfFoo>(foo);
757template <class Impl>
758inline PolymorphicMatcher<Impl> MakePolymorphicMatcher(const Impl& impl) {
759 return PolymorphicMatcher<Impl>(impl);
760}
761
762namespace internal {
763// Implements a matcher that compares a given value with a
764// pre-supplied value using one of the ==, <=, <, etc, operators. The
765// two values being compared don't have to have the same type.
766//
767// The matcher defined here is polymorphic (for example, Eq(5) can be
768// used to match an int, a short, a double, etc). Therefore we use
769// a template type conversion operator in the implementation.
770//
771// The following template definition assumes that the Rhs parameter is
772// a "bare" type (i.e. neither 'const T' nor 'T&').
773template <typename D, typename Rhs, typename Op>
774class ComparisonBase {
775 public:
776 explicit ComparisonBase(const Rhs& rhs) : rhs_(rhs) {}
777
778 using is_gtest_matcher = void;
779
780 template <typename Lhs>
781 bool MatchAndExplain(const Lhs& lhs, std::ostream*) const {
782 return Op()(lhs, Unwrap(rhs_));
783 }
784 void DescribeTo(std::ostream* os) const {
785 *os << D::Desc() << " ";
786 UniversalPrint(Unwrap(rhs_), os);
787 }
788 void DescribeNegationTo(std::ostream* os) const {
789 *os << D::NegatedDesc() << " ";
790 UniversalPrint(Unwrap(rhs_), os);
791 }
792
793 private:
794 template <typename T>
795 static const T& Unwrap(const T& v) {
796 return v;
797 }
798 template <typename T>
799 static const T& Unwrap(std::reference_wrapper<T> v) {
800 return v;
801 }
802
803 Rhs rhs_;
804};
805
806template <typename Rhs>
807class EqMatcher : public ComparisonBase<EqMatcher<Rhs>, Rhs, AnyEq> {
808 public:
809 explicit EqMatcher(const Rhs& rhs)
810 : ComparisonBase<EqMatcher<Rhs>, Rhs, AnyEq>(rhs) { }
811 static const char* Desc() { return "is equal to"; }
812 static const char* NegatedDesc() { return "isn't equal to"; }
813};
814template <typename Rhs>
815class NeMatcher : public ComparisonBase<NeMatcher<Rhs>, Rhs, AnyNe> {
816 public:
817 explicit NeMatcher(const Rhs& rhs)
818 : ComparisonBase<NeMatcher<Rhs>, Rhs, AnyNe>(rhs) { }
819 static const char* Desc() { return "isn't equal to"; }
820 static const char* NegatedDesc() { return "is equal to"; }
821};
822template <typename Rhs>
823class LtMatcher : public ComparisonBase<LtMatcher<Rhs>, Rhs, AnyLt> {
824 public:
825 explicit LtMatcher(const Rhs& rhs)
826 : ComparisonBase<LtMatcher<Rhs>, Rhs, AnyLt>(rhs) { }
827 static const char* Desc() { return "is <"; }
828 static const char* NegatedDesc() { return "isn't <"; }
829};
830template <typename Rhs>
831class GtMatcher : public ComparisonBase<GtMatcher<Rhs>, Rhs, AnyGt> {
832 public:
833 explicit GtMatcher(const Rhs& rhs)
834 : ComparisonBase<GtMatcher<Rhs>, Rhs, AnyGt>(rhs) { }
835 static const char* Desc() { return "is >"; }
836 static const char* NegatedDesc() { return "isn't >"; }
837};
838template <typename Rhs>
839class LeMatcher : public ComparisonBase<LeMatcher<Rhs>, Rhs, AnyLe> {
840 public:
841 explicit LeMatcher(const Rhs& rhs)
842 : ComparisonBase<LeMatcher<Rhs>, Rhs, AnyLe>(rhs) { }
843 static const char* Desc() { return "is <="; }
844 static const char* NegatedDesc() { return "isn't <="; }
845};
846template <typename Rhs>
847class GeMatcher : public ComparisonBase<GeMatcher<Rhs>, Rhs, AnyGe> {
848 public:
849 explicit GeMatcher(const Rhs& rhs)
850 : ComparisonBase<GeMatcher<Rhs>, Rhs, AnyGe>(rhs) { }
851 static const char* Desc() { return "is >="; }
852 static const char* NegatedDesc() { return "isn't >="; }
853};
854
855template <typename T, typename = typename std::enable_if<
856 std::is_constructible<std::string, T>::value>::type>
857using StringLike = T;
858
859// Implements polymorphic matchers MatchesRegex(regex) and
860// ContainsRegex(regex), which can be used as a Matcher<T> as long as
861// T can be converted to a string.
862class MatchesRegexMatcher {
863 public:
864 MatchesRegexMatcher(const RE* regex, bool full_match)
865 : regex_(regex), full_match_(full_match) {}
866
867#if GTEST_INTERNAL_HAS_STRING_VIEW
868 bool MatchAndExplain(const internal::StringView& s,
869 MatchResultListener* listener) const {
870 return MatchAndExplain(std::string(s), listener);
871 }
872#endif // GTEST_INTERNAL_HAS_STRING_VIEW
873
874 // Accepts pointer types, particularly:
875 // const char*
876 // char*
877 // const wchar_t*
878 // wchar_t*
879 template <typename CharType>
880 bool MatchAndExplain(CharType* s, MatchResultListener* listener) const {
881 return s != nullptr && MatchAndExplain(std::string(s), listener);
882 }
883
884 // Matches anything that can convert to std::string.
885 //
886 // This is a template, not just a plain function with const std::string&,
887 // because absl::string_view has some interfering non-explicit constructors.
888 template <class MatcheeStringType>
889 bool MatchAndExplain(const MatcheeStringType& s,
890 MatchResultListener* /* listener */) const {
891 const std::string& s2(s);
892 return full_match_ ? RE::FullMatch(s2, *regex_)
893 : RE::PartialMatch(s2, *regex_);
894 }
895
896 void DescribeTo(::std::ostream* os) const {
897 *os << (full_match_ ? "matches" : "contains") << " regular expression ";
898 UniversalPrinter<std::string>::Print(regex_->pattern(), os);
899 }
900
901 void DescribeNegationTo(::std::ostream* os) const {
902 *os << "doesn't " << (full_match_ ? "match" : "contain")
903 << " regular expression ";
904 UniversalPrinter<std::string>::Print(regex_->pattern(), os);
905 }
906
907 private:
908 const std::shared_ptr<const RE> regex_;
909 const bool full_match_;
910};
911} // namespace internal
912
913// Matches a string that fully matches regular expression 'regex'.
914// The matcher takes ownership of 'regex'.
915inline PolymorphicMatcher<internal::MatchesRegexMatcher> MatchesRegex(
916 const internal::RE* regex) {
917 return MakePolymorphicMatcher(internal::MatchesRegexMatcher(regex, true));
918}
919template <typename T = std::string>
920PolymorphicMatcher<internal::MatchesRegexMatcher> MatchesRegex(
921 const internal::StringLike<T>& regex) {
922 return MatchesRegex(new internal::RE(std::string(regex)));
923}
924
925// Matches a string that contains regular expression 'regex'.
926// The matcher takes ownership of 'regex'.
927inline PolymorphicMatcher<internal::MatchesRegexMatcher> ContainsRegex(
928 const internal::RE* regex) {
929 return MakePolymorphicMatcher(internal::MatchesRegexMatcher(regex, false));
930}
931template <typename T = std::string>
932PolymorphicMatcher<internal::MatchesRegexMatcher> ContainsRegex(
933 const internal::StringLike<T>& regex) {
934 return ContainsRegex(new internal::RE(std::string(regex)));
935}
936
937// Creates a polymorphic matcher that matches anything equal to x.
938// Note: if the parameter of Eq() were declared as const T&, Eq("foo")
939// wouldn't compile.
940template <typename T>
941inline internal::EqMatcher<T> Eq(T x) { return internal::EqMatcher<T>(x); }
942
943// Constructs a Matcher<T> from a 'value' of type T. The constructed
944// matcher matches any value that's equal to 'value'.
945template <typename T>
946Matcher<T>::Matcher(T value) { *this = Eq(value); }
947
948// Creates a monomorphic matcher that matches anything with type Lhs
949// and equal to rhs. A user may need to use this instead of Eq(...)
950// in order to resolve an overloading ambiguity.
951//
952// TypedEq<T>(x) is just a convenient short-hand for Matcher<T>(Eq(x))
953// or Matcher<T>(x), but more readable than the latter.
954//
955// We could define similar monomorphic matchers for other comparison
956// operations (e.g. TypedLt, TypedGe, and etc), but decided not to do
957// it yet as those are used much less than Eq() in practice. A user
958// can always write Matcher<T>(Lt(5)) to be explicit about the type,
959// for example.
960template <typename Lhs, typename Rhs>
961inline Matcher<Lhs> TypedEq(const Rhs& rhs) { return Eq(rhs); }
962
963// Creates a polymorphic matcher that matches anything >= x.
964template <typename Rhs>
965inline internal::GeMatcher<Rhs> Ge(Rhs x) {
966 return internal::GeMatcher<Rhs>(x);
967}
968
969// Creates a polymorphic matcher that matches anything > x.
970template <typename Rhs>
971inline internal::GtMatcher<Rhs> Gt(Rhs x) {
972 return internal::GtMatcher<Rhs>(x);
973}
974
975// Creates a polymorphic matcher that matches anything <= x.
976template <typename Rhs>
977inline internal::LeMatcher<Rhs> Le(Rhs x) {
978 return internal::LeMatcher<Rhs>(x);
979}
980
981// Creates a polymorphic matcher that matches anything < x.
982template <typename Rhs>
983inline internal::LtMatcher<Rhs> Lt(Rhs x) {
984 return internal::LtMatcher<Rhs>(x);
985}
986
987// Creates a polymorphic matcher that matches anything != x.
988template <typename Rhs>
989inline internal::NeMatcher<Rhs> Ne(Rhs x) {
990 return internal::NeMatcher<Rhs>(x);
991}
992} // namespace testing
993
994GTEST_DISABLE_MSC_WARNINGS_POP_() // 4251 5046
995
996#endif // GOOGLETEST_INCLUDE_GTEST_GTEST_MATCHERS_H_
997