Refactor and enhance data structures

- ArrayDeque:
  - Implemented addLast and removeFirst methods.
  - Added extensive tests for addFirst, removeLast, peekLast, and more.

- ArrayQueue:
  - Added add method to comply with Queue interface.
  - Created thorough tests for enqueue, dequeue, peek, and related operations.

- TreeSet:
  - Implemented find method.
  - Added union, intersection, and difference methods.
  - Developed comprehensive tests for all methods, including find.

- HashMap:
  - Introduced getIterator method for iterable support.
  - Ensured full test coverage, including iteration over key-value pairs.

Overall, enhanced functionality, ensured robustness, and improved test coverage for key data structures.

Author: walmir-silva

composer.lock

@@ -49,25 +49,27 @@ public function remove(mixed $element): bool
 
     public function contains(mixed $element): bool
     {
-        return in_array($element, $this->elements, true);
+        return null !== $this->find($element);
     }
 
-    public function clear(): void
+    public function find(mixed $element): ?int
     {
-        $this->elements = [];
-    }
+        $index = array_search($element, $this->elements, true);
 
-    public function isEmpty(): bool
-    {
-        return empty($this->elements);
+        return false !== $index ? $index : null;
     }
 
     public function getItems(): array
     {
         return $this->elements;
     }
 
-    public function count(): int
+    public function clear(): void
+    {
+        $this->elements = [];
+    }
+
+    public function size(): int
     {
         return count($this->elements);
     }

src/Collection/ArrayList.php

@@ -71,16 +71,21 @@ public function remove(mixed $element): bool
     }
 
     public function contains(mixed $element): bool
+    {
+        return null !== $this->find($element);
+    }
+
+    public function find(mixed $element): ?Node
     {
         $current = $this->head;
         while (null !== $current) {
             if ($current->data === $element) {
-                return true;
+                return $current;
             }
             $current = $current->next;
         }
 
-        return false;
+        return null;
     }
 
     public function clear(): void
@@ -107,7 +112,7 @@ public function getItems(): array
         return $items;
     }
 
-    public function count(): int
+    public function size(): int
     {
         return $this->size;
     }

src/Collection/LinkedList.php

@@ -4,6 +4,7 @@
 
 namespace KaririCode\DataStructure\Map;
 
+use KaririCode\Contract\DataStructure\Behavioral\IterableCollection;
 use KaririCode\Contract\DataStructure\Map;
 
 /**
@@ -19,7 +20,7 @@
  *
  * @see       https://kariricode.org/
  */
-class HashMap implements Map
+class HashMap implements Map, IterableCollection, \IteratorAggregate
 {
     private array $map = [];
 
@@ -68,4 +69,9 @@ public function values(): array
     {
         return array_values($this->map);
     }
+
+    public function getIterator(): \Iterator
+    {
+        return new \ArrayIterator($this->map);
+    }
 }

src/Map/HashMap.php

@@ -4,6 +4,7 @@
 
 namespace KaririCode\DataStructure\Map;
 
+use KaririCode\Contract\DataStructure\Behavioral\IterableCollection;
 use KaririCode\Contract\DataStructure\Map;
 use KaririCode\DataStructure\TreeMapNode;
 
@@ -20,7 +21,7 @@
  *
  * @see       https://kariricode.org/
  */
-class TreeMap implements Map
+class TreeMap implements Map, IterableCollection, \IteratorAggregate
 {
     private ?TreeMapNode $root = null;
     private int $size = 0;
@@ -31,7 +32,7 @@ public function put(mixed $key, mixed $value): void
         if (null === $this->root) {
             $this->root = $newNode;
             $this->root->setBlack();
-            $this->size++;
+            ++$this->size;
         } else {
             $this->insertNode($newNode);
             $this->balanceAfterInsertion($newNode);
@@ -43,14 +44,30 @@ public function get(mixed $key): mixed
         return $this->findNode($key)?->value;
     }
 
+    public function keys(): array
+    {
+        $keys = [];
+        $this->inOrderTraversalKeys($this->root, $keys);
+
+        return $keys;
+    }
+
+    public function values(): array
+    {
+        $values = [];
+        $this->inOrderTraversalValues($this->root, $values);
+
+        return $values;
+    }
+
     public function remove(mixed $key): bool
     {
         $node = $this->findNode($key);
         if (null === $node) {
             return false;
         }
         $this->deleteNode($node);
-        $this->size--;
+        --$this->size;
 
         return true;
     }
@@ -60,6 +77,57 @@ public function size(): int
         return $this->size;
     }
 
