Skip to main content

Maps

If you’ve spent any time working with data, you know that keeping things organized is paramount. While arrays and slices are great for ordered lists, what happens when you need to quickly look up a piece of information using a descriptive name or identifier?

Enter the Map (often called a Dictionary or Hash Map in other languages). Maps are fundamental data structures that store data in key-value pairs, providing lightning-fast lookups. They are indispensable for tasks like configuration settings, counting occurrences, or storing user profiles.

This guide will walk you through everything you need to know about working with maps: how to set them up, manipulate their elements, reliably check if an element exists, and iterate through the stored data.

1. Map Initialization: Getting Started​

A map is essentially an unordered collection of unique keys, each associated with a single value. Before you can use a map, you must initialize it.

Defining the Type​

When you define a map, you must specify the data type for both the key and the value. For example, map[string]int means the keys must be strings and the values must be integers.

Method 1: Using the make() function​

The most common way to create an empty map is using the built-in make() function.

// Creates an empty map where keys are strings and values are integers
scores := make(map[string]int)

// Creates an empty map where keys are integers and values are strings
userIDs := make(map[int]string)

Method 2: Using Map Literals (Pre-Populated)​

If you want to initialize the map with data immediately, you can use a literal notation.

// Initializes a map with three key-value pairs
inventory := map[string]int{
    "Apples":  10,
    "Bananas": 5,
    "Oranges": 12,
}

2. Adding and Updating Elements (The CRUD 'C' and 'U')​

Adding a new element or updating an existing one uses the exact same syntax: access the map using the key in square brackets and assign the value.

Adding a New Element​

// We start with our empty scores map
scores := make(map[string]int)

// Add a new element: key "Alice", value 95
scores["Alice"] = 95

// Add another element: key "Bob", value 88
scores["Bob"] = 88

Updating an Existing Element​

If you assign a value to a key that already exists, the old value is overwritten.

// Change Alice's score from 95 to 98
scores["Alice"] = 98 
// scores is now {"Alice": 98, "Bob": 88}

3. Deleting Elements (The CRUD 'D')​

To remove a key-value pair from a map, you use the built-in delete() function.

// Current map: {"Alice": 98, "Bob": 88}

// Delete Bob's score
delete(scores, "Bob")

// Current map: {"Alice": 98}

// Note: Attempting to delete a key that doesn't exist
// does NOT cause an error; the map remains unchanged.
delete(scores, "Charlie")

4. Checking Existence: The Power of the Comma-OK Idiom​

This is arguably the most important concept when working with maps reliably. When you try to access a map element using a key, there are two possible outcomes:

  1. The key exists, and you get its value.
  2. The key does not exist.

The Problem with Simple Access​

If you access a map using a key that doesn't exist (e.g., scores["Charlie"]), the map will return the zero value for the value type (0 for integers, "" for strings, false for booleans, etc.).

If a student named "Frank" truly scored 0, and a student named "George" doesn't exist, simple access returns 0 for both! We can't tell the difference.

The Solution: The Comma-OK Idiom​

To solve this ambiguity, map access allows for a special two-value return. The first return value is the element's value, and the second is a boolean, conventionally named ok, which tells you whether the key was actually present in the map.

// Initializing a map where "Frank" genuinely scored 0
scores := map[string]int{
    "Alice": 98,
    "Frank": 0, 
}

// 1. Check for Frank (key exists)
frankScore, ok := scores["Frank"]

// ok will be true
// frankScore will be 0
if ok {
    fmt.Println("Frank's score is valid:", frankScore)
}

// 2. Check for George (key does not exist)
georgeScore, ok := scores["George"]

// ok will be false
// georgeScore will be 0 (the zero value for int)
if ok {
    // This block will NOT execute
    fmt.Println("George's score is valid:", georgeScore)
} else {
    fmt.Println("George is not recorded in the map.")
}

Key Insight: Always use the comma-ok idiom when reading a map unless you are absolutely certain the key exists. This prevents errors caused by mistakenly treating a zero value return as an existing entry.

5. Iterating Over Maps (Walking the Data)​

You can easily loop through all key-value pairs in a map using the range keyword.

Important Note on Ordering​

Unlike slices, maps are unordered. The order in which elements are returned during iteration is not guaranteed and can change between runs. If you need sorted results, you must extract the keys, sort the keys, and then look up the values individually.

Iterating Over Key and Value​

The range loop returns two values on each iteration: the key and the value.

inventory := map[string]int{
    "Apples":  10,
    "Bananas": 5,
    "Oranges": 12,
}

for fruit, count := range inventory {
    fmt.Printf("There are %d %s left.\n", count, fruit)
}
/* Possible Output (Order not guaranteed):
There are 10 Apples left.
There are 5 Bananas left.
There are 12 Oranges left.
*/

Iterating Over Only Keys or Only Values​

If you only need the key (or only the value), you can discard the unwanted variable using the blank identifier (_).

Iterating Keys Only

for fruitName := range inventory {
    fmt.Println("Inventory item:", fruitName)
}

Iterating Values Only

for _, stockCount := range inventory {
    fmt.Println("Stock count:", stockCount)
}

Summary: Maps Are Your Data Lookup Tool​

Maps are powerful, flexible tools for associating data points and performing high-speed lookups. By mastering initialization, element manipulation, and the crucial comma-ok idiom for existence checks, you are now equipped to handle complex data organization in your applications.