Skip to main content
Version: 2.8.x(Latest)
tip

The following list of common methods may lag behind the features of the code in the documentation update. Please refer to the code documentation for more methods and examples: https://pkg.go.dev/github.com/gogf/gf/v2/container/gmap

New

  • Description: New creates and returns an empty AnyAnyMap. The parameter safe is used to specify whether to use a concurrency-safe map, which is false by default.

  • Format:

New(safe ...bool) *Map
  • Example:
func ExampleNew() {
m := gmap.New()

// Add data.
m.Set("key1", "val1")

// Print size.
fmt.Println(m.Size())

addMap := make(map[interface{}]interface{})
addMap["key2"] = "val2"
addMap["key3"] = "val3"
addMap[1] = 1

fmt.Println(m.Values())

// Batch add data.
m.Sets(addMap)

// Gets the value of the corresponding key.
fmt.Println(m.Get("key3"))

// Get the value by key, or set it with given key-value if not exist.
fmt.Println(m.GetOrSet("key4", "val4"))

// Set key-value if the key does not exist, then return true; or else return false.
fmt.Println(m.SetIfNotExist("key3", "val3"))

// Remove key
m.Remove("key2")
fmt.Println(m.Keys())

// Batch remove keys.
m.Removes([]interface{}{"key1", 1})
fmt.Println(m.Keys())

// Contains checks whether a key exists.
fmt.Println(m.Contains("key3"))

// Flip exchanges key-value of the map, it will change key-value to value-key.
m.Flip()
fmt.Println(m.Map())

// Clear deletes all data of the map.
m.Clear()

fmt.Println(m.Size())

// May Output:
// 1
// [val1]
// val3
// val4
// false
// [key4 key1 key3 1]
// [key4 key3]
// true
// map[val3:key3 val4:key4]
// 0
}

NewFrom

  • Description: NewFrom creates and returns an AnyAnyMap with the data of the given map.

  • Note: The input parameter map will be set as the underlying data mapping (without deep copy), so external changes to the map may introduce some safety issues simultaneously. Optional argument safe specifies whether to use this structure in concurrency safety, default is false.

  • Format:

NewFrom(data map[interface{}]interface{}, safe ...bool) *Map
  • Example:
func ExampleNewFrom() {
m := gmap.New()

m.Set("key1", "val1")
fmt.Println(m)

n := gmap.NewFrom(m.MapCopy(), true)
fmt.Println(n)

// Output:
// {"key1":"val1"}
// {"key1":"val1"}
}

Iterator

  • Description: Iterator iterates through the hashmap in a read-only manner using a custom callback function f. If f returns true, it continues iterating, if it returns false, it stops.

  • Format:

Iterator(f func(k interface{}, v interface{}) bool)
  • Example:
func ExampleAnyAnyMap_Iterator() {
m := gmap.New()
for i := 0; i < 10; i++ {
m.Set(i, i*2)
}

var totalKey, totalValue int
m.Iterator(func(k interface{}, v interface{}) bool {
totalKey += k.(int)
totalValue += v.(int)

return totalKey < 10
})

fmt.Println("totalKey:", totalKey)
fmt.Println("totalValue:", totalValue)

// May Output:
// totalKey: 11
// totalValue: 22
}

Clone

  • Description: Clone returns a new AnyAnyMap, which contains a copy of the current map data.

  • Format:

Clone(safe ...bool) *AnyAnyMap
  • Example:
func ExampleAnyAnyMap_Clone() {
m := gmap.New()

m.Set("key1", "val1")
fmt.Println(m)

n := m.Clone()
fmt.Println(n)

// Output:
// {"key1":"val1"}
// {"key1":"val1"}
}

Map

  • Description: Map returns the underlying data map.

  • Note: If in concurrency safety, it returns a copy of the underlying data, otherwise it returns a pointer pointing to the underlying data.

  • Format:

Map() map[interface{}]interface{}
  • Example:
