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 31// Google Mock - a framework for writing C++ mock classes. 32// 33// This file implements Matcher<const string&>, Matcher<string>, and 34// utilities for defining matchers. 35 36#include "gmock/gmock-matchers.h" 37#include "gmock/gmock-generated-matchers.h" 38 39#include <string.h> 40#include <iostream> 41#include <sstream> 42#include <string> 43 44namespace testing { 45 46// Constructs a matcher that matches a const std::string& whose value is 47// equal to s. 48Matcher<const std::string&>::Matcher(const std::string& s) { *this = Eq(s); } 49 50#if GTEST_HAS_GLOBAL_STRING 51// Constructs a matcher that matches a const std::string& whose value is 52// equal to s. 53Matcher<const std::string&>::Matcher(const ::string& s) { 54 *this = Eq(static_cast<std::string>(s)); 55} 56#endif // GTEST_HAS_GLOBAL_STRING 57 58// Constructs a matcher that matches a const std::string& whose value is 59// equal to s. 60Matcher<const std::string&>::Matcher(const char* s) { 61 *this = Eq(std::string(s)); 62} 63 64// Constructs a matcher that matches a std::string whose value is equal to 65// s. 66Matcher<std::string>::Matcher(const std::string& s) { *this = Eq(s); } 67 68#if GTEST_HAS_GLOBAL_STRING 69// Constructs a matcher that matches a std::string whose value is equal to 70// s. 71Matcher<std::string>::Matcher(const ::string& s) { 72 *this = Eq(static_cast<std::string>(s)); 73} 74#endif // GTEST_HAS_GLOBAL_STRING 75 76// Constructs a matcher that matches a std::string whose value is equal to 77// s. 78Matcher<std::string>::Matcher(const char* s) { *this = Eq(std::string(s)); } 79 80#if GTEST_HAS_GLOBAL_STRING 81// Constructs a matcher that matches a const ::string& whose value is 82// equal to s. 83Matcher<const ::string&>::Matcher(const std::string& s) { 84 *this = Eq(static_cast<::string>(s)); 85} 86 87// Constructs a matcher that matches a const ::string& whose value is 88// equal to s. 89Matcher<const ::string&>::Matcher(const ::string& s) { *this = Eq(s); } 90 91// Constructs a matcher that matches a const ::string& whose value is 92// equal to s. 93Matcher<const ::string&>::Matcher(const char* s) { *this = Eq(::string(s)); } 94 95// Constructs a matcher that matches a ::string whose value is equal to s. 96Matcher<::string>::Matcher(const std::string& s) { 97 *this = Eq(static_cast<::string>(s)); 98} 99 100// Constructs a matcher that matches a ::string whose value is equal to s. 101Matcher<::string>::Matcher(const ::string& s) { *this = Eq(s); } 102 103// Constructs a matcher that matches a string whose value is equal to s. 104Matcher<::string>::Matcher(const char* s) { *this = Eq(::string(s)); } 105#endif // GTEST_HAS_GLOBAL_STRING 106 107#if GTEST_HAS_ABSL 108// Constructs a matcher that matches a const absl::string_view& whose value is 109// equal to s. 110Matcher<const absl::string_view&>::Matcher(const std::string& s) { 111 *this = Eq(s); 112} 113 114#if GTEST_HAS_GLOBAL_STRING 115// Constructs a matcher that matches a const absl::string_view& whose value is 116// equal to s. 117Matcher<const absl::string_view&>::Matcher(const ::string& s) { *this = Eq(s); } 118#endif // GTEST_HAS_GLOBAL_STRING 119 120// Constructs a matcher that matches a const absl::string_view& whose value is 121// equal to s. 122Matcher<const absl::string_view&>::Matcher(const char* s) { 123 *this = Eq(std::string(s)); 124} 125 126// Constructs a matcher that matches a const absl::string_view& whose value is 127// equal to s. 128Matcher<const absl::string_view&>::Matcher(absl::string_view s) { 129 *this = Eq(std::string(s)); 130} 131 132// Constructs a matcher that matches a absl::string_view whose value is equal to 133// s. 134Matcher<absl::string_view>::Matcher(const std::string& s) { *this = Eq(s); } 135 136#if GTEST_HAS_GLOBAL_STRING 137// Constructs a matcher that matches a absl::string_view whose value is equal to 138// s. 139Matcher<absl::string_view>::Matcher(const ::string& s) { *this = Eq(s); } 140#endif // GTEST_HAS_GLOBAL_STRING 141 142// Constructs a matcher that matches a absl::string_view whose value is equal to 143// s. 144Matcher<absl::string_view>::Matcher(const char* s) { 145 *this = Eq(std::string(s)); 146} 147 148// Constructs a matcher that matches a absl::string_view whose value is equal to 149// s. 150Matcher<absl::string_view>::Matcher(absl::string_view s) { 151 *this = Eq(std::string(s)); 152} 153#endif // GTEST_HAS_ABSL 154 155namespace internal { 156 157// Returns the description for a matcher defined using the MATCHER*() 158// macro where the user-supplied description string is "", if 159// 'negation' is false; otherwise returns the description of the 160// negation of the matcher. 'param_values' contains a list of strings 161// that are the print-out of the matcher's parameters. 162GTEST_API_ std::string FormatMatcherDescription(bool negation, 163 const char* matcher_name, 164 const Strings& param_values) { 165 std::string result = ConvertIdentifierNameToWords(matcher_name); 166 if (param_values.size() >= 1) result += " " + JoinAsTuple(param_values); 167 return negation ? "not (" + result + ")" : result; 168} 169 170// FindMaxBipartiteMatching and its helper class. 171// 172// Uses the well-known Ford-Fulkerson max flow method to find a maximum 173// bipartite matching. Flow is considered to be from left to right. 174// There is an implicit source node that is connected to all of the left 175// nodes, and an implicit sink node that is connected to all of the 176// right nodes. All edges have unit capacity. 177// 178// Neither the flow graph nor the residual flow graph are represented 179// explicitly. Instead, they are implied by the information in 'graph' and 180// a vector<int> called 'left_' whose elements are initialized to the 181// value kUnused. This represents the initial state of the algorithm, 182// where the flow graph is empty, and the residual flow graph has the 183// following edges: 184// - An edge from source to each left_ node 185// - An edge from each right_ node to sink 186// - An edge from each left_ node to each right_ node, if the 187// corresponding edge exists in 'graph'. 188// 189// When the TryAugment() method adds a flow, it sets left_[l] = r for some 190// nodes l and r. This induces the following changes: 191// - The edges (source, l), (l, r), and (r, sink) are added to the 192// flow graph. 193// - The same three edges are removed from the residual flow graph. 194// - The reverse edges (l, source), (r, l), and (sink, r) are added 195// to the residual flow graph, which is a directional graph 196// representing unused flow capacity. 197// 198// When the method augments a flow (moving left_[l] from some r1 to some 199// other r2), this can be thought of as "undoing" the above steps with 200// respect to r1 and "redoing" them with respect to r2. 201// 202// It bears repeating that the flow graph and residual flow graph are 203// never represented explicitly, but can be derived by looking at the 204// information in 'graph' and in left_. 205// 206// As an optimization, there is a second vector<int> called right_ which 207// does not provide any new information. Instead, it enables more 208// efficient queries about edges entering or leaving the right-side nodes 209// of the flow or residual flow graphs. The following invariants are 210// maintained: 211// 212// left[l] == kUnused or right[left[l]] == l 213// right[r] == kUnused or left[right[r]] == r 214// 215// . [ source ] . 216// . ||| . 217// . ||| . 218// . ||\--> left[0]=1 ---\ right[0]=-1 ----\ . 219// . || | | . 220// . |\---> left[1]=-1 \--> right[1]=0 ---\| . 221// . | || . 222// . \----> left[2]=2 ------> right[2]=2 --\|| . 223// . ||| . 224// . elements matchers vvv . 225// . [ sink ] . 226// 227// See Also: 228// [1] Cormen, et al (2001). "Section 26.2: The Ford-Fulkerson method". 229// "Introduction to Algorithms (Second ed.)", pp. 651-664. 230// [2] "Ford-Fulkerson algorithm", Wikipedia, 231// 'http://en.wikipedia.org/wiki/Ford%E2%80%93Fulkerson_algorithm' 232class MaxBipartiteMatchState { 233 public: 234 explicit MaxBipartiteMatchState(const MatchMatrix& graph) 235 : graph_(&graph), 236 left_(graph_->LhsSize(), kUnused), 237 right_(graph_->RhsSize(), kUnused) {} 238 239 // Returns the edges of a maximal match, each in the form {left, right}. 240 ElementMatcherPairs Compute() { 241 // 'seen' is used for path finding { 0: unseen, 1: seen }. 242 ::std::vector<char> seen; 243 // Searches the residual flow graph for a path from each left node to 244 // the sink in the residual flow graph, and if one is found, add flow 245 // to the graph. It's okay to search through the left nodes once. The 246 // edge from the implicit source node to each previously-visited left 247 // node will have flow if that left node has any path to the sink 248 // whatsoever. Subsequent augmentations can only add flow to the 249 // network, and cannot take away that previous flow unit from the source. 250 // Since the source-to-left edge can only carry one flow unit (or, 251 // each element can be matched to only one matcher), there is no need 252 // to visit the left nodes more than once looking for augmented paths. 253 // The flow is known to be possible or impossible by looking at the 254 // node once. 255 for (size_t ilhs = 0; ilhs < graph_->LhsSize(); ++ilhs) { 256 // Reset the path-marking vector and try to find a path from 257 // source to sink starting at the left_[ilhs] node. 258 GTEST_CHECK_(left_[ilhs] == kUnused) 259 << "ilhs: " << ilhs << ", left_[ilhs]: " << left_[ilhs]; 260 // 'seen' initialized to 'graph_->RhsSize()' copies of 0. 261 seen.assign(graph_->RhsSize(), 0); 262 TryAugment(ilhs, &seen); 263 } 264 ElementMatcherPairs result; 265 for (size_t ilhs = 0; ilhs < left_.size(); ++ilhs) { 266 size_t irhs = left_[ilhs]; 267 if (irhs == kUnused) continue; 268 result.push_back(ElementMatcherPair(ilhs, irhs)); 269 } 270 return result; 271 } 272 273 private: 274 static const size_t kUnused = static_cast<size_t>(-1); 275 276 // Perform a depth-first search from left node ilhs to the sink. If a 277 // path is found, flow is added to the network by linking the left and 278 // right vector elements corresponding each segment of the path. 279 // Returns true if a path to sink was found, which means that a unit of 280 // flow was added to the network. The 'seen' vector elements correspond 281 // to right nodes and are marked to eliminate cycles from the search. 282 // 283 // Left nodes will only be explored at most once because they 284 // are accessible from at most one right node in the residual flow 285 // graph. 286 // 287 // Note that left_[ilhs] is the only element of left_ that TryAugment will 288 // potentially transition from kUnused to another value. Any other 289 // left_ element holding kUnused before TryAugment will be holding it 290 // when TryAugment returns. 291 // 292 bool TryAugment(size_t ilhs, ::std::vector<char>* seen) { 293 for (size_t irhs = 0; irhs < graph_->RhsSize(); ++irhs) { 294 if ((*seen)[irhs]) continue; 295 if (!graph_->HasEdge(ilhs, irhs)) continue; 296 // There's an available edge from ilhs to irhs. 297 (*seen)[irhs] = 1; 298 // Next a search is performed to determine whether 299 // this edge is a dead end or leads to the sink. 300 // 301 // right_[irhs] == kUnused means that there is residual flow from 302 // right node irhs to the sink, so we can use that to finish this 303 // flow path and return success. 304 // 305 // Otherwise there is residual flow to some ilhs. We push flow 306 // along that path and call ourselves recursively to see if this 307 // ultimately leads to sink. 308 if (right_[irhs] == kUnused || TryAugment(right_[irhs], seen)) { 309 // Add flow from left_[ilhs] to right_[irhs]. 310 left_[ilhs] = irhs; 311 right_[irhs] = ilhs; 312 return true; 313 } 314 } 315 return false; 316 } 317 318 const MatchMatrix* graph_; // not owned 319 // Each element of the left_ vector represents a left hand side node 320 // (i.e. an element) and each element of right_ is a right hand side 321 // node (i.e. a matcher). The values in the left_ vector indicate 322 // outflow from that node to a node on the right_ side. The values 323 // in the right_ indicate inflow, and specify which left_ node is 324 // feeding that right_ node, if any. For example, left_[3] == 1 means 325 // there's a flow from element #3 to matcher #1. Such a flow would also 326 // be redundantly represented in the right_ vector as right_[1] == 3. 327 // Elements of left_ and right_ are either kUnused or mutually 328 // referent. Mutually referent means that left_[right_[i]] = i and 329 // right_[left_[i]] = i. 330 ::std::vector<size_t> left_; 331 ::std::vector<size_t> right_; 332 333 GTEST_DISALLOW_ASSIGN_(MaxBipartiteMatchState); 334}; 335 336const size_t MaxBipartiteMatchState::kUnused; 337 338GTEST_API_ ElementMatcherPairs FindMaxBipartiteMatching(const MatchMatrix& g) { 339 return MaxBipartiteMatchState(g).Compute(); 340} 341 342static void LogElementMatcherPairVec(const ElementMatcherPairs& pairs, 343 ::std::ostream* stream) { 344 typedef ElementMatcherPairs::const_iterator Iter; 345 ::std::ostream& os = *stream; 346 os << "{"; 347 const char* sep = ""; 348 for (Iter it = pairs.begin(); it != pairs.end(); ++it) { 349 os << sep << "\n (" 350 << "element #" << it->first << ", " 351 << "matcher #" << it->second << ")"; 352 sep = ","; 353 } 354 os << "\n}"; 355} 356 357bool MatchMatrix::NextGraph() { 358 for (size_t ilhs = 0; ilhs < LhsSize(); ++ilhs) { 359 for (size_t irhs = 0; irhs < RhsSize(); ++irhs) { 360 char& b = matched_[SpaceIndex(ilhs, irhs)]; 361 if (!b) { 362 b = 1; 363 return true; 364 } 365 b = 0; 366 } 367 } 368 return false; 369} 370 371void MatchMatrix::Randomize() { 372 for (size_t ilhs = 0; ilhs < LhsSize(); ++ilhs) { 373 for (size_t irhs = 0; irhs < RhsSize(); ++irhs) { 374 char& b = matched_[SpaceIndex(ilhs, irhs)]; 375 b = static_cast<char>(rand() & 1); // NOLINT 376 } 377 } 378} 379 380std::string MatchMatrix::DebugString() const { 381 ::std::stringstream ss; 382 const char* sep = ""; 383 for (size_t i = 0; i < LhsSize(); ++i) { 384 ss << sep; 385 for (size_t j = 0; j < RhsSize(); ++j) { 386 ss << HasEdge(i, j); 387 } 388 sep = ";"; 389 } 390 return ss.str(); 391} 392 393void UnorderedElementsAreMatcherImplBase::DescribeToImpl( 394 ::std::ostream* os) const { 395 switch (match_flags()) { 396 case UnorderedMatcherRequire::ExactMatch: 397 if (matcher_describers_.empty()) { 398 *os << "is empty"; 399 return; 400 } 401 if (matcher_describers_.size() == 1) { 402 *os << "has " << Elements(1) << " and that element "; 403 matcher_describers_[0]->DescribeTo(os); 404 return; 405 } 406 *os << "has " << Elements(matcher_describers_.size()) 407 << " and there exists some permutation of elements such that:\n"; 408 break; 409 case UnorderedMatcherRequire::Superset: 410 *os << "a surjection from elements to requirements exists such that:\n"; 411 break; 412 case UnorderedMatcherRequire::Subset: 413 *os << "an injection from elements to requirements exists such that:\n"; 414 break; 415 } 416 417 const char* sep = ""; 418 for (size_t i = 0; i != matcher_describers_.size(); ++i) { 419 *os << sep; 420 if (match_flags() == UnorderedMatcherRequire::ExactMatch) { 421 *os << " - element #" << i << " "; 422 } else { 423 *os << " - an element "; 424 } 425 matcher_describers_[i]->DescribeTo(os); 426 if (match_flags() == UnorderedMatcherRequire::ExactMatch) { 427 sep = ", and\n"; 428 } else { 429 sep = "\n"; 430 } 431 } 432} 433 434void UnorderedElementsAreMatcherImplBase::DescribeNegationToImpl( 435 ::std::ostream* os) const { 436 switch (match_flags()) { 437 case UnorderedMatcherRequire::ExactMatch: 438 if (matcher_describers_.empty()) { 439 *os << "isn't empty"; 440 return; 441 } 442 if (matcher_describers_.size() == 1) { 443 *os << "doesn't have " << Elements(1) << ", or has " << Elements(1) 444 << " that "; 445 matcher_describers_[0]->DescribeNegationTo(os); 446 return; 447 } 448 *os << "doesn't have " << Elements(matcher_describers_.size()) 449 << ", or there exists no permutation of elements such that:\n"; 450 break; 451 case UnorderedMatcherRequire::Superset: 452 *os << "no surjection from elements to requirements exists such that:\n"; 453 break; 454 case UnorderedMatcherRequire::Subset: 455 *os << "no injection from elements to requirements exists such that:\n"; 456 break; 457 } 458 const char* sep = ""; 459 for (size_t i = 0; i != matcher_describers_.size(); ++i) { 460 *os << sep; 461 if (match_flags() == UnorderedMatcherRequire::ExactMatch) { 462 *os << " - element #" << i << " "; 463 } else { 464 *os << " - an element "; 465 } 466 matcher_describers_[i]->DescribeTo(os); 467 if (match_flags() == UnorderedMatcherRequire::ExactMatch) { 468 sep = ", and\n"; 469 } else { 470 sep = "\n"; 471 } 472 } 473} 474 475// Checks that all matchers match at least one element, and that all 476// elements match at least one matcher. This enables faster matching 477// and better error reporting. 478// Returns false, writing an explanation to 'listener', if and only 479// if the success criteria are not met. 480bool UnorderedElementsAreMatcherImplBase::VerifyMatchMatrix( 481 const ::std::vector<std::string>& element_printouts, 482 const MatchMatrix& matrix, MatchResultListener* listener) const { 483 bool result = true; 484 ::std::vector<char> element_matched(matrix.LhsSize(), 0); 485 ::std::vector<char> matcher_matched(matrix.RhsSize(), 0); 486 487 for (size_t ilhs = 0; ilhs < matrix.LhsSize(); ilhs++) { 488 for (size_t irhs = 0; irhs < matrix.RhsSize(); irhs++) { 489 char matched = matrix.HasEdge(ilhs, irhs); 490 element_matched[ilhs] |= matched; 491 matcher_matched[irhs] |= matched; 492 } 493 } 494 495 if (match_flags() & UnorderedMatcherRequire::Superset) { 496 const char* sep = 497 "where the following matchers don't match any elements:\n"; 498 for (size_t mi = 0; mi < matcher_matched.size(); ++mi) { 499 if (matcher_matched[mi]) continue; 500 result = false; 501 if (listener->IsInterested()) { 502 *listener << sep << "matcher #" << mi << ": "; 503 matcher_describers_[mi]->DescribeTo(listener->stream()); 504 sep = ",\n"; 505 } 506 } 507 } 508 509 if (match_flags() & UnorderedMatcherRequire::Subset) { 510 const char* sep = 511 "where the following elements don't match any matchers:\n"; 512 const char* outer_sep = ""; 513 if (!result) { 514 outer_sep = "\nand "; 515 } 516 for (size_t ei = 0; ei < element_matched.size(); ++ei) { 517 if (element_matched[ei]) continue; 518 result = false; 519 if (listener->IsInterested()) { 520 *listener << outer_sep << sep << "element #" << ei << ": " 521 << element_printouts[ei]; 522 sep = ",\n"; 523 outer_sep = ""; 524 } 525 } 526 } 527 return result; 528} 529 530bool UnorderedElementsAreMatcherImplBase::FindPairing( 531 const MatchMatrix& matrix, MatchResultListener* listener) const { 532 ElementMatcherPairs matches = FindMaxBipartiteMatching(matrix); 533 534 size_t max_flow = matches.size(); 535 if ((match_flags() & UnorderedMatcherRequire::Superset) && 536 max_flow < matrix.RhsSize()) { 537 if (listener->IsInterested()) { 538 *listener << "where no permutation of the elements can satisfy all " 539 "matchers, and the closest match is " 540 << max_flow << " of " << matrix.RhsSize() 541 << " matchers with the pairings:\n"; 542 LogElementMatcherPairVec(matches, listener->stream()); 543 } 544 return false; 545 } 546 if ((match_flags() & UnorderedMatcherRequire::Subset) && 547 max_flow < matrix.LhsSize()) { 548 if (listener->IsInterested()) { 549 *listener 550 << "where not all elements can be matched, and the closest match is " 551 << max_flow << " of " << matrix.RhsSize() 552 << " matchers with the pairings:\n"; 553 LogElementMatcherPairVec(matches, listener->stream()); 554 } 555 return false; 556 } 557 558 if (matches.size() > 1) { 559 if (listener->IsInterested()) { 560 const char* sep = "where:\n"; 561 for (size_t mi = 0; mi < matches.size(); ++mi) { 562 *listener << sep << " - element #" << matches[mi].first 563 << " is matched by matcher #" << matches[mi].second; 564 sep = ",\n"; 565 } 566 } 567 } 568 return true; 569} 570 571} // namespace internal 572} // namespace testing 573