structs

README

structs

Go library for encoding native Go structures into generic map values.

Installation

Use go get.

    go get -u github.com/things-go/structs

Then import the structs package into your own code.

    import "github.com/things-go/structs"

Usage && Example

API

// Encode takes an input structure and uses reflection to translate it to
// the output map[string]interface{} with default tag "map"
func Encode(input interface{}) map[string]interface{}

// Encode takes an input structure and uses reflection to translate it to
// the output map[string]interface{} with the custom tag name
func EncodeWithTag(input interface{}, tagName string) map[string]interface{}

This function converts a struct to map. To use this function, import it first:

import "github.com/things-go/structs"

Here is an example:

m := structs.Encode(struct {
    Id      int64
    Name    string
    }{
        Id:        1001,
        Name:      "structs",
    })
/*
    map[string]interface{}{
        "Id": 1001,  
        "Name": "structs",
    }
*/

Encode will create and return a new map from the given struct. The keys of the map will be the name of fields. The values will be the value of fields.

Only public fields will be processed. So fields starting with lowercase will be ignored.

Name Tags

type AA struct {
    Id        int64    `map:"id"`
    Name      string   `map:"name"`
}

We can give the field a tag to specify another name to be used as the key.

Ignore Field

type AA struct {
    Ignore string `map:"-"`
}

If we give the special tag "-" to a field, it will be ignored.

Omit Empty

type AA struct {
    Desc        string    `map:"desc,omitempty"`
}

If tag option is "omitempty", this field will not appear in the map if the value is empty. Empty values are 0, false, "", nil, empty array and empty map.

To String

type AA struct {
    Id        int64    `map:"id,string"`
    Price     float32  `map:"price,string"`
}

If tag option is "string", this field will be converted to string type. Encode will put the original value to the map if the conversion is failed.

References

• mapstructure

License

This project is under MIT License. See the LICENSE file for the full license text.

Documentation

Overview

Package structs Go library for encoding native Go structures into generic map values.

The simplest function to start with is Encoded.

Field Tags

When encode to a map[string]interface{}, structs will use the field name by default to perform the mapping. For example, if a struct has a field "Username" then structs will use a key "Username".

type User struct {
    Username string
}

You can change the behavior of structs by using struct tags. The default struct tag that structs looks for is "map" but you can customize it using EncodeWithTag.

Renaming Fields

To rename the key that structs looks for, use the "map" tag and set a value directly. For example, to change the "username" example above to "user":

type User struct {
    Username string `map:"user"`
}

Embedded Structs

Embedded structs are treated as if they're another field with that name.

type Person struct {
    Name string `map:"name"`
}

type Friend struct {
    Person
}

This would output that looks like below:

map[string]interface{}{
    "name": "alice",
}

Omit Empty Values

When encoding from a struct to any other value, you may use the ",omitempty" suffix on your tag to omit that value if it equates to the zero value. The zero value of all types is specified in the Go specification.

For example, the zero type of a numeric type is zero ("0"). If the struct field value is zero and a numeric type, the field is empty, and it won't be encoded into the destination type.

type Source {
    Age int `map:",omitempty"`
}

Unexported fields

Since unexported (private) struct fields cannot be set outside the package where they are defined, the encoder will simply skip them.

For this input type definition:

type Exported struct {
    private string // this unexported field will be skipped
    Public string
}

this map as output:

map[string]interface{}{
    "Public":  "I made it through!",
}

Index

• Constants
• func Encode(input interface{}) map[string]interface{}
• func EncodeWithTag(input interface{}, tagName string) map[string]interface{}

Constants

const DefaultTag = "map"

Functions

func Encode

func Encode(input interface{}) map[string]interface{}

Encode takes an input structure and uses reflection to translate it to the output map[string]interface{} with default tag "map"

func EncodeWithTag

func EncodeWithTag(input interface{}, tagName string) map[string]interface{}

EncodeWithTag takes an input structure and uses reflection to translate it to the output map[string]interface{} with the custom tag name