deepcopy

README

Fast deep-copy library for Go

Functionalities

• True deep copy
• Very fast (see benchmarks section)
• Ability to copy data between convertible types (for example: copy from int to float)
• Ability to copy between pointers and values (for example: copy from *int to int)
• Ability to copy between struct fields and methods
• Ability to copy between unexported struct fields
• Ability to configure copying behavior

Installation

go get github.com/tiendc/go-deepcopy

Usage

• First example
• Copy between struct fields with different names
• Ignore copying struct fields
• Copy between struct fields and methods
• Copy between unexported struct fields
• Configure copying behavior

First example

Playground

    type SS struct {
        B bool
    }
    type S struct {
        I  int
        U  uint
        St string
        V  SS
    }
    type DD struct {
        B bool
    }
    type D struct {
        I int
        U uint
        X string
        V DD
    }
    src := []S{{I: 1, U: 2, St: "3", V: SS{B: true}}, {I: 11, U: 22, St: "33", V: SS{B: false}}}
    var dst []D
    _ = deepcopy.Copy(&dst, src)

    for _, d := range dst {
        fmt.Printf("%+v\n", d)
    }

    // Output:
    // {I:1 U:2 X: V:{B:true}}
    // {I:11 U:22 X: V:{B:false}}

Copy between struct fields with different names

Playground

    type S struct {
        X  int    `copy:"Key"` // 'Key' is used to match the fields
        U  uint
        St string
    }
    type D struct {
        Y int     `copy:"Key"`
        U uint
    }
    src := []S{{X: 1, U: 2, St: "3"}, {X: 11, U: 22, St: "33"}}
    var dst []D
    _ = deepcopy.Copy(&dst, src)

    for _, d := range dst {
        fmt.Printf("%+v\n", d)
    }

    // Output:
    // {Y:1 U:2}
    // {Y:11 U:22}

Ignore copying struct fields

• By default, matching fields will be copied. If you don't want to copy a field, use tag -.

  Playground

    // S and D both have `I` field, but we don't want to copy it
    // Tag `-` can be used in both struct definitions or just in one
    type S struct {
        I  int
        U  uint
        St string
    }
    type D struct {
        I int `copy:"-"`
        U uint
    }
    src := []S{{I: 1, U: 2, St: "3"}, {I: 11, U: 22, St: "33"}}
    var dst []D
    _ = deepcopy.Copy(&dst, src)

    for _, d := range dst {
        fmt.Printf("%+v\n", d)
    }

    // Output:
    // {I:0 U:2}
    // {I:0 U:22}

Copy between struct fields and methods

Playground 1 / Playground 2

type S struct {
    X  int
    U  uint
    St string
}

type D struct {
    x string
    U uint
}

// Copy method should be in form of `Copy<source-field>` (or key) and return `error` type
func (d *D) CopyX(i int) error {
    d.x = fmt.Sprintf("%d", i)
    return nil
}

    src := []S{{X: 1, U: 2, St: "3"}, {X: 11, U: 22, St: "33"}}
    var dst []D
    _ = deepcopy.Copy(&dst, src)

    for _, d := range dst {
        fmt.Printf("%+v\n", d)
    }

    // Output:
    // {x:1 U:2}
    // {x:11 U:22}

Copy between unexported struct fields

• By default, unexported struct fields will be ignored when copy. If you want to copy them, use tag required.

  Playground

    type S struct {
        i  int
        U  uint
        St string
    }
    type D struct {
        i int `copy:",required"`
        U uint
    }
    src := []S{{i: 1, U: 2, St: "3"}, {i: 11, U: 22, St: "33"}}
    var dst []D
    _ = deepcopy.Copy(&dst, src)

    for _, d := range dst {
        fmt.Printf("%+v\n", d)
    }

    // Output:
    // {i:1 U:2}
    // {i:11 U:22}

Configure copying behavior

• Not allow to copy between ptr type and value (default is allow)

  Playground

    type S struct {
        I  int
        U  uint
    }
    type D struct {
        I *int
        U uint
    }
    src := []S{{I: 1, U: 2}, {I: 11, U: 22}}
    var dst []D
    err := deepcopy.Copy(&dst, src, deepcopy.CopyBetweenPtrAndValue(false))
    fmt.Println("error:", err)

    // Output:
    // error: ErrTypeNonCopyable: int -> *int

