A RetroSearch Logo

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Search Query:

Showing content from https://pkg.go.dev/github.com/google/go-cmp/cmp below:

cmp package - github.com/google/go-cmp/cmp - Go Packages

Package cmp determines equality of values.

This package is intended to be a more powerful and safer alternative to reflect.DeepEqual for comparing whether two values are semantically equal. It is intended to only be used in tests, as performance is not a goal and it may panic if it cannot compare the values. Its propensity towards panicking means that its unsuitable for production environments where a spurious panic may be fatal.

The primary features of cmp are:

This section is empty.

This section is empty.

Diff returns a human-readable report of the differences between two values: y - x. It returns an empty string if and only if Equal returns true for the same input values and options.

The output is displayed as a literal in pseudo-Go syntax. At the start of each line, a "-" prefix indicates an element removed from x, a "+" prefix to indicates an element added from y, and the lack of a prefix indicates an element common to both x and y. If possible, the output uses fmt.Stringer.String or error.Error methods to produce more humanly readable outputs. In such cases, the string is prefixed with either an 's' or 'e' character, respectively, to indicate that the method was called.

Do not depend on this output being stable. If you need the ability to programmatically interpret the difference, consider using a custom Reporter.

Use Diff to print out a human-readable report of differences for tests comparing nested or structured data.

package main

import (
	"fmt"
	"net"
	"time"

	"github.com/google/go-cmp/cmp"
)

func main() {
	// Let got be the hypothetical value obtained from some logic under test
	// and want be the expected golden data.
	got, want := MakeGatewayInfo()

	if diff := cmp.Diff(want, got); diff != "" {
		t.Errorf("MakeGatewayInfo() mismatch (-want +got):\n%s", diff)
	}

}

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:  "arabica",
			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:  "arabica",
			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...) }
Output:

MakeGatewayInfo() mismatch (-want +got):
  cmp_test.Gateway{
  	SSID:      "CoffeeShopWiFi",
- 	IPAddress: s"192.168.0.2",
+ 	IPAddress: s"192.168.0.1",
  	NetMask:   s"ffff0000",
  	Clients: []cmp_test.Client{
  		... // 2 identical elements
  		{Hostname: "macchiato", IPAddress: s"192.168.0.153", LastSeen: s"2009-11-10 23:39:43 +0000 UTC"},
  		{Hostname: "espresso", IPAddress: s"192.168.0.121"},
  		{
  			Hostname:  "latte",
- 			IPAddress: s"192.168.0.221",
+ 			IPAddress: s"192.168.0.219",
  			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",
+ 		},
  	},
  }

Equal reports whether x and y are equal by recursively applying the following rules in the given order to x and y and all of their sub-values:

Structs are equal if recursively calling Equal on all fields report equal. If a struct contains unexported fields, Equal panics unless an Ignore option (e.g., github.com/google/go-cmp/cmp/cmpopts.IgnoreUnexported) ignores that field or the Exporter option explicitly permits comparing the unexported field.

Slices are equal if they are both nil or both non-nil, where recursively calling Equal on all non-ignored slice or array elements report equal. Empty non-nil slices and nil slices are not equal; to equate empty slices, consider using github.com/google/go-cmp/cmp/cmpopts.EquateEmpty.

Maps are equal if they are both nil or both non-nil, where recursively calling Equal on all non-ignored map entries report equal. Map keys are equal according to the == operator. To use custom comparisons for map keys, consider using github.com/google/go-cmp/cmp/cmpopts.SortMaps. Empty non-nil maps and nil maps are not equal; to equate empty maps, consider using github.com/google/go-cmp/cmp/cmpopts.EquateEmpty.

Pointers and interfaces are equal if they are both nil or both non-nil, where they have the same underlying concrete type and recursively calling Equal on the underlying values reports equal.

Before recursing into a pointer, slice element, or map, the current path is checked to detect whether the address has already been visited. If there is a cycle, then the pointed at values are considered equal only if both addresses were previously visited in the same path step.

Indirect is a PathStep that represents pointer indirection on the parent type.

MapIndex is a PathStep that represents an index operation on a map at some index Key.

Key is the value of the map key.

type Option interface {
	
}

Option configures for specific behavior of Equal and Diff. In particular, the fundamental Option functions (Ignore, Transformer, and Comparer), configure how equality is determined.

The fundamental options may be composed with filters (FilterPath and FilterValues) to control the scope over which they are applied.

