Add HashMap Implementation and Comprehensive Unit Tests

- Implemented the HashMap class in the KaririCode\\DataStructure\\Map namespace.
- Added comprehensive unit tests for the HashMap class in the KaririCode\\DataStructure\\Tests\\Map namespace.

Class:
- KaririCode\\DataStructure\\Map\\HashMap

Tests:
- KaririCode\\DataStructure\\Tests\\Map\\HashMapTest

Implemented Features and Corresponding Tests:
- Put method: testPutAddsKeyValuePairToMap
- Get method: testGetReturnsValueForKey
- Remove method: testRemoveDeletesKeyValuePairFromMap
- Contains key method: testContainsKeyReturnsTrueIfKeyExists
- Clear method: testClearRemovesAllKeyValuePairsFromMap
- Keys method: testKeysReturnsAllKeysInMap
- Values method: testValuesReturnsAllValuesInMap
- Size method: testSizeReturnsNumberOfKeyValuePairsInMap
- Handling null values: testHandlingNullValuesCorrectly
- Put replaces value for existing key: testPutReplacesValueForExistingKey

src/Collection/LinkedList.php

@@ -138,13 +138,13 @@ public function set(int $index, mixed $element): void
     }
 
     /**
-    * Clone method to ensure deep copy of nodes
-    */
+     * Clone method to ensure deep copy of nodes.
+     */
     public function __clone()
     {
         $newList = new LinkedList();
         $current = $this->head;
-        while ($current !== null) {
+        while (null !== $current) {
             $newList->add($current->data);
             $current = $current->next;
         }

src/Map/HashMap.php

@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\DataStructure\Map;
+
+use KaririCode\Contract\DataStructure\Map;
+
+/**
+ * HashMap implementation.
+ *
+ * This class implements a hash map using PHP's built-in array as the underlying storage.
+ * It provides O(1) average time complexity for put, get, and remove operations.
+ *
+ * @category  Maps
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+class HashMap implements Map
+{
+    private array $map = [];
+
+    public function put(mixed $key, mixed $value): void
+    {
+        $this->map[$key] = $value;
+    }
+
+    public function get(mixed $key): mixed
+    {
+        return $this->map[$key] ?? null;
+    }
+
+    public function remove(mixed $key): bool
+    {
+        if (array_key_exists($key, $this->map)) {
+            unset($this->map[$key]);
+
+            return true;
+        }
+
+        return false;
+    }
+
+    public function containsKey(mixed $key): bool
+    {
+        return array_key_exists($key, $this->map);
+    }
+
+    public function size(): int
+    {
+        return count($this->map);
+    }
+
+    public function clear(): void
+    {
+        $this->map = [];
+    }
+
+    public function keys(): array
+    {
+        return array_keys($this->map);
+    }
+
+    public function values(): array
+    {
+        return array_values($this->map);
+    }
+}

tests/Map/HashMapTest.php

@@ -0,0 +1,107 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\DataStructure\Tests\Map;
+
+use KaririCode\DataStructure\Map\HashMap;
+use PHPUnit\Framework\TestCase;
+
+final class HashMapTest extends TestCase
+{
+    // Test adding a key-value pair to the map
+    public function testPutAddsKeyValuePairToMap(): void
+    {
+        $map = new HashMap();
+        $map->put('key1', 'value1');
+        $this->assertSame('value1', $map->get('key1'));
+    }
+
+    // Test retrieving a value by key
+    public function testGetReturnsValueForKey(): void
+    {
+        $map = new HashMap();
+        $map->put('key1', 'value1');
+        $this->assertSame('value1', $map->get('key1'));
+        $this->assertNull($map->get('key2'));
+    }
+
+    // Test removing a key-value pair by key
+    public function testRemoveDeletesKeyValuePairFromMap(): void
+    {
+        $map = new HashMap();
+        $map->put('key1', 'value1');
+        $this->assertTrue($map->remove('key1'));
+        $this->assertFalse($map->remove('key2'));
+        $this->assertNull($map->get('key1'));
+    }
+
+    // Test checking if the map contains a specific key
+    public function testContainsKeyReturnsTrueIfKeyExists(): void
+    {
+        $map = new HashMap();
+        $map->put('key1', 'value1');
+        $this->assertTrue($map->containsKey('key1'));
+        $this->assertFalse($map->containsKey('key2'));
+    }
+
+    // Test clearing all key-value pairs from the map
+    public function testClearRemovesAllKeyValuePairsFromMap(): void
+    {
+        $map = new HashMap();
+        $map->put('key1', 'value1');
+        $map->put('key2', 'value2');
+        $map->clear();
+        $this->assertSame(0, $map->size());
+        $this->assertNull($map->get('key1'));
+        $this->assertNull($map->get('key2'));
+    }
+
+    // Test getting all keys from the map
+    public function testKeysReturnsAllKeysInMap(): void
+    {
+        $map = new HashMap();
+        $map->put('key1', 'value1');
+        $map->put('key2', 'value2');
+        $this->assertSame(['key1', 'key2'], $map->keys());
+    }
+
+    // Test getting all values from the map
+    public function testValuesReturnsAllValuesInMap(): void
+    {
+        $map = new HashMap();
+        $map->put('key1', 'value1');
+        $map->put('key2', 'value2');
+        $this->assertSame(['value1', 'value2'], $map->values());
+    }
+
+    // Test getting the size of the map
+    public function testSizeReturnsNumberOfKeyValuePairsInMap(): void
+    {
+        $map = new HashMap();
+        $this->assertSame(0, $map->size());
+        $map->put('key1', 'value1');
+        $map->put('key2', 'value2');
+        $this->assertSame(2, $map->size());
+    }
+
+    // Test handling null values in the map
+    public function testHandlingNullValuesCorrectly(): void
+    {
+        $map = new HashMap();
+        $map->put('key1', null);
+        $this->assertTrue($map->containsKey('key1'));
+        $this->assertNull($map->get('key1'));
+        $this->assertTrue($map->remove('key1'));
+        $this->assertFalse($map->containsKey('key1'));
+    }
+
+    // Test replacing a value for an existing key
+    public function testPutReplacesValueForExistingKey(): void
+    {
+        $map = new HashMap();
+        $map->put('key1', 'value1');
+        $map->put('key1', 'value2');
+        $this->assertSame('value2', $map->get('key1'));
+    }
+}