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.

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 recursive pointers. 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
}

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

goos: darwin
goarch: amd64
pkg: github.com/huandu/go-clone
BenchmarkSimpleClone-12     	10000000	       147 ns/op	      32 B/op	       1 allocs/op
BenchmarkComplexClone-12    	 1000000	      1823 ns/op	    1376 B/op	      19 allocs/op
BenchmarkUnwrap-12          	20000000	        96.9 ns/op	       0 B/op	       0 allocs/op
BenchmarkSimpleWrap-12      	 5000000	       289 ns/op	      48 B/op	       1 allocs/op
BenchmarkComplexWrap-12     	 1000000	      1298 ns/op	     656 B/op	      12 allocs/op

Similar packages

• Package encoding/gob: Gob encoder/decoder can be used to clone Go data. However, it's extremely slow.
• Package github.com/jinzhu/copier: Copy data by field name. It doesn't work with values containing recursive pointers.
• Package github.com/ulule/deepcopier: Another copier.

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 Slowly(v interface{}) interface{}
• func Undo(v interface{})
• func Unwrap(v interface{}) interface{}
• func Wrap(v interface{}) interface{}

Examples

• 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 recursive pointers in v, e.g. v has a pointer points to v itself.

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 recursive pointers in v.

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