clone

README

go-clone: Deep clone any Go data

Package clone provides functions to deep clone any Go data. It also provides a wrapper to protect a pointer from any unexpected mutation.

Clone/Slowly can clone unexported fields and "no-copy" structs as well. Use this feature wisely.

Install

Use go get to install this package.

go get github.com/huandu/go-clone

Usage

Clone and Slowly

If we want to clone any Go value, use Clone.

t := &T{...}
v := clone.Clone(t).(*T)
reflect.DeepEqual(t, v) // true

For the sake of performance, Clone doesn't deal with values containing pointer cycles. If we need to clone such values, use Slowly instead.

type ListNode struct {
    Data int
    Next *ListNode
}
node1 := &ListNode{
    Data: 1,
}
node2 := &ListNode{
    Data: 2,
}
node3 := &ListNode{
    Data: 3,
}
node1.Next = node2
node2.Next = node3
node3.Next = node1

// We must use `Slowly` to clone a circular linked list.
node := Slowly(node1).(*ListNode)

for i := 0; i < 10; i++ {
    fmt.Println(node.Data)
    node = node.Next
}

Mark struct type as scalar

Some struct types can be considered as scalar.

A well-known case is time.Time. Although there is a pointer loc *time.Location inside time.Time, we always use time.Time by value in all methods. When cloning time.Time, it should be OK to return a shadow copy.

Currently, following types are marked as scalar by default.

• time.Time
• reflect.Value

If there is any type defined in built-in package should be considered as scalar, please open new issue to let me know. I will update the default.

If there is any custom type should be considered as scalar, call MarkAsScalar to mark it manually. See MarkAsScalar sample code for more details.

Clone "no-copy" structs defined in sync and sync/atomic

There are some "no-copy" types like sync.Mutex, atomic.Value, etc. They cannot be cloned by copying all fields one by one, but we can alloc a new zero value and call methods to do proper initialization.

Currently, following "no-copy" types can be cloned properly.

• sync.Mutex: Cloned value is a newly allocated zero mutex.
• sync.RWMutex: Cloned value is a newly allocated zero mutex.
• sync.WaitGroup: Cloned value is a newly allocated zero wait group.
• *sync.Cond: Cloned value is a cond with a newly allocated zero lock.
• sync.Pool: Cloned value is an empty pool with the same New function.
• sync.Map: Cloned value is a sync map with cloned key/value pairs.
• sync.Once: Cloned value is a once type with the same done flag.
• atomic.Value: Cloned value is a new atomic value with the same value.

If there is any type defined in built-in package should be considered as "no-copy" types, please open new issue to let me know. I will update the default.

SSet custom clone function

If default clone strategy doesn't work for some custom types, we can call SetCustomFunc to clone it manually.

See SetCustomFunc sample code for more details.

Wrap, Unwrap and Undo

Package clone provides Wrap/Unwrap functions to protect a pointer value from any unexpected mutation. It's useful when we want to protect a variable which should be immutable by design, e.g. global config, the value stored in context, the value sent to a chan, etc.

// Suppose we have a type T defined as following.
//     type T struct {
//         Foo int
//     }
v := &T{
    Foo: 123,
}
w := Wrap(v).(*T) // Wrap value to protect it.

// Use w freely. The type of w is the same as that of v.

// It's OK to modify w. The change will not affect v.
w.Foo = 456
fmt.Println(w.Foo) // 456
fmt.Println(v.Foo) // 123

// Once we need the original value stored in w, call `Unwrap`.
orig := Unwrap(w).(*T)
fmt.Println(orig == v) // true
fmt.Println(orig.Foo)  // 123

// Or, we can simply undo any change made in w.
// Note that `Undo` is significantly slower than `Unwrap`, thus
// the latter is always preferred.
Undo(w)
fmt.Println(w.Foo) // 123

Performance

Here is the performance data running on my MacBook Pro.

MacBook Pro (15-inch, 2019)
Processor: 2.6 GHz Intel Core i7

go 1.15.8
goos: darwin
goarch: amd64
pkg: github.com/huandu/go-clone

BenchmarkSimpleClone-12          8325153               137 ns/op              32 B/op          1 allocs/op
BenchmarkComplexClone-12          540330              2190 ns/op            1488 B/op         24 allocs/op
BenchmarkUnwrap-12              12075483                96.8 ns/op             0 B/op          0 allocs/op
BenchmarkSimpleWrap-12           3233422               373 ns/op              80 B/op          2 allocs/op
BenchmarkComplexWrap-12           757730              1498 ns/op             752 B/op         16 allocs/op

License

This package is licensed under MIT license. See LICENSE for details.

Documentation

Overview

Package clone provides functions to deep clone any Go data. It also provides a wrapper to protect a pointer from any unexpected mutation.

Index

• func Clone(v interface{}) interface{}
• func MarkAsScalar(t reflect.Type)
• func SetCustomFunc(t reflect.Type, fn Func)
• func Slowly(v interface{}) interface{}
• func Undo(v interface{})
• func Unwrap(v interface{}) interface{}
• func Wrap(v interface{}) interface{}
• type Func

Examples

• MarkAsScalar
• SetCustomFunc
• Slowly
• Wrap

Functions

func Clone

func Clone(v interface{}) interface{}

Clone recursively deep clone v to a new value. It assumes that there is no pointer cycle in v, e.g. v has a pointer points to v itself. If there is a pointer cycle, use Slowly instead.

