Adjust heuristic for line-based versus byte-based diffing (#299)

.github/workflows/test.yml

@@ -0,0 +1,21 @@
+on: [push, pull_request]
+name: Test
+jobs:
+  test:
+    strategy:
+      matrix:
+        go-version: [1.13.x, 1.14.x, 1.15.x, 1.16.x, 1.17.x, 1.18.x, 1.19.x]
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+    - name: Install Go
+      uses: actions/setup-go@v2
+      with:
+        go-version: ${{ matrix.go-version }}
+    - name: Checkout code
+      uses: actions/checkout@v2
+    - name: Test
+      run: go test -v -race ./...
+    - name: Format
+      if: matrix.go-version == '1.19.x'
+      run: diff -u <(echo -n) <(gofmt -d .)

README.md

@@ -1,7 +1,7 @@
 # Package for equality of Go values
 
-[![GoDoc](https://godoc.org/github.com/google/go-cmp/cmp?status.svg)][godoc]
-[![Build Status](https://travis-ci.org/google/go-cmp.svg?branch=master)][travis]
+[![GoDev](https://img.shields.io/static/v1?label=godev&message=reference&color=00add8)][godev]
+[![Build Status](https://github.com/google/go-cmp/actions/workflows/test.yml/badge.svg?branch=master)][actions]
 
 This package is intended to be a more powerful and safer alternative to
 `reflect.DeepEqual` for comparing whether two values are semantically equal.
@@ -24,12 +24,12 @@ The primary features of `cmp` are:
   by using an `Ignore` option (see `cmpopts.IgnoreUnexported`) or explicitly
   compared using the `AllowUnexported` option.
 
-See the [GoDoc documentation][godoc] for more information.
+See the [documentation][godev] for more information.
 
 This is not an official Google product.
 
-[godoc]: https://godoc.org/github.com/google/go-cmp/cmp
-[travis]: https://travis-ci.org/google/go-cmp
+[godev]: https://pkg.go.dev/github.com/google/go-cmp/cmp
+[actions]: https://github.com/google/go-cmp/actions
 
 ## Install
 

cmp/cmpopts/equate.go

@@ -1,13 +1,15 @@
 // Copyright 2017, The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
-// license that can be found in the LICENSE.md file.
+// license that can be found in the LICENSE file.
 
 // Package cmpopts provides common options for the cmp package.
 package cmpopts
 
 import (
+	"errors"
 	"math"
 	"reflect"
+	"time"
 
 	"github.com/google/go-cmp/cmp"
 )
@@ -40,6 +42,7 @@ func isEmpty(x, y interface{}) bool {
 // The fraction and margin must be non-negative.
 //
 // The mathematical expression used is equivalent to:
+//
 //	|x-y| ≤ max(fraction*min(|x|, |y|), margin)
 //
 // EquateApprox can be used in conjunction with EquateNaNs.
@@ -87,3 +90,67 @@ func areNaNsF64s(x, y float64) bool {
 func areNaNsF32s(x, y float32) bool {
 	return areNaNsF64s(float64(x), float64(y))
 }
+
+// EquateApproxTime returns a Comparer option that determines two non-zero
+// time.Time values to be equal if they are within some margin of one another.
+// If both times have a monotonic clock reading, then the monotonic time
+// difference will be used. The margin must be non-negative.
+func EquateApproxTime(margin time.Duration) cmp.Option {
+	if margin < 0 {
+		panic("margin must be a non-negative number")
+	}
+	a := timeApproximator{margin}
+	return cmp.FilterValues(areNonZeroTimes, cmp.Comparer(a.compare))
+}
+
+func areNonZeroTimes(x, y time.Time) bool {
+	return !x.IsZero() && !y.IsZero()
+}
+
+type timeApproximator struct {
+	margin time.Duration
+}
+
+func (a timeApproximator) compare(x, y time.Time) bool {
+	// Avoid subtracting times to avoid overflow when the
+	// difference is larger than the largest representable duration.
+	if x.After(y) {
+		// Ensure x is always before y
+		x, y = y, x
+	}
+	// We're within the margin if x+margin >= y.
+	// Note: time.Time doesn't have AfterOrEqual method hence the negation.
+	return !x.Add(a.margin).Before(y)
+}
+
+// AnyError is an error that matches any non-nil error.
+var AnyError anyError
+
+type anyError struct{}
+
+func (anyError) Error() string     { return "any error" }
+func (anyError) Is(err error) bool { return err != nil }
+
+// EquateErrors returns a Comparer option that determines errors to be equal
+// if errors.Is reports them to match. The AnyError error can be used to
+// match any non-nil error.
+func EquateErrors() cmp.Option {
+	return cmp.FilterValues(areConcreteErrors, cmp.Comparer(compareErrors))
+}
+
+// areConcreteErrors reports whether x and y are types that implement error.
+// The input types are deliberately of the interface{} type rather than the
+// error type so that we can handle situations where the current type is an
+// interface{}, but the underlying concrete types both happen to implement
+// the error interface.
+func areConcreteErrors(x, y interface{}) bool {
+	_, ok1 := x.(error)
+	_, ok2 := y.(error)
+	return ok1 && ok2
+}
+
+func compareErrors(x, y interface{}) bool {
+	xe := x.(error)
+	ye := y.(error)
+	return errors.Is(xe, ye) || errors.Is(ye, xe)
+}

cmp/cmpopts/example_test.go

@@ -0,0 +1,130 @@
+// Copyright 2020, The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package cmpopts_test
+
+import (
+	"fmt"
+	"net"
+	"time"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/google/go-cmp/cmp/cmpopts"
+	"github.com/google/go-cmp/cmp/internal/flags"
+)
+
+func init() {
+	flags.Deterministic = true
+}
+
+// Use IgnoreFields to ignore fields on a struct type when comparing
+// by providing a value of the type and the field names to ignore.
+// Typically, a zero value of the type is used (e.g., foo.MyStruct{}).
+func ExampleIgnoreFields_testing() {
+	// Let got be the hypothetical value obtained from some logic under test
+	// and want be the expected golden data.
+	got, want := MakeGatewayInfo()
+
+	// While the specified fields will be semantically ignored for the comparison,
+	// the fields may be printed in the diff when displaying entire values
+	// that are already determined to be different.
+	if diff := cmp.Diff(want, got, cmpopts.IgnoreFields(Client{}, "IPAddress")); diff != "" {
+		t.Errorf("MakeGatewayInfo() mismatch (-want +got):\n%s", diff)
+	}
+
+	// Output:
+	// MakeGatewayInfo() mismatch (-want +got):
+	//   cmpopts_test.Gateway{
+	//   	SSID:      "CoffeeShopWiFi",
+	// - 	IPAddress: s"192.168.0.2",
+	// + 	IPAddress: s"192.168.0.1",
+	//   	NetMask:   s"ffff0000",
+	//   	Clients: []cmpopts_test.Client{
+	//   		... // 3 identical elements
+	//   		{Hostname: "espresso", ...},
+	//   		{Hostname: "latte", LastSeen: s"2009-11-10 23:00:23 +0000 UTC", ...},
+	// + 		{
+	// + 			Hostname:  "americano",
+	// + 			IPAddress: s"192.168.0.188",
+	// + 			LastSeen:  s"2009-11-10 23:03:05 +0000 UTC",
+	// + 		},
+	//   	},
+	//   }
+}
+
+type (
+	Gateway struct {
+		SSID      string
+		IPAddress net.IP
+		NetMask   net.IPMask
+		Clients   []Client
+	}
+	Client struct {
+		Hostname  string
+		IPAddress net.IP
+		LastSeen  time.Time
+	}
+)
+
+func MakeGatewayInfo() (x, y Gateway) {
+	x = Gateway{
+		SSID:      "CoffeeShopWiFi",
+		IPAddress: net.IPv4(192, 168, 0, 1),
+		NetMask:   net.IPv4Mask(255, 255, 0, 0),
+		Clients: []Client{{
+			Hostname:  "ristretto",
+			IPAddress: net.IPv4(192, 168, 0, 116),
+		}, {
+			Hostname:  "aribica",
+			IPAddress: net.IPv4(192, 168, 0, 104),
+			LastSeen:  time.Date(2009, time.November, 10, 23, 6, 32, 0, time.UTC),
+		}, {
+			Hostname:  "macchiato",
+			IPAddress: net.IPv4(192, 168, 0, 153),
+			LastSeen:  time.Date(2009, time.November, 10, 23, 39, 43, 0, time.UTC),
+		}, {
+			Hostname:  "espresso",
+			IPAddress: net.IPv4(192, 168, 0, 121),
+		}, {
+			Hostname:  "latte",
+			IPAddress: net.IPv4(192, 168, 0, 219),
+			LastSeen:  time.Date(2009, time.November, 10, 23, 0, 23, 0, time.UTC),
+		}, {
+			Hostname:  "americano",
+			IPAddress: net.IPv4(192, 168, 0, 188),
+			LastSeen:  time.Date(2009, time.November, 10, 23, 3, 5, 0, time.UTC),
+		}},
+	}
+	y = Gateway{
+		SSID:      "CoffeeShopWiFi",
+		IPAddress: net.IPv4(192, 168, 0, 2),
+		NetMask:   net.IPv4Mask(255, 255, 0, 0),
+		Clients: []Client{{
+			Hostname:  "ristretto",
+			IPAddress: net.IPv4(192, 168, 0, 116),
+		}, {
+			Hostname:  "aribica",
+			IPAddress: net.IPv4(192, 168, 0, 104),
+			LastSeen:  time.Date(2009, time.November, 10, 23, 6, 32, 0, time.UTC),
+		}, {
+			Hostname:  "macchiato",
+			IPAddress: net.IPv4(192, 168, 0, 153),
+			LastSeen:  time.Date(2009, time.November, 10, 23, 39, 43, 0, time.UTC),
+		}, {
+			Hostname:  "espresso",
+			IPAddress: net.IPv4(192, 168, 0, 121),
+		}, {
+			Hostname:  "latte",
+			IPAddress: net.IPv4(192, 168, 0, 221),
+			LastSeen:  time.Date(2009, time.November, 10, 23, 0, 23, 0, time.UTC),
+		}},
+	}
+	return x, y
+}
+
+var t fakeT
+
+type fakeT struct{}
+
+func (t fakeT) Errorf(format string, args ...interface{}) { fmt.Printf(format+"\n", args...) }