Documentation

Overview

    Package cmpopts provides common options for the cmp package.

    Index

    Examples

    Constants

    This section is empty.

    Variables

    View Source
    var AnyError anyError

      AnyError is an error that matches any non-nil error.

      Functions

      func AcyclicTransformer

      func AcyclicTransformer(name string, xformFunc interface{}) cmp.Option

        AcyclicTransformer returns a Transformer with a filter applied that ensures that the transformer cannot be recursively applied upon its own output.

        An example use case is a transformer that splits a string by lines:

        AcyclicTransformer("SplitLines", func(s string) []string{
        	return strings.Split(s, "\n")
        })
        

        Had this been an unfiltered Transformer instead, this would result in an infinite cycle converting a string to []string to [][]string and so on.

        func EquateApprox

        func EquateApprox(fraction, margin float64) cmp.Option

          EquateApprox returns a Comparer option that determines float32 or float64 values to be equal if they are within a relative fraction or absolute margin. This option is not used when either x or y is NaN or infinite.

          The fraction determines that the difference of two values must be within the smaller fraction of the two values, while the margin determines that the two values must be within some absolute margin. To express only a fraction or only a margin, use 0 for the other parameter. 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.

          func EquateApproxTime

          func EquateApproxTime(margin time.Duration) cmp.Option

            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 EquateEmpty

            func EquateEmpty() cmp.Option

              EquateEmpty returns a Comparer option that determines all maps and slices with a length of zero to be equal, regardless of whether they are nil.

              EquateEmpty can be used in conjunction with SortSlices and SortMaps.

              func EquateErrors

              func EquateErrors() cmp.Option

                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 EquateNaNs

                func EquateNaNs() cmp.Option

                  EquateNaNs returns a Comparer option that determines float32 and float64 NaN values to be equal.

                  EquateNaNs can be used in conjunction with EquateApprox.

                  func IgnoreFields

                  func IgnoreFields(typ interface{}, names ...string) cmp.Option

                    IgnoreFields returns an Option that ignores fields of the given names on a single struct type. It respects the names of exported fields that are forwarded due to struct embedding. The struct type is specified by passing in a value of that type.

                    The name may be a dot-delimited string (e.g., "Foo.Bar") to ignore a specific sub-field that is embedded or nested within the parent struct.

                    Example (Testing)

                      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{}).

                      Output:
                      
                      MakeGatewayInfo() mismatch (-want +got):
                        cmpopts_test.Gateway{
                        	SSID:      "CoffeeShopWiFi",
                      - 	IPAddress: s"192.168.0.2",
                      + 	IPAddress: s"192.168.0.1",
                        	NetMask:   {0xff, 0xff, 0x00, 0x00},
                        	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",
                      + 		},
                        	},
                        }
                      

                      func IgnoreInterfaces

                      func IgnoreInterfaces(ifaces interface{}) cmp.Option

                        IgnoreInterfaces returns an Option that ignores all values or references of values assignable to certain interface types. These interfaces are specified by passing in an anonymous struct with the interface types embedded in it. For example, to ignore sync.Locker, pass in struct{sync.Locker}{}.

                        func IgnoreMapEntries

                        func IgnoreMapEntries(discardFunc interface{}) cmp.Option

                          IgnoreMapEntries returns an Option that ignores entries of map[K]V. The discard function must be of the form "func(T, R) bool" which is used to ignore map entries of type K and V, where K and V are assignable to T and R. Entries are ignored if the function reports true.

                          func IgnoreSliceElements

                          func IgnoreSliceElements(discardFunc interface{}) cmp.Option

                            IgnoreSliceElements returns an Option that ignores elements of []V. The discard function must be of the form "func(T) bool" which is used to ignore slice elements of type V, where V is assignable to T. Elements are ignored if the function reports true.

                            func IgnoreTypes

                            func IgnoreTypes(typs ...interface{}) cmp.Option

                              IgnoreTypes returns an Option that ignores all values assignable to certain types, which are specified by passing in a value of each type.

                              func IgnoreUnexported

                              func IgnoreUnexported(typs ...interface{}) cmp.Option

                                IgnoreUnexported returns an Option that only ignores the immediate unexported fields of a struct, including anonymous fields of unexported types. In particular, unexported fields within the struct's exported fields of struct types, including anonymous fields, will not be ignored unless the type of the field itself is also passed to IgnoreUnexported.

                                Avoid ignoring unexported fields of a type which you do not control (i.e. a type from another repository), as changes to the implementation of such types may change how the comparison behaves. Prefer a custom Comparer instead.

                                func SortMaps

                                func SortMaps(lessFunc interface{}) cmp.Option

                                  SortMaps returns a Transformer option that flattens map[K]V types to be a sorted []struct{K, V}. The less function must be of the form "func(T, T) bool" which is used to sort any map with key K that is assignable to T.

                                  Flattening the map into a slice has the property that cmp.Equal is able to use Comparers on K or the K.Equal method if it exists.

                                  The less function must be:

                                  • Deterministic: less(x, y) == less(x, y)
                                  • Irreflexive: !less(x, x)
                                  • Transitive: if !less(x, y) and !less(y, z), then !less(x, z)
                                  • Total: if x != y, then either less(x, y) or less(y, x)
                                  

                                  SortMaps can be used in conjunction with EquateEmpty.

                                  func SortSlices

                                  func SortSlices(lessFunc interface{}) cmp.Option

                                    SortSlices returns a Transformer option that sorts all []V. The less function must be of the form "func(T, T) bool" which is used to sort any slice with element type V that is assignable to T.

                                    The less function must be:

                                    • Deterministic: less(x, y) == less(x, y)
                                    • Irreflexive: !less(x, x)
                                    • Transitive: if !less(x, y) and !less(y, z), then !less(x, z)
                                    

                                    The less function does not have to be "total". That is, if !less(x, y) and !less(y, x) for two elements x and y, their relative order is maintained.

                                    SortSlices can be used in conjunction with EquateEmpty.

                                    Types

                                    This section is empty.