copystructure

README

copystructure

copystructure is a Go library for deep copying values in Go.

This allows you to copy Go values that may contain reference values such as maps, slices, or pointers, and copy their data as well instead of just their references.

Installation

Standard go get:

$ go get github.com/mitchellh/copystructure

Usage & Example

For usage and examples see the Godoc.

The Copy function has examples associated with it there.

Documentation

Index

• Variables
• func Copy(v interface{}) (interface{}, error)
• func Must(v interface{}, err error) interface{}
• type Config
  • func (c Config) Copy(v interface{}) (interface{}, error)
• type CopierFunc

Examples

• Copy

Variables

var Copiers map[reflect.Type]CopierFunc = make(map[reflect.Type]CopierFunc)

Copiers is a map of types that behave specially when they are copied. If a type is found in this map while deep copying, this function will be called to copy it instead of attempting to copy all fields.

The key should be the type, obtained using: reflect.TypeOf(value with type).

It is unsafe to write to this map after Copies have started. If you are writing to this map while also copying, wrap all modifications to this map as well as to Copy in a mutex.

var ShallowCopiers map[reflect.Type]struct{} = make(map[reflect.Type]struct{})

ShallowCopiers is a map of pointer types that behave specially when they are copied. If a type is found in this map while deep copying, the pointer value will be shallow copied and not walked into.

The key should be the type, obtained using: reflect.TypeOf(value with type).

It is unsafe to write to this map after Copies have started. If you are writing to this map while also copying, wrap all modifications to this map as well as to Copy in a mutex.

Functions

func Copy

func Copy(v interface{}) (interface{}, error)

Copy returns a deep copy of v.

Copy is unable to copy unexported fields in a struct (lowercase field names). Unexported fields can't be reflected by the Go runtime and therefore copystructure can't perform any data copies.

For structs, copy behavior can be controlled with struct tags. For example:

struct {
  Name string
  Data *bytes.Buffer `copy:"shallow"`
}

The available tag values are:

• "ignore" - The field will be ignored, effectively resulting in it being assigned the zero value in the copy.

• "shallow" - The field will be be shallow copied. This means that references values such as pointers, maps, slices, etc. will be directly assigned versus deep copied.

Example

input := map[string]interface{}{
	"bob": map[string]interface{}{
		"emails": []string{"a", "b"},
	},
}

dup, err := Copy(input)
if err != nil {
	panic(err)
}

fmt.Printf("%#v", dup)

Output:

map[string]interface {}{"bob":map[string]interface {}{"emails":[]string{"a", "b"}}}

func Must

func Must(v interface{}, err error) interface{}

Must is a helper that wraps a call to a function returning (interface{}, error) and panics if the error is non-nil. It is intended for use in variable initializations and should only be used when a copy error should be a crashing case.

Types

type Config

type Config struct {
	// Lock any types that are a sync.Locker and are not a mutex while copying.
	// If there is an RLocker method, use that to get the sync.Locker.
	Lock bool

	// Copiers is a map of types associated with a CopierFunc. Use the global
	// Copiers map if this is nil.
	Copiers map[reflect.Type]CopierFunc

	// ShallowCopiers is a map of pointer types that when they are
	// shallow copied no matter where they are encountered. Use the
	// global ShallowCopiers if this is nil.
	ShallowCopiers map[reflect.Type]struct{}
}

func (Config) Copy

func (c Config) Copy(v interface{}) (interface{}, error)

type CopierFunc

type CopierFunc func(interface{}) (interface{}, error)

CopierFunc is a function that knows how to deep copy a specific type. Register these globally with the Copiers variable.