HashMap Implementation from Scratch in DSA Python

Mental Model

A HashMap stores key-value pairs by turning keys into indexes to quickly find values.

Analogy: Imagine a library where each book has a unique code. Instead of searching all shelves, you use the code to go directly to the right shelf and find the book fast.

Buckets array: [null, null, null, null, null]
Each bucket can hold a linked list of entries:
Bucket 0 -> null
Bucket 1 -> null
Bucket 2 -> null
Bucket 3 -> null
Bucket 4 -> null

Dry Run Walkthrough

Input: Insert key-value pairs: (1, 'apple'), (6, 'banana'), (11, 'cherry') into a HashMap with 5 buckets

Goal: Store all pairs so that keys with same bucket index are chained, and values can be retrieved quickly

Step 1: Insert (1, 'apple'): compute bucket index 1 % 5 = 1, bucket 1 is empty, add node

Buckets:
[null, (1:'apple') -> null, null, null, null]

Why: We place the first key-value pair in its bucket directly

Step 2: Insert (6, 'banana'): compute bucket index 6 % 5 = 1, bucket 1 has (1:'apple'), add new node at head

Buckets:
[null, (6:'banana') -> (1:'apple') -> null, null, null, null]

Why: Collision occurs, so we chain new node at bucket 1's linked list head

Step 3: Insert (11, 'cherry'): compute bucket index 11 % 5 = 1, bucket 1 has two nodes, add new node at head

Buckets:
[null, (11:'cherry') -> (6:'banana') -> (1:'apple') -> null, null, null, null]

Why: Another collision, so we add new node at head of bucket 1's chain

Step 4: Retrieve value for key 6: compute bucket 1, traverse nodes (11:'cherry'), (6:'banana') found key 6

Buckets unchanged:
[null, (11:'cherry') -> (6:'banana') -> (1:'apple') -> null, null, null, null]

Why: We find the value by checking nodes in the bucket's chain

Result:

Buckets:
[null, (11:'cherry') -> (6:'banana') -> (1:'apple') -> null, null, null, null]
Value for key 6: 'banana'

Annotated Code

DSA Python

class Node:
    def __init__(self, key, value):
        self.key = key
        self.value = value
        self.next = None

class HashMap:
    def __init__(self, size=5):
        self.size = size
        self.buckets = [None] * size

    def _hash(self, key):
        return key % self.size

    def put(self, key, value):
        index = self._hash(key)  # find bucket index
        head = self.buckets[index]

        # Check if key exists, update value
        curr = head
        while curr:
            if curr.key == key:
                curr.value = value  # update existing key
                return
            curr = curr.next

        # Insert new node at head
        new_node = Node(key, value)
        new_node.next = head
        self.buckets[index] = new_node

    def get(self, key):
        index = self._hash(key)  # find bucket index
        curr = self.buckets[index]
        while curr:
            if curr.key == key:
                return curr.value  # found value
            curr = curr.next
        return None  # key not found

    def __str__(self):
        result = []
        for i, node in enumerate(self.buckets):
            chain = []
            curr = node
            while curr:
                chain.append(f"({curr.key}: '{curr.value}')")
                curr = curr.next
            chain_str = " -> ".join(chain) + " -> null" if chain else "null"
            result.append(f"Bucket {i}: {chain_str}")
        return "\n".join(result)

# Driver code
hash_map = HashMap()
hash_map.put(1, 'apple')
hash_map.put(6, 'banana')
hash_map.put(11, 'cherry')
print(hash_map)
print("Value for key 6:", hash_map.get(6))

index = self._hash(key) # find bucket index

compute bucket index from key

while curr: if curr.key == key: curr.value = value return

search bucket chain to update existing key's value

new_node.next = head self.buckets[index] = new_node

insert new node at head of bucket chain

while curr: if curr.key == key: return curr.value

search bucket chain to find value for key

Output

Bucket 0: null

Bucket 1: (11: 'cherry') -> (6: 'banana') -> (1: 'apple') -> null

Bucket 2: null

Bucket 3: null

Bucket 4: null

Value for key 6: banana

Complexity Analysis

Time: O(n/k) average, where n is number of keys and k is bucket count, because each bucket chain is short on average

Space: O(n) because we store all key-value pairs in nodes

vs Alternative: Compared to a simple list which is O(n) for search, this reduces average search to O(1) by using hashing and chaining

Edge Cases

Insert duplicate key with new value

Value is updated in existing node instead of adding new node

DSA Python

if curr.key == key:
    curr.value = value  # update existing key
    return

Get value for key not present

Returns None indicating key not found

DSA Python

return None  # key not found

Empty HashMap get operation

Returns None since no keys exist

DSA Python

return None  # key not found

When to Use This Pattern

When you need fast key-value storage with quick insert and lookup, and keys can collide, use a HashMap with chaining to handle collisions efficiently.

Common Mistakes

Mistake: Not handling collisions, overwriting existing nodes in bucket
Fix: Use linked list chaining to store multiple nodes in the same bucket

Mistake: Not updating value when inserting duplicate key
Fix: Check for existing key in bucket chain and update its value instead of adding new node

Summary

Stores key-value pairs using hashing and linked list chaining to handle collisions.

Use when you want fast average-time insert and lookup by key.

The key insight is to convert keys to bucket indexes and chain collided entries in linked lists.