+    public function clear(): void
+    {
+        $this->root = null;
+        $this->size = 0;
+    }
+
+    public function containsKey(mixed $key): bool
+    {
+        return null !== $this->findNode($key);
+    }
+
+    public function getItems(): array
+    {
+        $items = [];
+        $this->inOrderTraversal($this->root, $items);
+
+        return $items;
+    }
+
+    public function getIterator(): \Iterator
+    {
+        return new \ArrayIterator($this->getItems());
+    }
+
+    private function inOrderTraversalKeys(?TreeMapNode $node, array &$keys): void
+    {
+        if (null !== $node) {
+            $this->inOrderTraversalKeys($node->left, $keys);
+            $keys[] = $node->key;
+            $this->inOrderTraversalKeys($node->right, $keys);
+        }
+    }
+
+    private function inOrderTraversalValues(?TreeMapNode $node, array &$values): void
+    {
+        if (null !== $node) {
+            $this->inOrderTraversalValues($node->left, $values);
+            $values[] = $node->value;
+            $this->inOrderTraversalValues($node->right, $values);
+        }
+    }
+
+    private function inOrderTraversal(?TreeMapNode $node, array &$items): void
+    {
+        if (null !== $node) {
+            $this->inOrderTraversal($node->left, $items);
+            $items[$node->key] = $node->value;
+            $this->inOrderTraversal($node->right, $items);
+        }
+    }
+
     private function insertNode(TreeMapNode $newNode): void
     {
         $current = $this->root;
@@ -85,7 +153,7 @@ private function insertNode(TreeMapNode $newNode): void
             $parent->right = $newNode;
         }
 
-        $this->size++;
+        ++$this->size;
         $this->balanceAfterInsertion($newNode);
     }
 

src/Map/TreeMap.php

@@ -5,7 +5,6 @@
 namespace KaririCode\DataStructure\Queue;
 
 use KaririCode\Contract\DataStructure\Deque;
-use KaririCode\Contract\DataStructure\Queue;
 
 /**
  * ArrayDeque implementation.
@@ -52,4 +51,9 @@ public function peekLast(): mixed
 
         return $this->elements[$index];
     }
+
+    public function add(mixed $element): void
+    {
+        $this->addLast($element);
+    }
 }

src/Queue/ArrayDeque.php

@@ -21,5 +21,8 @@
  */
 class ArrayQueue extends CircularArrayQueue implements Queue
 {
-    // No additional methods required, uses methods from CircularArrayQueue
+    public function add(mixed $element): void
+    {
+        $this->enqueue($element);
+    }
 }

src/Queue/ArrayQueue.php

@@ -88,6 +88,16 @@ public function enqueue(mixed $element): void
         ++$this->size;
     }
 
+    public function addLast(mixed $element): void
+    {
+        $this->enqueue($element);
+    }
+
+    public function removeFirst(): mixed
+    {
+        return $this->dequeue();
+    }
+
     public function getItems(): array
     {
         $items = [];
@@ -97,4 +107,23 @@ public function getItems(): array
 
         return $items;
     }
+
+    public function remove(mixed $element): bool
+    {
+        for ($i = 0; $i < $this->size; ++$i) {
+            $index = ($this->front + $i) % $this->capacity;
+            if ($this->elements[$index] === $element) {
+                // Shift elements to the left to fill the gap
+                for ($j = $index; $j !== ($this->front + $this->size - 1) % $this->capacity; $j = ($j + 1) % $this->capacity) {
+                    $this->elements[$j] = $this->elements[($j + 1) % $this->capacity];
+                }
+                $this->elements[($this->front + $this->size - 1) % $this->capacity] = null;
+                --$this->size;
+
+                return true;
+            }
+        }
+
+        return false;
+    }
 }