480 lines · plain
1// Copyright 2007, Google Inc.2// All rights reserved.3//4// Redistribution and use in source and binary forms, with or without5// modification, are permitted provided that the following conditions are6// met:7//8// * Redistributions of source code must retain the above copyright9// notice, this list of conditions and the following disclaimer.10// * Redistributions in binary form must reproduce the above11// copyright notice, this list of conditions and the following disclaimer12// in the documentation and/or other materials provided with the13// distribution.14// * Neither the name of Google Inc. nor the names of its15// contributors may be used to endorse or promote products derived from16// this software without specific prior written permission.17//18// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS19// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT20// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR21// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT22// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,23// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT24// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,25// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY26// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT27// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE28// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.29 30// Google Mock - a framework for writing C++ mock classes.31//32// This file implements Matcher<const string&>, Matcher<string>, and33// utilities for defining matchers.34 35#include "gmock/gmock-matchers.h"36 37#include <string.h>38 39#include <iostream>40#include <sstream>41#include <string>42#include <vector>43 44namespace testing {45namespace internal {46 47// Returns the description for a matcher defined using the MATCHER*()48// macro where the user-supplied description string is "", if49// 'negation' is false; otherwise returns the description of the50// negation of the matcher. 'param_values' contains a list of strings51// that are the print-out of the matcher's parameters.52GTEST_API_ std::string FormatMatcherDescription(53 bool negation, const char* matcher_name,54 const std::vector<const char*>& param_names, const Strings& param_values) {55 std::string result = ConvertIdentifierNameToWords(matcher_name);56 if (!param_values.empty()) {57 result += " " + JoinAsKeyValueTuple(param_names, param_values);58 }59 return negation ? "not (" + result + ")" : result;60}61 62// FindMaxBipartiteMatching and its helper class.63//64// Uses the well-known Ford-Fulkerson max flow method to find a maximum65// bipartite matching. Flow is considered to be from left to right.66// There is an implicit source node that is connected to all of the left67// nodes, and an implicit sink node that is connected to all of the68// right nodes. All edges have unit capacity.69//70// Neither the flow graph nor the residual flow graph are represented71// explicitly. Instead, they are implied by the information in 'graph' and72// a vector<int> called 'left_' whose elements are initialized to the73// value kUnused. This represents the initial state of the algorithm,74// where the flow graph is empty, and the residual flow graph has the75// following edges:76// - An edge from source to each left_ node77// - An edge from each right_ node to sink78// - An edge from each left_ node to each right_ node, if the79// corresponding edge exists in 'graph'.80//81// When the TryAugment() method adds a flow, it sets left_[l] = r for some82// nodes l and r. This induces the following changes:83// - The edges (source, l), (l, r), and (r, sink) are added to the84// flow graph.85// - The same three edges are removed from the residual flow graph.86// - The reverse edges (l, source), (r, l), and (sink, r) are added87// to the residual flow graph, which is a directional graph88// representing unused flow capacity.89//90// When the method augments a flow (moving left_[l] from some r1 to some91// other r2), this can be thought of as "undoing" the above steps with92// respect to r1 and "redoing" them with respect to r2.93//94// It bears repeating that the flow graph and residual flow graph are95// never represented explicitly, but can be derived by looking at the96// information in 'graph' and in left_.97//98// As an optimization, there is a second vector<int> called right_ which99// does not provide any new information. Instead, it enables more100// efficient queries about edges entering or leaving the right-side nodes101// of the flow or residual flow graphs. The following invariants are102// maintained:103//104// left[l] == kUnused or right[left[l]] == l105// right[r] == kUnused or left[right[r]] == r106//107// . [ source ] .108// . ||| .109// . ||| .110// . ||\--> left[0]=1 ---\ right[0]=-1 ----\ .111// . || | | .112// . |\---> left[1]=-1 \--> right[1]=0 ---\| .113// . | || .114// . \----> left[2]=2 ------> right[2]=2 --\|| .115// . ||| .116// . elements matchers vvv .117// . [ sink ] .118//119// See Also:120// [1] Cormen, et al (2001). "Section 26.2: The Ford-Fulkerson method".121// "Introduction to Algorithms (Second ed.)", pp. 651-664.122// [2] "Ford-Fulkerson algorithm", Wikipedia,123// 'http://en.wikipedia.org/wiki/Ford%E2%80%93Fulkerson_algorithm'124class MaxBipartiteMatchState {125 public:126 explicit MaxBipartiteMatchState(const MatchMatrix& graph)127 : graph_(&graph),128 left_(graph_->LhsSize(), kUnused),129 right_(graph_->RhsSize(), kUnused) {}130 131 // Returns the edges of a maximal match, each in the form {left, right}.132 ElementMatcherPairs Compute() {133 // 'seen' is used for path finding { 0: unseen, 1: seen }.134 ::std::vector<char> seen;135 // Searches the residual flow graph for a path from each left node to136 // the sink in the residual flow graph, and if one is found, add flow137 // to the graph. It's okay to search through the left nodes once. The138 // edge from the implicit source node to each previously-visited left139 // node will have flow if that left node has any path to the sink140 // whatsoever. Subsequent augmentations can only add flow to the141 // network, and cannot take away that previous flow unit from the source.142 // Since the source-to-left edge can only carry one flow unit (or,143 // each element can be matched to only one matcher), there is no need144 // to visit the left nodes more than once looking for augmented paths.145 // The flow is known to be possible or impossible by looking at the146 // node once.147 for (size_t ilhs = 0; ilhs < graph_->LhsSize(); ++ilhs) {148 // Reset the path-marking vector and try to find a path from149 // source to sink starting at the left_[ilhs] node.150 GTEST_CHECK_(left_[ilhs] == kUnused)151 << "ilhs: " << ilhs << ", left_[ilhs]: " << left_[ilhs];152 // 'seen' initialized to 'graph_->RhsSize()' copies of 0.153 seen.assign(graph_->RhsSize(), 0);154 TryAugment(ilhs, &seen);155 }156 ElementMatcherPairs result;157 for (size_t ilhs = 0; ilhs < left_.size(); ++ilhs) {158 size_t irhs = left_[ilhs];159 if (irhs == kUnused) continue;160 result.push_back(ElementMatcherPair(ilhs, irhs));161 }162 return result;163 }164 165 private:166 static const size_t kUnused = static_cast<size_t>(-1);167 168 // Perform a depth-first search from left node ilhs to the sink. If a169 // path is found, flow is added to the network by linking the left and170 // right vector elements corresponding each segment of the path.171 // Returns true if a path to sink was found, which means that a unit of172 // flow was added to the network. The 'seen' vector elements correspond173 // to right nodes and are marked to eliminate cycles from the search.174 //175 // Left nodes will only be explored at most once because they176 // are accessible from at most one right node in the residual flow177 // graph.178 //179 // Note that left_[ilhs] is the only element of left_ that TryAugment will180 // potentially transition from kUnused to another value. Any other181 // left_ element holding kUnused before TryAugment will be holding it182 // when TryAugment returns.183 //184 bool TryAugment(size_t ilhs, ::std::vector<char>* seen) {185 for (size_t irhs = 0; irhs < graph_->RhsSize(); ++irhs) {186 if ((*seen)[irhs]) continue;187 if (!graph_->HasEdge(ilhs, irhs)) continue;188 // There's an available edge from ilhs to irhs.189 (*seen)[irhs] = 1;190 // Next a search is performed to determine whether191 // this edge is a dead end or leads to the sink.192 //193 // right_[irhs] == kUnused means that there is residual flow from194 // right node irhs to the sink, so we can use that to finish this195 // flow path and return success.196 //197 // Otherwise there is residual flow to some ilhs. We push flow198 // along that path and call ourselves recursively to see if this199 // ultimately leads to sink.200 if (right_[irhs] == kUnused || TryAugment(right_[irhs], seen)) {201 // Add flow from left_[ilhs] to right_[irhs].202 left_[ilhs] = irhs;203 right_[irhs] = ilhs;204 return true;205 }206 }207 return false;208 }209 210 const MatchMatrix* graph_; // not owned211 // Each element of the left_ vector represents a left hand side node212 // (i.e. an element) and each element of right_ is a right hand side213 // node (i.e. a matcher). The values in the left_ vector indicate214 // outflow from that node to a node on the right_ side. The values215 // in the right_ indicate inflow, and specify which left_ node is216 // feeding that right_ node, if any. For example, left_[3] == 1 means217 // there's a flow from element #3 to matcher #1. Such a flow would also218 // be redundantly represented in the right_ vector as right_[1] == 3.219 // Elements of left_ and right_ are either kUnused or mutually220 // referent. Mutually referent means that left_[right_[i]] = i and221 // right_[left_[i]] = i.222 ::std::vector<size_t> left_;223 ::std::vector<size_t> right_;224};225 226const size_t MaxBipartiteMatchState::kUnused;227 228GTEST_API_ ElementMatcherPairs FindMaxBipartiteMatching(const MatchMatrix& g) {229 return MaxBipartiteMatchState(g).Compute();230}231 232static void LogElementMatcherPairVec(const ElementMatcherPairs& pairs,233 ::std::ostream* stream) {234 typedef ElementMatcherPairs::const_iterator Iter;235 ::std::ostream& os = *stream;236 os << "{";237 const char* sep = "";238 for (Iter it = pairs.begin(); it != pairs.end(); ++it) {239 os << sep << "\n ("240 << "element #" << it->first << ", "241 << "matcher #" << it->second << ")";242 sep = ",";243 }244 os << "\n}";245}246 247bool MatchMatrix::NextGraph() {248 for (size_t ilhs = 0; ilhs < LhsSize(); ++ilhs) {249 for (size_t irhs = 0; irhs < RhsSize(); ++irhs) {250 char& b = matched_[SpaceIndex(ilhs, irhs)];251 if (!b) {252 b = 1;253 return true;254 }255 b = 0;256 }257 }258 return false;259}260 261void MatchMatrix::Randomize() {262 for (size_t ilhs = 0; ilhs < LhsSize(); ++ilhs) {263 for (size_t irhs = 0; irhs < RhsSize(); ++irhs) {264 char& b = matched_[SpaceIndex(ilhs, irhs)];265 b = static_cast<char>(rand() & 1); // NOLINT266 }267 }268}269 270std::string MatchMatrix::DebugString() const {271 ::std::stringstream ss;272 const char* sep = "";273 for (size_t i = 0; i < LhsSize(); ++i) {274 ss << sep;275 for (size_t j = 0; j < RhsSize(); ++j) {276 ss << HasEdge(i, j);277 }278 sep = ";";279 }280 return ss.str();281}282 283void UnorderedElementsAreMatcherImplBase::DescribeToImpl(284 ::std::ostream* os) const {285 switch (match_flags()) {286 case UnorderedMatcherRequire::ExactMatch:287 if (matcher_describers_.empty()) {288 *os << "is empty";289 return;290 }291 if (matcher_describers_.size() == 1) {292 *os << "has " << Elements(1) << " and that element ";293 matcher_describers_[0]->DescribeTo(os);294 return;295 }296 *os << "has " << Elements(matcher_describers_.size())297 << " and there exists some permutation of elements such that:\n";298 break;299 case UnorderedMatcherRequire::Superset:300 *os << "a surjection from elements to requirements exists such that:\n";301 break;302 case UnorderedMatcherRequire::Subset:303 *os << "an injection from elements to requirements exists such that:\n";304 break;305 }306 307 const char* sep = "";308 for (size_t i = 0; i != matcher_describers_.size(); ++i) {309 *os << sep;310 if (match_flags() == UnorderedMatcherRequire::ExactMatch) {311 *os << " - element #" << i << " ";312 } else {313 *os << " - an element ";314 }315 matcher_describers_[i]->DescribeTo(os);316 if (match_flags() == UnorderedMatcherRequire::ExactMatch) {317 sep = ", and\n";318 } else {319 sep = "\n";320 }321 }322}323 324void UnorderedElementsAreMatcherImplBase::DescribeNegationToImpl(325 ::std::ostream* os) const {326 switch (match_flags()) {327 case UnorderedMatcherRequire::ExactMatch:328 if (matcher_describers_.empty()) {329 *os << "isn't empty";330 return;331 }332 if (matcher_describers_.size() == 1) {333 *os << "doesn't have " << Elements(1) << ", or has " << Elements(1)334 << " that ";335 matcher_describers_[0]->DescribeNegationTo(os);336 return;337 }338 *os << "doesn't have " << Elements(matcher_describers_.size())339 << ", or there exists no permutation of elements such that:\n";340 break;341 case UnorderedMatcherRequire::Superset:342 *os << "no surjection from elements to requirements exists such that:\n";343 break;344 case UnorderedMatcherRequire::Subset:345 *os << "no injection from elements to requirements exists such that:\n";346 break;347 }348 const char* sep = "";349 for (size_t i = 0; i != matcher_describers_.size(); ++i) {350 *os << sep;351 if (match_flags() == UnorderedMatcherRequire::ExactMatch) {352 *os << " - element #" << i << " ";353 } else {354 *os << " - an element ";355 }356 matcher_describers_[i]->DescribeTo(os);357 if (match_flags() == UnorderedMatcherRequire::ExactMatch) {358 sep = ", and\n";359 } else {360 sep = "\n";361 }362 }363}364 365// Checks that all matchers match at least one element, and that all366// elements match at least one matcher. This enables faster matching367// and better error reporting.368// Returns false, writing an explanation to 'listener', if and only369// if the success criteria are not met.370bool UnorderedElementsAreMatcherImplBase::VerifyMatchMatrix(371 const ::std::vector<std::string>& element_printouts,372 const MatchMatrix& matrix, MatchResultListener* listener) const {373 if (matrix.LhsSize() == 0 && matrix.RhsSize() == 0) {374 return true;375 }376 377 if (match_flags() == UnorderedMatcherRequire::ExactMatch) {378 if (matrix.LhsSize() != matrix.RhsSize()) {379 // The element count doesn't match. If the container is empty,380 // there's no need to explain anything as Google Mock already381 // prints the empty container. Otherwise we just need to show382 // how many elements there actually are.383 if (matrix.LhsSize() != 0 && listener->IsInterested()) {384 *listener << "which has " << Elements(matrix.LhsSize());385 }386 return false;387 }388 }389 390 bool result = true;391 ::std::vector<char> element_matched(matrix.LhsSize(), 0);392 ::std::vector<char> matcher_matched(matrix.RhsSize(), 0);393 394 for (size_t ilhs = 0; ilhs < matrix.LhsSize(); ilhs++) {395 for (size_t irhs = 0; irhs < matrix.RhsSize(); irhs++) {396 char matched = matrix.HasEdge(ilhs, irhs);397 element_matched[ilhs] |= matched;398 matcher_matched[irhs] |= matched;399 }400 }401 402 if (match_flags() & UnorderedMatcherRequire::Superset) {403 const char* sep =404 "where the following matchers don't match any elements:\n";405 for (size_t mi = 0; mi < matcher_matched.size(); ++mi) {406 if (matcher_matched[mi]) continue;407 result = false;408 if (listener->IsInterested()) {409 *listener << sep << "matcher #" << mi << ": ";410 matcher_describers_[mi]->DescribeTo(listener->stream());411 sep = ",\n";412 }413 }414 }415 416 if (match_flags() & UnorderedMatcherRequire::Subset) {417 const char* sep =418 "where the following elements don't match any matchers:\n";419 const char* outer_sep = "";420 if (!result) {421 outer_sep = "\nand ";422 }423 for (size_t ei = 0; ei < element_matched.size(); ++ei) {424 if (element_matched[ei]) continue;425 result = false;426 if (listener->IsInterested()) {427 *listener << outer_sep << sep << "element #" << ei << ": "428 << element_printouts[ei];429 sep = ",\n";430 outer_sep = "";431 }432 }433 }434 return result;435}436 437bool UnorderedElementsAreMatcherImplBase::FindPairing(438 const MatchMatrix& matrix, MatchResultListener* listener) const {439 ElementMatcherPairs matches = FindMaxBipartiteMatching(matrix);440 441 size_t max_flow = matches.size();442 if ((match_flags() & UnorderedMatcherRequire::Superset) &&443 max_flow < matrix.RhsSize()) {444 if (listener->IsInterested()) {445 *listener << "where no permutation of the elements can satisfy all "446 "matchers, and the closest match is "447 << max_flow << " of " << matrix.RhsSize()448 << " matchers with the pairings:\n";449 LogElementMatcherPairVec(matches, listener->stream());450 }451 return false;452 }453 if ((match_flags() & UnorderedMatcherRequire::Subset) &&454 max_flow < matrix.LhsSize()) {455 if (listener->IsInterested()) {456 *listener457 << "where not all elements can be matched, and the closest match is "458 << max_flow << " of " << matrix.RhsSize()459 << " matchers with the pairings:\n";460 LogElementMatcherPairVec(matches, listener->stream());461 }462 return false;463 }464 465 if (matches.size() > 1) {466 if (listener->IsInterested()) {467 const char* sep = "where:\n";468 for (size_t mi = 0; mi < matches.size(); ++mi) {469 *listener << sep << " - element #" << matches[mi].first470 << " is matched by matcher #" << matches[mi].second;471 sep = ",\n";472 }473 }474 }475 return true;476}477 478} // namespace internal479} // namespace testing480