README

hashstructure

hashstructure is a Go library for creating a unique hash value for arbitrary values in Go.

This can be used to key values in a hash (for use in a map, set, etc.) that are complex. The most common use case is comparing two values without sending data across the network, caching values locally (de-dup), and so on.

Features

  • Hash any arbitrary Go value, including complex types.

  • Tag a struct field to ignore it and not affect the hash value.

  • Tag a slice type struct field to treat it as a set where ordering doesn't affect the hash code but the field itself is still taken into account to create the hash value.

  • Optionally specify a custom hash function to optimize for speed, collision avoidance for your data set, etc.

Installation

Standard go get:

$ go get github.com/mitchellh/hashstructure

Usage & Example

For usage and examples see the Godoc.

A quick code example is shown below:

type ComplexStruct struct {
    Name     string
    Age      uint
    Metadata map[string]interface{}
}

v := ComplexStruct{
    Name: "mitchellh",
    Age:  64,
    Metadata: map[string]interface{}{
        "car":      true,
        "location": "California",
        "siblings": []string{"Bob", "John"},
    },
}

hash, err := hashstructure.Hash(v, nil)
if err != nil {
    panic(err)
}

fmt.Printf("%d", hash)
// Output:
// 2307517237273902113

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Hash

func Hash(v interface{}, opts *HashOptions) (uint64, error)

    Hash returns the hash value of an arbitrary value.

    If opts is nil, then default options will be used. See HashOptions for the default values.

    Notes on the value:

    * Unexported fields on structs are ignored and do not affect the
      hash value.
    
    * Adding an exported field to a struct with the zero value will change
      the hash value.
    

    For structs, the hashing can be controlled using tags. For example:

    struct {
        Name string
        UUID string `hash:"ignore"`
    }
    

    The available tag values are:

    * "ignore" - The field will be ignored and not affect the hash code.
    
    * "set" - The field will be treated as a set, where ordering doesn't
              affect the hash code. This only works for slices.
    

    Types

    type HashOptions

    type HashOptions struct {
    	// Hasher is the hash function to use. If this isn't set, it will
    	// default to FNV.
    	Hasher hash.Hash64
    
    	// TagName is the struct tag to look at when hashing the structure.
    	// By default this is "hash".
    	TagName string
    }

      HashOptions are options that are available for hashing.

      type Includable

      type Includable interface {
      	HashInclude(field string, v interface{}) (bool, error)
      }

        Includable is an interface that can optionally be implemented by a struct. It will be called for each field in the struct to check whether it should be included in the hash.

        type IncludableMap

        type IncludableMap interface {
        	HashIncludeMap(field string, k, v interface{}) (bool, error)
        }

          IncludableMap is an interface that can optionally be implemented by a struct. It will be called when a map-type field is found to ask the struct if the map item should be included in the hash.