func ExampleAnyAnyMap_Map() {
// non concurrent-safety, a pointer to the underlying data
m1 := gmap.New()
m1.Set("key1", "val1")
fmt.Println("m1:", m1)

n1 := m1.Map()
fmt.Println("before n1:", n1)
m1.Set("key1", "val2")
fmt.Println("after n1:", n1)

// concurrent-safety, copy of underlying data
m2 := gmap.New(true)
m2.Set("key1", "val1")
fmt.Println("m1:", m2)

n2 := m2.Map()
fmt.Println("before n2:", n2)
m2.Set("key1", "val2")
fmt.Println("after n2:", n2)

// Output:
// m1: {"key1":"val1"}
// before n1: map[key1:val1]
// after n1: map[key1:val2]
// m1: {"key1":"val1"}
// before n2: map[key1:val1]
// after n2: map[key1:val1]
}

MapCopy

  • Description: MapCopy returns a copy of the data in the map.

  • Format:

MapCopy() map[interface{}]interface{}
  • Example:
func ExampleAnyAnyMap_MapCopy() {
m := gmap.New()

m.Set("key1", "val1")
m.Set("key2", "val2")
fmt.Println(m)

n := m.MapCopy()
fmt.Println(n)

// Output:
// {"key1":"val1","key2":"val2"}
// map[key1:val1 key2:val2]
}

MapStrAny

  • Description: MapStrAny returns a copy of the map's data in the form of map[string]interface{}.

  • Format:

MapStrAny() map[string]interface{}
  • Example:
func ExampleAnyAnyMap_MapStrAny() {
m := gmap.New()
m.Set(1001, "val1")
m.Set(1002, "val2")

n := m.MapStrAny()
fmt.Println(n)

// Output:
// map[1001:val1 1002:val2]
}

FilterEmpty

  • Description: FilterEmpty removes all key-value pairs with empty values. Values such as 0, nil, false, "", len(slice/map/chan) == 0 are considered empty.

  • Format:

FilterEmpty()
  • Example:
func ExampleAnyAnyMap_FilterEmpty() {
m := gmap.NewFrom(g.MapAnyAny{
"k1": "",
"k2": nil,
"k3": 0,
"k4": 1,
})
m.FilterEmpty()
fmt.Println(m.Map())

// Output:
// map[k4:1]
}

FilterNil

  • Description: FilterNil removes all key-value pairs where the value is nil.

  • Format:

FilterNil()
  • Example:
func ExampleAnyAnyMap_FilterNil() {
m := gmap.NewFrom(g.MapAnyAny{
"k1": "",
"k2": nil,
"k3": 0,
"k4": 1,
})
m.FilterNil()
fmt.Println(m.Map())

// May Output:
// map[k1: k3:0 k4:1]
}

Set

  • Description: Set sets the key/value for the map.

  • Format:

Set(key interface{}, value interface{})
  • Example:
func ExampleAnyAnyMap_Set() {
m := gmap.New()

m.Set("key1", "val1")
fmt.Println(m)

// Output:
// {"key1":"val1"}
}

Sets

  • Description: Sets sets the key/ value batch for the map.

  • Format:

Sets(data map[interface{}]interface{})
  • Example:
func ExampleAnyAnyMap_Sets() {
m := gmap.New()

addMap := make(map[interface{}]interface{})
addMap["key1"] = "val1"
addMap["key2"] = "val2"
addMap["key3"] = "val3"

m.Sets(addMap)
fmt.Println(m)

// Output:
// {"key1":"val1","key2":"val2","key3":"val3"}
}
  • Description: Search searches the map using the parameter key. If the key is found, it returns its corresponding value and the parameter found as true, otherwise as false.

  • Format:

Search(key interface{}) (value interface{}, found bool)
  • Example:
func ExampleAnyAnyMap_Search() {
m := gmap.New()

m.Set("key1", "val1")

value, found := m.Search("key1")
if found {
fmt.Println("find key1 value:", value)
}

value, found = m.Search("key2")
if !found {
fmt.Println("key2 not find")
}

// Output:
// find key1 value: val1
// key2 not find
}


Get

  • Description: Get returns the value corresponding to the parameter key. If the key does not exist, it returns Nil.

  • Format:

Get(key interface{}) (value interface{})
  • Example:
func ExampleAnyAnyMap_Get() {
m := gmap.New()

m.Set("key1", "val1")

fmt.Println("key1 value:", m.Get("key1"))
fmt.Println("key2 value:", m.Get("key2"))

// Output:
// key1 value: val1
// key2 value: <nil>
}