• Ignore ErrTypeNonCopyable, the process will not return that error, but some copying won't be performed.

  Playground 1 / Playground 2

    type S struct {
        I []int
        U uint
    }
    type D struct {
        I int
        U uint
    }
    src := []S{{I: []int{1, 2, 3}, U: 2}, {I: []int{1, 2, 3}, U: 22}}
    var dst []D
    // The copy will succeed with ignoring copy of field `I`
    _ = deepcopy.Copy(&dst, src, deepcopy.IgnoreNonCopyableTypes(true))

    for _, d := range dst {
        fmt.Printf("%+v\n", d)
    }

    // Output:
    // {I:0 U:2}
    // {I:0 U:22}

Benchmarks

Go-DeepCopy vs ManualCopy vs JinzhuCopier vs Deepcopier

Benchmark code

BenchmarkCopy/Go-DeepCopy
BenchmarkCopy/Go-DeepCopy-10         	 1712484	       685.5 ns/op

BenchmarkCopy/ManualCopy
BenchmarkCopy/ManualCopy-10          	27953836	        41.14 ns/op

BenchmarkCopy/JinzhuCopier
BenchmarkCopy/JinzhuCopier-10        	  129792	      9177 ns/op

BenchmarkCopy/Deepcopier
BenchmarkCopy/Deepcopier-10          	   42990	     27988 ns/op

Contributing

• You are welcome to make pull requests for new functions and bug fixes.

License

• MIT License

Documentation

Index

• Constants
• Variables
• func ClearCache()
• func Copy(dst, src any, options ...Option) (err error)
• type Context
• type Option
  • func CopyBetweenPtrAndValue(flag bool) Option
  • func CopyBetweenStructFieldAndMethod(flag bool) Option
  • func IgnoreNonCopyableTypes(flag bool) Option
  • func UseGlobalCache(flag bool) Option

Constants

const (
	// DefaultTagName default tag name for the program to parse input struct tags
	// to build copier configuration.
	DefaultTagName = "copy"
)

Variables

var (
	// ErrTypeInvalid returned when type of input var does not meet the requirement
	ErrTypeInvalid = errors.New("ErrTypeInvalid")
	// ErrTypeNonCopyable returned when the function can not perform copying between types
	ErrTypeNonCopyable = errors.New("ErrTypeNonCopyable")
	// ErrValueInvalid returned when input value does not meet the requirement
	ErrValueInvalid = errors.New("ErrValueInvalid")
	// ErrValueUnaddressable returned when value is `unaddressable` which is required
	// in some situations such as when accessing an unexported struct field.
	ErrValueUnaddressable = errors.New("ErrValueUnaddressable")
	// ErrFieldRequireCopying returned when a field is required to be copied
	// but no copying is done for it.
	ErrFieldRequireCopying = errors.New("ErrFieldRequireCopying")
)

Errors may be returned from Copy function

Functions

func ClearCache

func ClearCache()

ClearCache clears global cache of previously used copiers

func Copy

func Copy(dst, src any, options ...Option) (err error)

Copy performs deep copy from `src` to `dst`.

`dst` must be a pointer to the output var, `src` can be either value or pointer. In case you want to copy unexported struct fields within `src`, `src` must be a pointer.

Types

type Context

type Context struct {
	// CopyBetweenPtrAndValue allow or not copying between pointers and values (default is `true`)
	CopyBetweenPtrAndValue bool

	// CopyBetweenStructFieldAndMethod allow or not copying between struct fields and methods (default is `true`)
	CopyBetweenStructFieldAndMethod bool

	// IgnoreNonCopyableTypes ignore non-copyable types (default is `false`)
	IgnoreNonCopyableTypes bool

	// UseGlobalCache if false not use global cache (default is `true`)
	UseGlobalCache bool
	// contains filtered or unexported fields
}

Context copier context

type Option

type Option func(ctx *Context)

Option configuration option function provided as extra arguments of copying function

func CopyBetweenPtrAndValue

func CopyBetweenPtrAndValue(flag bool) Option

CopyBetweenPtrAndValue config function for setting flag `CopyBetweenPtrAndValue`

func CopyBetweenStructFieldAndMethod

func CopyBetweenStructFieldAndMethod(flag bool) Option

CopyBetweenStructFieldAndMethod config function for setting flag `CopyBetweenStructFieldAndMethod`

func IgnoreNonCopyableTypes

func IgnoreNonCopyableTypes(flag bool) Option

IgnoreNonCopyableTypes config function for setting flag `IgnoreNonCopyableTypes`

func UseGlobalCache

func UseGlobalCache(flag bool) Option

UseGlobalCache config function for setting flag `UseGlobalCache`