The github.com/google/go-cmp/cmp/cmpopts package provides helper functions for creating options that may be used with Equal and Diff.

Approximate equality for floats can be handled by defining a custom comparer on floats that determines two values to be equal if they are within some range of each other.

This example is for demonstrative purposes; use github.com/google/go-cmp/cmp/cmpopts.EquateApprox instead.

package main

import (
	"fmt"
	"math"

	"github.com/google/go-cmp/cmp"
)

func main() {
	// This Comparer only operates on float64.
	// To handle float32s, either define a similar function for that type
	// or use a Transformer to convert float32s into float64s.
	opt := cmp.Comparer(func(x, y float64) bool {
		delta := math.Abs(x - y)
		mean := math.Abs(x+y) / 2.0
		return delta/mean < 0.00001
	})

	x := []float64{1.0, 1.1, 1.2, math.Pi}
	y := []float64{1.0, 1.1, 1.2, 3.14159265359} // Accurate enough to Pi
	z := []float64{1.0, 1.1, 1.2, 3.1415}        // Diverges too far from Pi

	fmt.Println(cmp.Equal(x, y, opt))
	fmt.Println(cmp.Equal(y, z, opt))
	fmt.Println(cmp.Equal(z, x, opt))

}
Output:

true
false
false

If the Equal method defined on a type is not suitable, the type can be dynamically transformed to be stripped of the Equal method (or any method for that matter).

package main

import (
	"fmt"
	"strings"

	"github.com/google/go-cmp/cmp"
)

type otherString string

func (x otherString) Equal(y otherString) bool {
	return strings.EqualFold(string(x), string(y))
}

func main() {
	// Suppose otherString.Equal performs a case-insensitive equality,
	// which is too loose for our needs.
	// We can avoid the methods of otherString by declaring a new type.
	type myString otherString

	// This transformer converts otherString to myString, allowing Equal to use
	// other Options to determine equality.
	trans := cmp.Transformer("", func(in otherString) myString {
		return myString(in)
	})

	x := []otherString{"foo", "bar", "baz"}
	y := []otherString{"fOO", "bAr", "Baz"} // Same as before, but with different case

	fmt.Println(cmp.Equal(x, y))        // Equal because of case-insensitivity
	fmt.Println(cmp.Equal(x, y, trans)) // Not equal because of more exact equality

}
Output:

true
false

Sometimes, an empty map or slice is considered equal to an allocated one of zero length.

This example is for demonstrative purposes; use github.com/google/go-cmp/cmp/cmpopts.EquateEmpty instead.

package main

import (
	"fmt"
	"reflect"

	"github.com/google/go-cmp/cmp"
)

func main() {
	alwaysEqual := cmp.Comparer(func(_, _ interface{}) bool { return true })

	// This option handles slices and maps of any type.
	opt := cmp.FilterValues(func(x, y interface{}) bool {
		vx, vy := reflect.ValueOf(x), reflect.ValueOf(y)
		return (vx.IsValid() && vy.IsValid() && vx.Type() == vy.Type()) &&
			(vx.Kind() == reflect.Slice || vx.Kind() == reflect.Map) &&
			(vx.Len() == 0 && vy.Len() == 0)
	}, alwaysEqual)

	type S struct {
		A []int
		B map[string]bool
	}
	x := S{nil, make(map[string]bool, 100)}
	y := S{make([]int, 0, 200), nil}
	z := S{[]int{0}, nil} // []int has a single element (i.e., not empty)

	fmt.Println(cmp.Equal(x, y, opt))
	fmt.Println(cmp.Equal(y, z, opt))
	fmt.Println(cmp.Equal(z, x, opt))

}
Output:

true
false
false

Normal floating-point arithmetic defines == to be false when comparing NaN with itself. In certain cases, this is not the desired property.

This example is for demonstrative purposes; use github.com/google/go-cmp/cmp/cmpopts.EquateNaNs instead.

package main

import (
	"fmt"
	"math"

	"github.com/google/go-cmp/cmp"
)

func main() {
	// This Comparer only operates on float64.
	// To handle float32s, either define a similar function for that type
	// or use a Transformer to convert float32s into float64s.
	opt := cmp.Comparer(func(x, y float64) bool {
		return (math.IsNaN(x) && math.IsNaN(y)) || x == y
	})

	x := []float64{1.0, math.NaN(), math.E, 0.0}
	y := []float64{1.0, math.NaN(), math.E, 0.0}
	z := []float64{1.0, math.NaN(), math.Pi, 0.0} // Pi constant instead of E

	fmt.Println(cmp.Equal(x, y, opt))
	fmt.Println(cmp.Equal(y, z, opt))
	fmt.Println(cmp.Equal(z, x, opt))

}
Output:

true
false
false

To have floating-point comparisons combine both properties of NaN being equal to itself and also approximate equality of values, filters are needed to restrict the scope of the comparison so that they are composable.

This example is for demonstrative purposes; use github.com/google/go-cmp/cmp/cmpopts.EquateApprox instead.

package main

import (
	"fmt"
	"math"

	"github.com/google/go-cmp/cmp"
)

func main() {
	alwaysEqual := cmp.Comparer(func(_, _ interface{}) bool { return true })

	opts := cmp.Options{
		// This option declares that a float64 comparison is equal only if
		// both inputs are NaN.
		cmp.FilterValues(func(x, y float64) bool {
			return math.IsNaN(x) && math.IsNaN(y)
		}, alwaysEqual),

		// This option declares approximate equality on float64s only if
		// both inputs are not NaN.
		cmp.FilterValues(func(x, y float64) bool {
			return !math.IsNaN(x) && !math.IsNaN(y)
		}, cmp.Comparer(func(x, y float64) bool {
			delta := math.Abs(x - y)
			mean := math.Abs(x+y) / 2.0
			return delta/mean < 0.00001
		})),
	}

	x := []float64{math.NaN(), 1.0, 1.1, 1.2, math.Pi}
	y := []float64{math.NaN(), 1.0, 1.1, 1.2, 3.14159265359} // Accurate enough to Pi
	z := []float64{math.NaN(), 1.0, 1.1, 1.2, 3.1415}        // Diverges too far from Pi

	fmt.Println(cmp.Equal(x, y, opts))
	fmt.Println(cmp.Equal(y, z, opts))
	fmt.Println(cmp.Equal(z, x, opts))

}
Output:

true
false
false

Two slices may be considered equal if they have the same elements, regardless of the order that they appear in. Transformations can be used to sort the slice.

This example is for demonstrative purposes; use github.com/google/go-cmp/cmp/cmpopts.SortSlices instead.

package main

import (
	"fmt"
	"sort"

	"github.com/google/go-cmp/cmp"
)

func main() {
	// This Transformer sorts a []int.
	trans := cmp.Transformer("Sort", func(in []int) []int {
		out := append([]int(nil), in...) // Copy input to avoid mutating it
		sort.Ints(out)
		return out
	})

	x := struct{ Ints []int }{[]int{0, 1, 2, 3, 4, 5, 6, 7, 8, 9}}
	y := struct{ Ints []int }{[]int{2, 8, 0, 9, 6, 1, 4, 7, 3, 5}}
	z := struct{ Ints []int }{[]int{0, 0, 1, 2, 3, 4, 5, 6, 7, 8}}

	fmt.Println(cmp.Equal(x, y, trans))
	fmt.Println(cmp.Equal(y, z, trans))
	fmt.Println(cmp.Equal(z, x, trans))

}
Output:

true
false
false

The complex numbers complex64 and complex128 can really just be decomposed into a pair of float32 or float64 values. It would be convenient to be able define only a single comparator on float64 and have float32, complex64, and complex128 all be able to use that comparator. Transformations can be used to handle this.

package main

import (
	"fmt"
	"math"

	"github.com/google/go-cmp/cmp"
)

func roundF64(z float64) float64 {
	if z < 0 {
		return math.Ceil(z - 0.5)
	}
	return math.Floor(z + 0.5)
}

func main() {
	opts := []cmp.Option{
		// This transformer decomposes complex128 into a pair of float64s.
		cmp.Transformer("T1", func(in complex128) (out struct{ Real, Imag float64 }) {
			out.Real, out.Imag = real(in), imag(in)
			return out
		}),
		// This transformer converts complex64 to complex128 to allow the
		// above transform to take effect.
		cmp.Transformer("T2", func(in complex64) complex128 {
			return complex128(in)
		}),
		// This transformer converts float32 to float64.
		cmp.Transformer("T3", func(in float32) float64 {
			return float64(in)
		}),
		// This equality function compares float64s as rounded integers.
		cmp.Comparer(func(x, y float64) bool {
			return roundF64(x) == roundF64(y)
		}),
	}

	x := []interface{}{
		complex128(3.0), complex64(5.1 + 2.9i), float32(-1.2), float64(12.3),
	}
	y := []interface{}{
		complex128(3.1), complex64(4.9 + 3.1i), float32(-1.3), float64(11.7),
	}
	z := []interface{}{
		complex128(3.8), complex64(4.9 + 3.1i), float32(-1.3), float64(11.7),
	}

	fmt.Println(cmp.Equal(x, y, opts...))
	fmt.Println(cmp.Equal(y, z, opts...))
	fmt.Println(cmp.Equal(z, x, opts...))

}
Output:

true
false
false
func AllowUnexported(types ...interface{}) Option

AllowUnexported returns an Option that allows Equal to forcibly introspect unexported fields of the specified struct types.

See Exporter for the proper use of this option.

func Comparer(f interface{}) Option

Comparer returns an Option that determines whether two values are equal to each other.

The comparer f must be a function "func(T, T) bool" and is implicitly filtered to input values assignable to T. If T is an interface, it is possible that f is called with two values of different concrete types that both implement T.

The equality function must be:

Exporter returns an Option that specifies whether Equal is allowed to introspect into the unexported fields of certain struct types.

Users of this option must understand that comparing on unexported fields from external packages is not safe since changes in the internal implementation of some external package may cause the result of Equal to unexpectedly change. However, it may be valid to use this option on types defined in an internal package where the semantic meaning of an unexported field is in the control of the user.

In many cases, a custom Comparer should be used instead that defines equality as a function of the public API of a type rather than the underlying unexported implementation.

For example, the reflect.Type documentation defines equality to be determined by the == operator on the interface (essentially performing a shallow pointer comparison) and most attempts to compare *regexp.Regexp types are interested in only checking that the regular expression strings are equal. Both of these are accomplished using Comparer options:

Comparer(func(x, y reflect.Type) bool { return x == y })
Comparer(func(x, y *regexp.Regexp) bool { return x.String() == y.String() })

In other cases, the github.com/google/go-cmp/cmp/cmpopts.IgnoreUnexported option can be used to ignore all unexported fields on specified struct types.

FilterPath returns a new Option where opt is only evaluated if filter f returns true for the current Path in the value tree.

This filter is called even if a slice element or map entry is missing and provides an opportunity to ignore such cases. The filter function must be symmetric such that the filter result is identical regardless of whether the missing value is from x or y.

The option passed in may be an Ignore, Transformer, Comparer, Options, or a previously filtered Option.

FilterValues returns a new Option where opt is only evaluated if filter f, which is a function of the form "func(T, T) bool", returns true for the current pair of values being compared. If either value is invalid or the type of the values is not assignable to T, then this filter implicitly returns false.

The filter function must be symmetric (i.e., agnostic to the order of the inputs) and deterministic (i.e., produces the same result when given the same inputs). If T is an interface, it is possible that f is called with two values with different concrete types that both implement T.

The option passed in may be an Ignore, Transformer, Comparer, Options, or a previously filtered Option.

Ignore is an Option that causes all comparisons to be ignored. This value is intended to be combined with FilterPath or FilterValues. It is an error to pass an unfiltered Ignore option to Equal.

Reporter is an Option that can be passed to Equal. When Equal traverses the value trees, it calls PushStep as it descends into each node in the tree and PopStep as it ascend out of the node. The leaves of the tree are either compared (determined to be equal or not equal) or ignored and reported as such by calling the Report method.

package main

import (
	"fmt"
	"strings"

	"github.com/google/go-cmp/cmp"
)

// DiffReporter is a simple custom reporter that only records differences
// detected during comparison.
type DiffReporter struct {
	path  cmp.Path
	diffs []string
}

func (r *DiffReporter) PushStep(ps cmp.PathStep) {
	r.path = append(r.path, ps)
}

func (r *DiffReporter) Report(rs cmp.Result) {
	if !rs.Equal() {
		vx, vy := r.path.Last().Values()
		r.diffs = append(r.diffs, fmt.Sprintf("%#v:\n\t-: %+v\n\t+: %+v\n", r.path, vx, vy))
	}
}

func (r *DiffReporter) PopStep() {
	r.path = r.path[:len(r.path)-1]
}

func (r *DiffReporter) String() string {
	return strings.Join(r.diffs, "\n")
}

