1// Copyright 2017, The Go Authors. All rights reserved. 2// Use of this source code is governed by a BSD-style 3// license that can be found in the LICENSE file. 4 5// Package cmpopts provides common options for the cmp package. 6package cmpopts 7 8import ( 9 "math" 10 "reflect" 11 "time" 12 13 "github.com/google/go-cmp/cmp" 14) 15 16func equateAlways(_, _ interface{}) bool { return true } 17 18// EquateEmpty returns a Comparer option that determines all maps and slices 19// with a length of zero to be equal, regardless of whether they are nil. 20// 21// EquateEmpty can be used in conjunction with SortSlices and SortMaps. 22func EquateEmpty() cmp.Option { 23 return cmp.FilterValues(isEmpty, cmp.Comparer(equateAlways)) 24} 25 26func isEmpty(x, y interface{}) bool { 27 vx, vy := reflect.ValueOf(x), reflect.ValueOf(y) 28 return (x != nil && y != nil && vx.Type() == vy.Type()) && 29 (vx.Kind() == reflect.Slice || vx.Kind() == reflect.Map) && 30 (vx.Len() == 0 && vy.Len() == 0) 31} 32 33// EquateApprox returns a Comparer option that determines float32 or float64 34// values to be equal if they are within a relative fraction or absolute margin. 35// This option is not used when either x or y is NaN or infinite. 36// 37// The fraction determines that the difference of two values must be within the 38// smaller fraction of the two values, while the margin determines that the two 39// values must be within some absolute margin. 40// To express only a fraction or only a margin, use 0 for the other parameter. 41// The fraction and margin must be non-negative. 42// 43// The mathematical expression used is equivalent to: 44// |x-y| ≤ max(fraction*min(|x|, |y|), margin) 45// 46// EquateApprox can be used in conjunction with EquateNaNs. 47func EquateApprox(fraction, margin float64) cmp.Option { 48 if margin < 0 || fraction < 0 || math.IsNaN(margin) || math.IsNaN(fraction) { 49 panic("margin or fraction must be a non-negative number") 50 } 51 a := approximator{fraction, margin} 52 return cmp.Options{ 53 cmp.FilterValues(areRealF64s, cmp.Comparer(a.compareF64)), 54 cmp.FilterValues(areRealF32s, cmp.Comparer(a.compareF32)), 55 } 56} 57 58type approximator struct{ frac, marg float64 } 59 60func areRealF64s(x, y float64) bool { 61 return !math.IsNaN(x) && !math.IsNaN(y) && !math.IsInf(x, 0) && !math.IsInf(y, 0) 62} 63func areRealF32s(x, y float32) bool { 64 return areRealF64s(float64(x), float64(y)) 65} 66func (a approximator) compareF64(x, y float64) bool { 67 relMarg := a.frac * math.Min(math.Abs(x), math.Abs(y)) 68 return math.Abs(x-y) <= math.Max(a.marg, relMarg) 69} 70func (a approximator) compareF32(x, y float32) bool { 71 return a.compareF64(float64(x), float64(y)) 72} 73 74// EquateNaNs returns a Comparer option that determines float32 and float64 75// NaN values to be equal. 76// 77// EquateNaNs can be used in conjunction with EquateApprox. 78func EquateNaNs() cmp.Option { 79 return cmp.Options{ 80 cmp.FilterValues(areNaNsF64s, cmp.Comparer(equateAlways)), 81 cmp.FilterValues(areNaNsF32s, cmp.Comparer(equateAlways)), 82 } 83} 84 85func areNaNsF64s(x, y float64) bool { 86 return math.IsNaN(x) && math.IsNaN(y) 87} 88func areNaNsF32s(x, y float32) bool { 89 return areNaNsF64s(float64(x), float64(y)) 90} 91 92// EquateApproxTime returns a Comparer option that determines two non-zero 93// time.Time values to be equal if they are within some margin of one another. 94// If both times have a monotonic clock reading, then the monotonic time 95// difference will be used. The margin must be non-negative. 96func EquateApproxTime(margin time.Duration) cmp.Option { 97 if margin < 0 { 98 panic("margin must be a non-negative number") 99 } 100 a := timeApproximator{margin} 101 return cmp.FilterValues(areNonZeroTimes, cmp.Comparer(a.compare)) 102} 103 104func areNonZeroTimes(x, y time.Time) bool { 105 return !x.IsZero() && !y.IsZero() 106} 107 108type timeApproximator struct { 109 margin time.Duration 110} 111 112func (a timeApproximator) compare(x, y time.Time) bool { 113 // Avoid subtracting times to avoid overflow when the 114 // difference is larger than the largest representable duration. 115 if x.After(y) { 116 // Ensure x is always before y 117 x, y = y, x 118 } 119 // We're within the margin if x+margin >= y. 120 // Note: time.Time doesn't have AfterOrEqual method hence the negation. 121 return !x.Add(a.margin).Before(y) 122} 123 124// AnyError is an error that matches any non-nil error. 125var AnyError anyError 126 127type anyError struct{} 128 129func (anyError) Error() string { return "any error" } 130func (anyError) Is(err error) bool { return err != nil } 131 132// EquateErrors returns a Comparer option that determines errors to be equal 133// if errors.Is reports them to match. The AnyError error can be used to 134// match any non-nil error. 135func EquateErrors() cmp.Option { 136 return cmp.FilterValues(areConcreteErrors, cmp.Comparer(compareErrors)) 137} 138 139// areConcreteErrors reports whether x and y are types that implement error. 140// The input types are deliberately of the interface{} type rather than the 141// error type so that we can handle situations where the current type is an 142// interface{}, but the underlying concrete types both happen to implement 143// the error interface. 144func areConcreteErrors(x, y interface{}) bool { 145 _, ok1 := x.(error) 146 _, ok2 := y.(error) 147 return ok1 && ok2 148} 149