Clone allocates memory and deeply copies values inside v in depth-first sequence. There are a few special rules for following types.

• Scalar types: all number-like types are copied by value.
• func: Copied by value as func is an opaque pointer at runtime.
• string: Copied by value as string is immutable by design.
• unsafe.Pointer: Copied by value as we don't know what's in it.
• chan: A new empty chan is created as we cannot read data inside the old chan.

Unlike many other packages, Clone is able to clone unexported fields of any struct. Use this feature wisely.

func MarkAsScalar

func MarkAsScalar(t reflect.Type)

MarkAsScalar marks t as a scalar type so that all clone methods will copy t by value. If t is not struct or pointer to struct, MarkAsScalar ignores t.

In the most cases, it's not necessary to call it explicitly. If a struct type contains scalar type fields only, the struct will be marked as scalar automatically.

Here is a list of types marked as scalar by default:

• time.Time
• reflect.Value

Example

package main

import (
	"fmt"
	"os"
	"reflect"
)

type ScalarType struct {
	stderr *os.File
}

func main() {
	MarkAsScalar(reflect.TypeOf(new(ScalarType)))

	scalar := &ScalarType{
		stderr: os.Stderr,
	}
	cloned := Clone(scalar).(*ScalarType)

	// cloned is a shadow copy of scalar
	// so that the pointer value should be the same.
	fmt.Println(scalar.stderr == cloned.stderr)

}

Output:

true

func SetCustomFunc

func SetCustomFunc(t reflect.Type, fn Func)

SetCustomFunc sets a custom clone function for type t. If t is not struct or pointer to struct, SetCustomFunc ignores t.

Example

type MyStruct struct {
	Data []interface{}
}

// Filter nil values in Data when cloning old value.
SetCustomFunc(reflect.TypeOf(MyStruct{}), func(old, new reflect.Value) {
	var value MyStruct

	// The old is guaranteed to be a MyStruct.
	data := old.FieldByName("Data")
	l := data.Len()

	for i := 0; i < l; i++ {
		v := data.Index(i)

		if v.IsNil() {
			continue
		}

		n := Clone(v.Interface())
		value.Data = append(value.Data, n)
	}

	// The new is a zero value of MySlice.
	// Set new to slice to return value to outside.
	new.Set(reflect.ValueOf(value))
})

slice := &MyStruct{
	Data: []interface{}{
		"abc", nil, 123, nil,
	},
}
cloned := Clone(slice).(*MyStruct)
fmt.Println(cloned.Data)

Output:

[abc 123]

func Slowly

func Slowly(v interface{}) interface{}

Slowly recursively deep clone v to a new value. It marks all cloned values internally, thus it can clone v with cycle pointer.

Slowly works exactly the same as Clone. See Clone doc for more details.

Example

type ListNode struct {
	Data int
	Next *ListNode
}
node1 := &ListNode{
	Data: 1,
}
node2 := &ListNode{
	Data: 2,
}
node3 := &ListNode{
	Data: 3,
}
node1.Next = node2
node2.Next = node3
node3.Next = node1

// We must use `Slowly` to clone a circular linked list.
node := Slowly(node1).(*ListNode)

for i := 0; i < 10; i++ {
	fmt.Println(node.Data)
	node = node.Next
}

Output:

1
2
3
1
2
3
1
2
3
1

func Undo

func Undo(v interface{})

Undo discards any change made in wrapped value. If v is not a wrapped value, nothing happens.

func Unwrap

func Unwrap(v interface{}) interface{}

Unwrap returns v's original value if v is a wrapped value. Otherwise, simply returns v itself.

func Wrap

func Wrap(v interface{}) interface{}

Wrap creates a wrapper of v, which must be a pointer. If v is not a pointer, Wrap simply returns v and do nothing.

The wrapper is a deep clone of v's value. It holds a shadow copy to v internally.

t := &T{Foo: 123}
v := Wrap(t).(*T)               // v is a clone of t.
reflect.DeepEqual(t, v) == true // v equals t.
v.Foo = 456                     // v.Foo is changed, but t.Foo doesn't change.
orig := Unwrap(v)               // Use `Unwrap` to discard wrapper and return original value, which is t.
orig.(*T) == t                  // orig and t is exactly the same.
Undo(v)                         // Use `Undo` to discard any change on v.
v.Foo == t.Foo                  // Now, the value of v and t are the same again.

Example

// Suppose we have a type T defined as following.
//     type T struct {
//         Foo int
//     }
v := &T{
	Foo: 123,
}
w := Wrap(v).(*T) // Wrap value to protect it.

// Use w freely. The type of w is the same as that of v.

// It's OK to modify w. The change will not affect v.
w.Foo = 456
fmt.Println(w.Foo) // 456
fmt.Println(v.Foo) // 123

// Once we need the original value stored in w, call `Unwrap`.
orig := Unwrap(w).(*T)
fmt.Println(orig == v) // true
fmt.Println(orig.Foo)  // 123

// Or, we can simply undo any change made in w.
// Note that `Undo` is significantly slower than `Unwrap`, thus
// the latter is always preferred.
Undo(w)
fmt.Println(w.Foo) // 123

Output:

456
123
true
123
123

Types

type Func

type Func func(old, new reflect.Value)

Func is a custom func to clone value from old to new. The new is a zero value which `new.CanSet()` and `new.CanAddr()` is guaranteed to be true.

Func must update the new to return result.