Pop

  • Description: Pop randomly retrieves and returns a key-value pair from map and deletes the key-value pair internally.

  • Format:

Pop() (key, value interface{})
  • Example:
func ExampleAnyAnyMap_Pop() {
var m gmap.Map
m.Sets(g.MapAnyAny{
"k1": "v1",
"k2": "v2",
"k3": "v3",
"k4": "v4",
})

fmt.Println(m.Pop())

// May Output:
// k1 v1
}

Pops

  • Description: Pops randomly retrieves and deletes size number of key-value pairs from map. If size == -1, it deletes and returns all key-value pairs.

  • Format:

Pops(size int) map[interface{}]interface{}
  • Example:
func ExampleAnyAnyMap_Pops() {
var m gmap.Map
m.Sets(g.MapAnyAny{
"k1": "v1",
"k2": "v2",
"k3": "v3",
"k4": "v4",
})
fmt.Println(m.Pops(-1))
fmt.Println("size:", m.Size())

m.Sets(g.MapAnyAny{
"k1": "v1",
"k2": "v2",
"k3": "v3",
"k4": "v4",
})
fmt.Println(m.Pops(2))
fmt.Println("size:", m.Size())

// May Output:
// map[k1:v1 k2:v2 k3:v3 k4:v4]
// size: 0
// map[k1:v1 k2:v2]
// size: 2
}

GetOrSet

  • Description: GetOrSet returns value if key exists. If key does not exist, it sets the key-value to the map and then returns the value.

  • Format:

GetOrSet(key interface{}, value interface{}) interface{}
  • Example:
func ExampleAnyAnyMap_GetOrSet() {
m := gmap.New()
m.Set("key1", "val1")

fmt.Println(m.GetOrSet("key1", "NotExistValue"))
fmt.Println(m.GetOrSet("key2", "val2"))

// Output:
// val1
// val2
}

GetOrSetFunc

  • Description: GetOrSetFunc returns value if key exists. If key does not exist, it sets the key-value for map using the return value of func f and then returns the value.

  • Format:

GetOrSetFunc(key interface{}, f func() interface{}) interface{}
  • Example:
func ExampleAnyAnyMap_GetOrSetFunc() {
m := gmap.New()
m.Set("key1", "val1")

fmt.Println(m.GetOrSetFunc("key1", func() interface{} {
return "NotExistValue"
}))
fmt.Println(m.GetOrSetFunc("key2", func() interface{} {
return "NotExistValue"
}))

// Output:
// val1
// NotExistValue
}

GetOrSetFuncLock

  • Description: GetOrSetFunc returns value if key exists. If key does not exist, it sets the key-value for map using the return value of func f and then returns the value.

  • Note: The difference between GetOrSetFuncLock and GetOrSetFunc is that it executes the function f in a write lock.

  • Format:

GetOrSetFuncLock(key interface{}, f func() interface{}) interface{}
  • Example:
func ExampleAnyAnyMap_GetOrSetFuncLock() {
m := gmap.New()
m.Set("key1", "val1")

fmt.Println(m.GetOrSetFuncLock("key1", func() interface{} {
return "NotExistValue"
}))
fmt.Println(m.GetOrSetFuncLock("key2", func() interface{} {
return "NotExistValue"
}))

// Output:
// val1
// NotExistValue
}

GetVar

  • Description: GetVar queries and returns the key-value corresponding to the key name key, with the key value returned using the generic type *gvar.Var.

  • Format:

GetVar(key interface{}) *gvar.Var
  • Example:
func ExampleAnyAnyMap_GetVar() {
m := gmap.New()
m.Set("key1", "val1")

fmt.Println(m.GetVar("key1"))
fmt.Println(m.GetVar("key2").IsNil())

// Output:
// val1
// true
}

GetVarOrSet

  • Description: GetVarOrSet queries and returns the key-value corresponding to the key name key. If the corresponding key-value does not exist, it uses value to set that key-value and returns the queried/settled key-value. The key-value is returned using the generic type *gvar.Var.

  • Format:

GetVarOrSet(key interface{}, value interface{}) *gvar.Var
  • Example:
func ExampleAnyAnyMap_GetVarOrSet() {
m := gmap.New()
m.Set("key1", "val1")

fmt.Println(m.GetVarOrSet("key1", "NotExistValue"))
fmt.Println(m.GetVarOrSet("key2", "val2"))

// Output:
// val1
// val2
}

GetVarOrSetFunc

  • Description: GetVarOrSetFunc queries and returns the key-value corresponding to the key name key. If the corresponding key-value does not exist, it uses the return value of func f to set that key-value and returns the queried/settled key-value. The key-value is returned using the generic type *gvar.Var.

  • Format:

GetVarOrSetFunc(key interface{}, f func() interface{}) *gvar.Var
  • Example:
func ExampleAnyAnyMap_GetVarOrSetFunc() {
m := gmap.New()
m.Set("key1", "val1")

fmt.Println(m.GetVarOrSetFunc("key1", func() interface{} {
return "NotExistValue"
}))
fmt.Println(m.GetVarOrSetFunc("key2", func() interface{} {
return "NotExistValue"
}))

// Output:
// val1
// NotExistValue
}

GetVarOrSetFuncLock

  • Description: GetVarOrSetFuncLock queries and returns the key-value corresponding to the key name key. If the corresponding key-value does not exist, it uses the return value of func f to set that key-value and returns the queried/settled key-value. The key-value is returned using the generic type *gvar.Var.

  • Note: The difference between GetVarOrSetFuncLock and GetVarOrSetFunc is that it executes the function f in a write lock before execution when multiple goroutines call this method simultaneously.

  • Format:

GetVarOrSetFuncLock(key interface{}, f func() interface{}) *gvar.Var
  • Example:
func ExampleAnyAnyMap_GetVarOrSetFuncLock() {
m := gmap.New()
m.Set("key1", "val1")

fmt.Println(m.GetVarOrSetFuncLock("key1", func() interface{} {
return "NotExistValue"
}))
fmt.Println(m.GetVarOrSetFuncLock("key2", func() interface{} {
return "NotExistValue"
}))

// Output:
// val1
// NotExistValue
}

SetIfNotExist

  • Description: If the key does not exist, SetIfNotExist sets the key-value pair key/value for the map and returns true. If the key exists, it returns false, and the value will be ignored.

  • Format:

SetIfNotExist(key interface{}, value interface{}) bool
  • Example:
func ExampleAnyAnyMap_SetIfNotExist() {
var m gmap.Map
fmt.Println(m.SetIfNotExist("k1", "v1"))
fmt.Println(m.SetIfNotExist("k1", "v1"))
fmt.Println(m.Map())

// Output:
// true
// false
// map[k1:v1]
}

SetIfNotExistFunc

  • Description: If the key does not exist, SetIfNotExistFunc sets the value for the map to the return value of the function f and returns true. If the key exists, it returns false, and the value will be ignored.

  • Format:

SetIfNotExistFunc(key interface{}, f func() interface{}) bool
  • Example:
func ExampleAnyAnyMap_SetIfNotExistFunc() {
var m gmap.Map
fmt.Println(m.SetIfNotExistFunc("k1", func() interface{} {
return "v1"
}))
fmt.Println(m.SetIfNotExistFunc("k1", func() interface{} {
return "v1"
}))
fmt.Println(m.Map())

// Output:
// true
// false
// map[k1:v1]
}

SetIfNotExistFuncLock

  • Description: If the key does not exist, SetIfNotExistFunc sets the value for the map to the return value of func f and then returns true. If the key exists, it returns false, and the value will be ignored.

  • Note: The difference between SetIfNotExistFuncLock and SetIfNotExistFunc is that it executes the function f in mutex.Lock.

  • Format:

SetIfNotExistFuncLock(key interface{}, f func() interface{}) bool
  • Example:
func ExampleAnyAnyMap_SetIfNotExistFuncLock() {
var m gmap.Map
fmt.Println(m.SetIfNotExistFuncLock("k1", func() interface{} {
return "v1"
}))
fmt.Println(m.SetIfNotExistFuncLock("k1", func() interface{} {
return "v1"
}))
fmt.Println(m.Map())

// Output:
// true
// false
// map[k1:v1]
}

