Go Maps
External
Internal
Overview
A map is the Go language implementation of a hash table.
A map variable is a value, not a reference variable, which means that no two different map variables may point to the same map instance.
Declaration
A map is declared with the following notation:
var <map_var_name> map[<key_type>]<value_type>
var m map[string]int
Note that this declaration will create a nil map. See Empty Map and nil Map below.
Literals
m := map[string]int {"Alice": 1, "Bob": 2}
m2 := map[string]int {
"Alice": 1,
"Bob": 2, // comma on the last line required
}
Initialization
A map can be initialized with a map literal, using long variable declaration with type inference or short variable declaration.
Long variable declaration with type inference:
var m = map[string]int {"Alice": 1, "Bob": 2}
Short variable declaration:
m := map[string]int {"Alice": 1, "Bob": 2}
A map can also be initialized with make(), which will yield an empty map:
var m map[string]int
m = make(map[string]int)
Empty Map and nil Map
A simple map variable declaration without initialization will create a nil map.
var m map[string]string // m is a nil map
An attempt to read a key with the [] operator will work with the nil map, in that the operator invocation will succeed and will return false.
_, exists := m["color"]
print(exists) // prints "false"
However, an attempt to write a nil map will panic the program:
m["color"] = "blue"
will result in:
panic: assignment to entry in nil map
To get a writable map, initialize with either the empty map or use make().
var m = map[string]string{}
or
m := make(map[string]string)
Testing for a nil Map
// nil map
var m map[string]struct{}
if m == nil {
// nil map
}
Operators
Indexing Operator []
Values stored in a map can be referenced with the indexing operator [], using the [<key>] syntax. The indexing operator returns two values: the value and a boolean that says whether the key exists or not in the map.
m := map[string]int {"Alice": 1, "Bob": 2}
v, exists := m["Alice"]
fmt.Printf("%d, %t\n", v, exists) // will display 1, true
If the key does not exist in map, the retuned value is not nil, but the zero value for the type.
The values can be changed, or new key/value pairs added with the same operator:
m["Alice"] = 7
println(m["Alice"])
m["Charlie"] = 9
println(m["Charlie"])
Functions
len()
len() is a built-in function that returns the number of keys in the map.
make()
make() is a built-in function that can be used to make new maps. See Initialization above.
delete()
delete() is a built-in function that can be used to delete a key/value pair from the map:
m := map[string]int{"Alice": 1, "Bob": 2}
delete(m, "Alice")
What if the key does not exist?
Iterating over Map Keys and Values
Use the range keyword. range allows to iterate by key and value pairs:
for k, v := range m {
fmt.Printf("key: %s, value: %d\n", k, v)
}
If we only want to iterate over keys and the values are not needed, this syntax is valid:
for k := range m {
fmt.Printf("key: %s\n", k)
}
Key Identity
The identity of a key in the map is given by its value and its type. We can use the same underlying value, but if the type is different, the keys will count as different. Two different aliases of the same type count as two different types.
type A int
type B int
m := map[interface{}]string{}
m[A(1)] = "red"
m[B(1)] = "blue"
fmt.Printf("%v", m)
will display:
map[1:red 1:blue]
This behavior is used to implement a technique that prevents key collisions when context.Context is used to store request-scoped key/value pairs.
TO DEPLETE
Overview
A map is an unordered collection of key-value pairs. The map implementation uses the key as an index, quickly retrieving the associated value.
The map key can be a value from any built-in or struct type as long as the value can be used in an expression with an == operator. Slices, functions and struct types that contain slices can't be used as map keys, an attempt will generate a compiler error.
Lexically, a map type is a reference type. The map instances must be initialized before attempting to use into them, either by using the make() function or a map literal, otherwise you will get a runtime error, because a zero value for a map is nil:
panic: assignment to entry in nil map
Unlike arrays, which are values and problematic to pass as function arguments, maps can be easily be passed as values - their memory footprint is very small. If a map is passed to a function and changed in the function, the changes will be reflected by all references to the map. From this point of view, maps are designed to be cheap, similar to slices.
Implementation Details
In order to store a key/value pair in the map, the map hash function is applied to the key, which produces the index of a bucket. The purpose of the hash function is to generate the index that is evenly distributed across the bucket population. Once a bucket is selected, the map stores the key/value pair in the bucket.
In order to retrieve the value corresponding to a key, the same hash function is applied to select the bucket, and then the map iterates over the keys stored in that bucket.
Declaration
Long Declaration
var map_identifier map[key_type]value_type
Example of a map of string to ints:
var m map[string]int
A map declaration and initialization with a map literal:
var m map[string]string = map[string]string {
"A": "B",
"C": "D",
}
A map declaration and initialization with make():
var m map[string]string = make(map[string]string)
Short Declaration
Short Declaration with Literals
m := map[string]string {
"A": "B",
"C": "D",
}
Using a literal is the idiomatic way to create a map.
Short Declaration with make()
m := make(map[string]string)
More about make() is available here.
nil Maps and Empty Maps
Declaring a map without initializing it creates a nil map - the map variable is initialized with nil. This is common behavior for reference types:
var m map[string]string
For a nil map, fmt.Printf("%p", s) prints 0x0. The underlying data structures are initialized with zero values.
A nil map is different from an empty map:
// empty map
m := map[string]string {}
// empty map m := make(map[string]string)
For an empty map, fmt.Printf("%p", s) prints a pointer: 0x8201d2210.
Regardless of whether a nil or empty map is used, the built-in functions append(), len() and cap() work the same.
Map Operators and Functions
Indexing Operator
Assigning a key/value pair to the map is performed using the indexing [] and the assignment operators =:
m["something"] = "something else"
Indexing operator [] returns the copy of the value corresponding to the specified key and a boolean value that says whether the key exists or not. If the key does not exist, the zero value for the value type is returned. Note that if the map allows zero values, we cannot rely on the returned value alone to decide whether the key/value has been actually stored in the map or not, we need to use the returned "exists" flag.
value := m["key"] // only the first return value can be used, as long as we are prepared to deal with the zero value value, exists := m["key"]
Idiom:
if value, exists := m["key"]; exists {
// it exists ...
}
Map Size
len() returns the number of keys.
Note that the built-in cap() function does not work on maps. Unlike slices, the maps do not have the concept of capacity,
delete()
Removes the element corresponding to the given key from the map:
delete(m, "something")
It is a no-op if the key does not exist.
make()
The make() function creates the map:
m := make(map[key_type]value_type)
Note that make() returns the map instance, not a pointer.