Go Maps

External

• Go Specification - Deletion of Map elements https://golang.org/ref/spec#Deletion_of_map_elements

Internal

• Built-in Types
• Arrays
• Slices

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

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 Length

len() returns the number of keys.

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.