Remove

  • Description: Delete value from the map by the given key, and return the deleted value.

  • Format:

Remove(key interface{}) (value interface{})
  • Example:
func ExampleAnyAnyMap_Remove() {
var m gmap.Map
m.Set("k1", "v1")

fmt.Println(m.Remove("k1"))
fmt.Println(m.Remove("k2"))

// Output:
// v1
// <nil>
}

Removes

  • Description: Removes batch deletes the value of the map by the given key.

  • Format:

Removes(keys []interface{})
  • Example:
func ExampleAnyAnyMap_Removes() {
var m gmap.Map
m.Sets(g.MapAnyAny{
"k1": "v1",
"k2": "v2",
"k3": "v3",
"k4": "v4",
})

removeList := make([]interface{}, 2)
removeList = append(removeList, "k1")
removeList = append(removeList, "k2")

m.Removes(removeList)

fmt.Println(m.Map())

// Output:
// map[k3:v3 k4:v4]
}

Keys

  • Description: Keys returns all the key of the map as slice.

  • Format:

Keys() []interface{}
  • Example:
func ExampleAnyAnyMap_Keys() {
var m gmap.Map
m.Sets(g.MapAnyAny{
"k1": "v1",
"k2": "v2",
"k3": "v3",
"k4": "v4",
})
fmt.Println(m.Keys())

// Output:
// [k1 k2 k3 k4]
}

Values

  • Description: Values returns all the value of the map as slice.

  • Format:

Values() []interface{}
  • Example:
func ExampleAnyAnyMap_Values() {
var m gmap.Map
m.Sets(g.MapAnyAny{
"k1": "v1",
"k2": "v2",
"k3": "v3",
"k4": "v4",
})
fmt.Println(m.Values())

// May Output:
// [v1 v2 v3 v4]
}

Contains

  • Description: Contains checks whether key exists. If key exists, it returns true, otherwise it returns false.

  • Note: The key name type is interface{}, so the match judgment needs to ensure that the type and value are identical.

  • Format:

Contains(key interface{}) bool
  • Example:
func ExampleAnyAnyMap_Contains() {
var m gmap.Map
m.Sets(g.MapAnyAny{
"k1": "v1",
"k2": "v2",
"k3": "v3",
"k4": "v4",
})
fmt.Println(m.Contains("k1"))
fmt.Println(m.Contains("k5"))

// Output:
// true
// false
}

Size

  • Description: Size returns the size of the map.

  • Format:

Size() int
  • Example:
func ExampleAnyAnyMap_Size() {
var m gmap.Map
m.Sets(g.MapAnyAny{
"k1": "v1",
"k2": "v2",
"k3": "v3",
"k4": "v4",
})

fmt.Println(m.Size())

// Output:
// 4
}

IsEmpty

  • Description: IsEmpty checks whether the map is empty. If the map is empty, it returns true, otherwise it returns false.

  • Format:

IsEmpty() bool
  • Example:
func ExampleAnyAnyMap_IsEmpty() {
var m gmap.Map
fmt.Println(m.IsEmpty())

m.Set("k1", "v1")
fmt.Println(m.IsEmpty())

// Output:
// true
// false
}

Clear

  • Description: Clear deletes all data of the map.

  • Format:

Clear()
  • Example:
func ExampleAnyAnyMap_Clear() {
var m gmap.Map
m.Sets(g.MapAnyAny{
"k1": "v1",
"k2": "v2",
"k3": "v3",
"k4": "v4",
})

m.Clear()

fmt.Println(m.Map())

// Output:
// map[]
}

Replace

  • Description: Replace completely replaces the map's value with the given data.

  • Format:

Replace(data map[interface{}]interface{})
  • Example:
func ExampleAnyAnyMap_Replace() {
var m gmap.Map
m.Sets(g.MapAnyAny{
"k1": "v1",
})

var n gmap.Map
n.Sets(g.MapAnyAny{
"k2": "v2",
})

fmt.Println(m.Map())

m.Replace(n.Map())
fmt.Println(m.Map())

n.Set("k2", "v1")
fmt.Println(m.Map())

// Output:
// map[k1:v1]
// map[k2:v2]
// map[k2:v1]
}

