package cmp

This package is intended to be a more powerful and safer alternative to
reflect.DeepEqual for comparing whether two values are semantically equal.

The primary features of cmp are:

• When the default behavior of equality does not suit the needs of the test,
custom equality functions can override the equality operation.
For example, an equality function may report floats as equal so long as they
are within some tolerance of each other.

• Types that have an Equal method may use that method to determine equality.
This allows package authors to determine the equality operation for the types
that they define.

• If no custom equality functions are used and no Equal method is defined,
equality is determined by recursively comparing the primitive kinds on both
values, much like reflect.DeepEqual. Unlike reflect.DeepEqual, unexported
fields are not compared by default; they result in panics unless suppressed
by using an Ignore option (see cmpopts.IgnoreUnexported) or explicitly compared
using the AllowUnexported option.

Diff returns a human-readable report of the differences between two values.
It returns an empty string if and only if Equal returns true for the same
input values and options. The output string will use the "-" symbol to
indicate elements removed from x, and the "+" symbol to indicate elements
added to y.

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:

• If two values are not of the same type, then they are never equal
and the overall result is false.

• Let S be the set of all Ignore, Transformer, and Comparer options that
remain after applying all path filters, value filters, and type filters.
If at least one Ignore exists in S, then the comparison is ignored.
If the number of Transformer and Comparer options in S is greater than one,
then Equal panics because it is ambiguous which option to use.
If S contains a single Transformer, then use that to transform the current
values and recursively call Equal on the output values.
If S contains a single Comparer, then use that to compare the current values.
Otherwise, evaluation proceeds to the next rule.

• If the values have an Equal method of the form "(T) Equal(T) bool" or
"(T) Equal(I) bool" where T is assignable to I, then use the result of
x.Equal(y) even if x or y is nil.
Otherwise, no such method exists and evaluation proceeds to the next rule.

• Lastly, try to compare x and y based on their basic kinds.
Simple kinds like booleans, integers, floats, complex numbers, strings, and
channels are compared using the equivalent of the == operator in Go.
Functions are only equal if they are both nil, otherwise they are unequal.
Pointers are equal if the underlying values they point to are also equal.
Interfaces are equal if their underlying concrete values are also equal.

Structs are equal if all of their fields are equal. If a struct contains
unexported fields, Equal panics unless the AllowUnexported option is used or
an Ignore option (e.g., cmpopts.IgnoreUnexported) ignores that field.

Arrays, slices, and maps are equal if they are both nil or both non-nil
with the same length and the elements at each index or key are equal.
Note that a non-nil empty slice and a nil slice are not equal.
To equate empty slices and maps, consider using cmpopts.EquateEmpty.
Map keys are equal according to the == operator.
To use custom comparisons for map keys, consider using cmpopts.SortMaps.

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 cmpopts.EquateNaNs and cmpopts.EquateApprox instead.

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.

AllowUnexported returns an Option that forcibly allows operations on
unexported fields in certain structs, which are specified by passing in a
value of each struct type.

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.

For some 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 Comparers:

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.

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 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.

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 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. 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 PathSteps 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.

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 Type.

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.

type SliceIndex interface {
PathStepKey() int// May return -1 if in a split state
// SplitKeys returns 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.
//
// 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.SplitKeys() (x int, y int)
// contains filtered or unexported methods
}

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

☞ Maps with keys containing NaN values cannot be properly compared due to
the reflection package's inability to retrieve such entries. Equal will panic
anytime it comes across a NaN key, but this behavior may change.
See https://golang.org/issue/11104 for more details.