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// Google Mock - a framework for writing C++ mock classes.
31//
32// This file implements Matcher<const string&>, Matcher<string>, and
33// 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 "", if
49// 'negation' is false; otherwise returns the description of the
50// negation of the matcher. 'param_values' contains a list of strings
51// 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(id_name: matcher_name);
56 if (param_values.size() >= 1) {
57 result += " " + JoinAsKeyValueTuple(names: param_names, values: 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 maximum
65// 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 left
67// nodes, and an implicit sink node that is connected to all of the
68// right nodes. All edges have unit capacity.
69//
70// Neither the flow graph nor the residual flow graph are represented
71// explicitly. Instead, they are implied by the information in 'graph' and
72// a vector<int> called 'left_' whose elements are initialized to the
73// value kUnused. This represents the initial state of the algorithm,
74// where the flow graph is empty, and the residual flow graph has the
75// following edges:
76// - An edge from source to each left_ node
77// - An edge from each right_ node to sink
78// - An edge from each left_ node to each right_ node, if the
79// corresponding edge exists in 'graph'.
80//
81// When the TryAugment() method adds a flow, it sets left_[l] = r for some
82// nodes l and r. This induces the following changes:
83// - The edges (source, l), (l, r), and (r, sink) are added to the
84// 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 added
87// to the residual flow graph, which is a directional graph
88// representing unused flow capacity.
89//
90// When the method augments a flow (moving left_[l] from some r1 to some
91// other r2), this can be thought of as "undoing" the above steps with
92// respect to r1 and "redoing" them with respect to r2.
93//
94// It bears repeating that the flow graph and residual flow graph are
95// never represented explicitly, but can be derived by looking at the
96// information in 'graph' and in left_.
97//
98// As an optimization, there is a second vector<int> called right_ which
99// does not provide any new information. Instead, it enables more
100// efficient queries about edges entering or leaving the right-side nodes
101// of the flow or residual flow graphs. The following invariants are
102// maintained:
103//
104// left[l] == kUnused or right[left[l]] == l
105// right[r] == kUnused or left[right[r]] == r
106//
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 to
136 // the sink in the residual flow graph, and if one is found, add flow
137 // to the graph. It's okay to search through the left nodes once. The
138 // edge from the implicit source node to each previously-visited left
139 // node will have flow if that left node has any path to the sink
140 // whatsoever. Subsequent augmentations can only add flow to the
141 // 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 need
144 // 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 the
146 // node once.
147 for (size_t ilhs = 0; ilhs < graph_->LhsSize(); ++ilhs) {
148 // Reset the path-marking vector and try to find a path from
149 // 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(n: graph_->RhsSize(), val: 0);
154 TryAugment(ilhs, seen: &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(x: 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 a
169 // path is found, flow is added to the network by linking the left and
170 // right vector elements corresponding each segment of the path.
171 // Returns true if a path to sink was found, which means that a unit of
172 // flow was added to the network. The 'seen' vector elements correspond
173 // to right nodes and are marked to eliminate cycles from the search.
174 //
175 // Left nodes will only be explored at most once because they
176 // are accessible from at most one right node in the residual flow
177 // graph.
178 //
179 // Note that left_[ilhs] is the only element of left_ that TryAugment will
180 // potentially transition from kUnused to another value. Any other
181 // left_ element holding kUnused before TryAugment will be holding it
182 // 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 whether
191 // this edge is a dead end or leads to the sink.
192 //
193 // right_[irhs] == kUnused means that there is residual flow from
194 // right node irhs to the sink, so we can use that to finish this
195 // flow path and return success.
196 //
197 // Otherwise there is residual flow to some ilhs. We push flow
198 // along that path and call ourselves recursively to see if this
199 // ultimately leads to sink.
200 if (right_[irhs] == kUnused || TryAugment(ilhs: 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 owned
211 // Each element of the left_ vector represents a left hand side node
212 // (i.e. an element) and each element of right_ is a right hand side
213 // node (i.e. a matcher). The values in the left_ vector indicate
214 // outflow from that node to a node on the right_ side. The values
215 // in the right_ indicate inflow, and specify which left_ node is
216 // feeding that right_ node, if any. For example, left_[3] == 1 means
217 // there's a flow from element #3 to matcher #1. Such a flow would also
218 // be redundantly represented in the right_ vector as right_[1] == 3.
219 // Elements of left_ and right_ are either kUnused or mutually
220 // referent. Mutually referent means that left_[right_[i]] = i and
221 // 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); // NOLINT
266 }
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(ilhs: i, irhs: 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(n: 1) << " and that element ";
293 matcher_describers_[0]->DescribeTo(os);
294 return;
295 }
296 *os << "has " << Elements(n: 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(n: 1) << ", or has " << Elements(n: 1)
334 << " that ";
335 matcher_describers_[0]->DescribeNegationTo(os);
336 return;
337 }
338 *os << "doesn't have " << Elements(n: 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 all
366// elements match at least one matcher. This enables faster matching
367// and better error reporting.
368// Returns false, writing an explanation to 'listener', if and only
369// 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 already
381 // prints the empty container. Otherwise we just need to show
382 // how many elements there actually are.
383 if (matrix.LhsSize() != 0 && listener->IsInterested()) {
384 *listener << "which has " << Elements(n: 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(os: 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(g: 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(pairs: matches, stream: listener->stream());
450 }
451 return false;
452 }
453 if ((match_flags() & UnorderedMatcherRequire::Subset) &&
454 max_flow < matrix.LhsSize()) {
455 if (listener->IsInterested()) {
456 *listener
457 << "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(pairs: matches, stream: 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].first
470 << " is matched by matcher #" << matches[mi].second;
471 sep = ",\n";
472 }
473 }
474 }
475 return true;
476}
477
478} // namespace internal
479} // namespace testing
480