LockFunc

  • Description: LockFunc executes the function f in the write lock.

  • Format:

LockFunc(f func(m map[interface{}]interface{}))
  • Example:
func ExampleAnyAnyMap_LockFunc() {
var m gmap.Map
m.Sets(g.MapAnyAny{
"k1": 1,
"k2": 2,
"k3": 3,
"k4": 4,
})

m.LockFunc(func(m map[interface{}]interface{}) {
totalValue := 0
for _, v := range m {
totalValue += v.(int)
}
fmt.Println("totalValue:", totalValue)
})

// Output:
// totalValue: 10
}

RLockFunc

  • Description: RLockFunc executes the function f in the read lock.

  • Format:

RLockFunc(f func(m map[interface{}]interface{}))
  • Example:
func ExampleAnyAnyMap_RLockFunc() {
var m gmap.Map
m.Sets(g.MapAnyAny{
"k1": 1,
"k2": 2,
"k3": 3,
"k4": 4,
})

m.RLockFunc(func(m map[interface{}]interface{}) {
totalValue := 0
for _, v := range m {
totalValue += v.(int)
}
fmt.Println("totalValue:", totalValue)
})

// Output:
// totalValue: 10
}

Flip

  • Description: Flip exchanges the key and value of the map.

  • Format:

Flip()
  • Example:
func ExampleAnyAnyMap_Flip() {
var m gmap.Map
m.Sets(g.MapAnyAny{
"k1": "v1",
})
m.Flip()
fmt.Println(m.Map())

// Output:
// map[v1:k1]
}

Merge

  • Description: Merge merges two AnyAnyMaps. The input parameter map will be merged into the original map.

  • Format:

Merge(other *AnyAnyMap)
  • Example:
func ExampleAnyAnyMap_Merge() {
var m1, m2 gmap.Map
m1.Set("key1", "val1")
m2.Set("key2", "val2")
m1.Merge(&m2)
fmt.Println(m1.Map())

// May Output:
// map[key1:val1 key2:val2]
}

String

  • Description: String returns the map in string form.

  • Format:

String() string
  • Example:
func ExampleAnyAnyMap_String() {
var m gmap.Map
m.Sets(g.MapAnyAny{
"k1": "v1",
})

fmt.Println(m.String())

// Output:
// {"k1":"v1"}
}

MarshalJSON

  • Description: MarshalJSON implements the json.Marshal interface.

  • Format:

MarshalJSON() ([]byte, error)
  • Example:
func ExampleAnyAnyMap_MarshalJSON() {
var m gmap.Map
m.Sets(g.MapAnyAny{
"k1": "v1",
"k2": "v2",
"k3": "v3",
"k4": "v4",
})

bytes, err := m.MarshalJSON()
if err == nil {
fmt.Println(gconv.String(bytes))
}

// Output:
// {"k1":"v1","k2":"v2","k3":"v3","k4":"v4"}
}

UnmarshalJSON

  • Description: UnmarshalJSON implements the json.Unmarshal interface.

  • Format:

UnmarshalJSON(b []byte) error
  • Example:
func ExampleAnyAnyMap_UnmarshalJSON() {
var m gmap.Map
m.Sets(g.MapAnyAny{
"k1": "v1",
"k2": "v2",
"k3": "v3",
"k4": "v4",
})

var n gmap.Map

err := n.UnmarshalJSON(gconv.Bytes(m.String()))
if err == nil {
fmt.Println(n.Map())
}

// Output:
// map[k1:v1 k2:v2 k3:v3 k4:v4]
}

UnmarshalValue

  • Description: UnmarshalValue is an interface implementation that initializes the current map through a variable of any type.

  • Format:

UnmarshalValue(value interface{}) (err error)
  • Example:
func ExampleAnyAnyMap_UnmarshalValue() {
var m gmap.Map
m.Sets(g.MapAnyAny{
"k1": "v1",
"k2": "v2",
"k3": "v3",
"k4": "v4",
})

var n gmap.Map
err := n.UnmarshalValue(m.String())
if err == nil {
fmt.Println(n.Map())
}
// Output:
// map[k1:v1 k2:v2 k3:v3 k4:v4]
}