copier

To start using Copier in your Go project, install it using go get:

go get -u github.com/jinzhu/copier

To ensure a field is copied but avoid application panics if it fails, use the copier:"must,nopanic" tag. In this mode, copier.Copy will return an error if the mandatory field is not found in the source.

type SafeSource struct {
	ID string
}

type SafeTarget struct {
	Code string `copier:"must,nopanic"` // Enforce copying without panic.
}

func main() {
	source := SafeSource{}
	target := SafeTarget{Code: "200"}

	if err := copier.Copy(&target, &source); err != nil {
		log.Fatalln("Error:", err)
	}
}

If the source and destination field names do not match, use the tag copier:"SourceFieldName" on the target struct field to define the mapping.

type SourceEmployee struct {
    Identifier int64
}

type TargetWorker struct {
    ID int64 `copier:"Identifier"` // Map Identifier from SourceEmployee to ID in TargetWorker
}

func main() {
	source := SourceEmployee{Identifier: 1001}
	target := TargetWorker{}

	copier.Copy(&target, &source)
}

When using copier.CopyWithOption with copier.Option{IgnoreEmpty: true}, fields with the copier:"override" tag will be copied even if the source value is empty or nil. This allows you to explicitly set a target field to a nil or zero value.

type SourceWithNil struct {
    Details *string
}

type TargetOverride struct {
    Details *string `copier:"override"` // Even if source is nil, copy it.
}

func main() {
    details := "Important details"
    source := SourceWithNil{Details: nil}
    target := TargetOverride{Details: &details}

    copier.CopyWithOption(&target, &source, copier.Option{IgnoreEmpty: true})
}

Use copier.Copy(destination, source) to copy data from one object to another. Copier supports field-to-field and method-to-field copying based on matching names. It also supports copying between slices, structs, and maps.

import "github.com/jinzhu/copier"

type User struct {
	Name string
	Role string
	Age  int32
}

type Employee struct {
	Name      string
	Age       int32
	SuperRole string
}

func main() {
	user := User{Name: "Jinzhu", Age: 18, Role: "Admin"}
	employee := Employee{}

	copier.Copy(&employee, &user)
}

Use CopyWithOption when you need to control the copying behavior, such as enabling deep copies, ignoring empty values, or providing custom type converters.

Common Option settings include:

• IgnoreEmpty: If true, zero values of fields will be ignored.
• DeepCopy: If true, performs a deep copy of the data.
• CaseSensitive: If true, field name matching is case-sensitive.
• Must: If true, all fields are treated as if they have the must tag.
• NoPanic: If true, the program returns an error instead of panicking when a must field is not copied (only effective if Must is also true).

If you need to copy data between types that aren't directly assignable or convertible, you can provide a TypeConverter.

Each converter requires a SrcType and DstType (used as templates to identify the pair) and a Fn function that performs the actual conversion.

Use the Copy function to perform a basic copy from a source value (fromValue) to a destination value (toValue). This is useful for transferring data between different struct types, slices, or maps.

Note that toValue must be a pointer or a type that can be addressed to allow the function to modify it.

The following error variables are exported by the copier package for error identification:

var (
	ErrInvalidCopyDestination        = errors.New("copy destination must be non-nil and addressable")
	ErrInvalidCopyFrom               = errors.New("copy from must be non-nil and addressable")
	ErrMapKeyNotMatch                = errors.New("map's key type doesn't match")
	ErrNotSupported                  = errors.New("not supported")
	ErrFieldNameTagStartNotUpperCase = errors.New("copier field name tag must be start upper case")
)