func main() {
	x, y := MakeGatewayInfo()

	var r DiffReporter
	cmp.Equal(x, y, cmp.Reporter(&r))
	fmt.Print(r.String())

}
Output:

{cmp_test.Gateway}.IPAddress:
	-: 192.168.0.1
	+: 192.168.0.2

{cmp_test.Gateway}.Clients[4].IPAddress:
	-: 192.168.0.219
	+: 192.168.0.221

{cmp_test.Gateway}.Clients[5->?]:
	-: {Hostname:americano IPAddress:192.168.0.188 LastSeen:2009-11-10 23:03:05 +0000 UTC}
	+: <invalid reflect.Value>

Transformer returns an Option that applies a transformation function that converts values of a certain type into that of another.

The transformer f must be a function "func(T) R" that converts values of type T to those of type R and is implicitly filtered to input values assignable to T. The transformer must not mutate T in any way.

To help prevent some cases of infinite recursive cycles applying the same transform to the output of itself (e.g., in the case where the input and output types are the same), an implicit filter is added such that a transformer is applicable only if that exact transformer is not already in the tail of the Path since the last non-Transform step. For situations where the implicit filter is still insufficient, consider using github.com/google/go-cmp/cmp/cmpopts.AcyclicTransformer, which adds a filter to prevent the transformer from being recursively applied upon itself.

The name is a user provided label that is used as the Transform.Name in the transformation PathStep (and eventually shown in the Diff output). The name must be a valid identifier or qualified identifier in Go syntax. If empty, an arbitrary name is used.

Options is a list of Option values that also satisfies the Option interface. Helper comparison packages may return an Options value when packing multiple Option values into a single Option. When this package processes an Options, it will be implicitly expanded into a flat list.

Applying a filter on an Options is equivalent to applying that same filter on all individual options held within.

Path is a list of PathStep describing the sequence of operations to get from some root type to the current position in the value tree. The first Path element is always an operation-less PathStep that exists simply to identify the initial type.

When traversing structs with embedded structs, the embedded struct will always be accessed as a field before traversing the fields of the embedded struct themselves. That is, an exported field from the embedded struct will never be accessed directly from the parent struct.

GoString returns the path to a specific node using Go syntax.

For example:

(*root.MyMap["key"].(*mypkg.MyStruct).MySlices)[2][3].MyField

Index returns the ith step in the Path and supports negative indexing. A negative index starts counting from the tail of the Path such that -1 refers to the last step, -2 refers to the second-to-last step, and so on. If index is invalid, this returns a non-nil PathStep that reports a nil [PathStep.Type].

Last returns the last PathStep in the Path. If the path is empty, this returns a non-nil PathStep that reports a nil [PathStep.Type].

String returns the simplified path to a node. The simplified path only contains struct field accesses.

For example:

MyMap.MySlices.MyField

PathStep is a union-type for specific operations to traverse a value's tree structure. Users of this package never need to implement these types as values of this type will be returned by this package.

Implementations of this interface:

Result represents the comparison result for a single node and is provided by cmp when calling Report (see Reporter).

ByCycle reports whether a reference cycle was detected.

ByFunc reports whether a Comparer function determined equality.

ByIgnore reports whether the node is equal because it was ignored. This never reports true if Result.Equal reports false.

ByMethod reports whether the Equal method determined equality.

Equal reports whether the node was determined to be equal or not. As a special case, ignored nodes are considered equal.

type SliceIndex struct {
	
}

SliceIndex is a PathStep that represents an index operation on a slice or array at some index SliceIndex.Key.

Key is the index key; it may return -1 if in a split state

SplitKeys are the indexes for indexing into slices in the x and y values, respectively. These indexes may differ due to the insertion or removal of an element in one of the slices, causing all of the indexes to be shifted. If an index is -1, then that indicates that the element does not exist in the associated slice.

SliceIndex.Key is guaranteed to return -1 if and only if the indexes returned by SplitKeys are not the same. SplitKeys will never return -1 for both indexes.

type StructField struct {
	
}

StructField is a PathStep that represents a struct field access on a field called StructField.Name.

type Transform struct {
	
}

Transform is a PathStep that represents a transformation from the parent type to the current type.

Func is the function pointer to the transformer function.

Option returns the originally constructed Transformer option. The == operator can be used to detect the exact option used.

type TypeAssertion struct {
	
}

TypeAssertion is a PathStep that represents a type assertion on an interface.


RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4