Add ArrayHelper (#9)

Author: yoanm

Makefile

@@ -78,7 +78,8 @@ test: test-unit test-functional codestyle phpstan
 
 .PHONY: coverage
 coverage:
-	COVERAGE_OUTPUT_STYLE=html make test
+	COVERAGE_OUTPUT_STYLE=html make test-unit
+	COVERAGE_OUTPUT_STYLE=html make test-functional
 
 .PHONY: test-unit
 ifdef PHPUNIT_COVERAGE_OPTION

src/DataStructure/Naming-conventions-and-Mapping.MD

@@ -0,0 +1,101 @@
+# Naming conventions & mapping
+
+## SplHeap 
+SplMinHeap / SplMaxHeap
+
+Construct ➙ 𝑂⟮𝑛⟯
+
+#### Add an element
+`add()`➙`insert()`
+
+TC: 𝑂⟮㏒ 𝑛⟯<br>
+SC: 𝑂⟮𝟷⟯
+
+#### Pop an element
+`pop()`➙`extract()`
+
+TC: 𝑂⟮㏒ 𝑛⟯<br>
+SC: 𝑂⟮𝟷⟯
+
+#### Peek element
+`peek()`➙`top()`
+
+TC: 𝑂⟮𝟷⟯<br>
+SC: 𝑂⟮𝟷⟯
+
+#### DS size
+`size()`➙`count()`
+
+TC: 𝑂⟮𝟷⟯<br>
+SC: 𝑂⟮𝟷⟯
+
+
+## SplPriorityQueue
+ℹ️ Implemented using a `SplMaxHeap`
+
+#### Add an element
+`add()`➙`insert()`
+
+TC: 𝑂⟮㏒ 𝑛⟯<br>
+SC: 𝑂⟮𝟷⟯
+
+#### Pop an element
+`pop()`➙`extract()`
+
+TC: 𝑂⟮㏒ 𝑛⟯<br>
+SC: 𝑂⟮𝟷⟯
+
+#### Peek element
+`peek()`➙`top()`
+
+TC: 𝑂⟮𝟷⟯<br>
+SC: 𝑂⟮𝟷⟯
+
+#### DS size
+`size()`➙`count()`
+
+TC: 𝑂⟮𝟷⟯<br>
+SC: 𝑂⟮𝟷⟯
+
+
+## SplQueue
+ℹ️ Implemented using a `SplDoublyLinkedList`
+
+#### Enqueue an element
+`enqueue()`
+
+#### Dequeue an element
+`dequeue()`
+
+#### Peek element
+`peek()`➙`bottom()`
+
+#### DS size
+`size()`➙`count()`
+
+#### Front / Rear
+⚠️ Not actually available on "real" queue !
+
+`front()`➙`bottom()` — `peek()`<br>
+`rear()`➙`top()`
+
+## SplStack
+ℹ️ Implemented using a `SplDoublyLinkedList`
+
+#### push an element
+`push()`
+
+#### pop an element
+`pop()`
+
+#### Peek element
+`peek()`➙`top()`
+
+#### DS size
+`size()`➙`count()`
+
+#### Front / Rear
+⚠️ Not actually available on "real" stack !
+
+`front()`➙`top()` — `peek()`<br>
+`rear()`➙`bottom()`

src/Helper/ArrayHelper.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace Yoanm\CommonDSA\Helper;
+
+use ArrayAccess;
+use Countable;
+
+class ArrayHelper
+{
+    /**
+     * Insert the value at the given index and push back values from $index to tail index
+     *
+     *
+     * ### Time/Space complexity
+     * With:
+     * - 𝑛 equals the provided list length.
+     * - 𝑥 equals to the number of values to push back (𝑥 = ⟮𝑛 − 𝟷 − $index⟯).
+     *
+     * TC: 𝑂⟮𝑥⟯ - Algo will iterate over each and every value to push back
+     *
+     * SC: 𝑂⟮𝟷⟯ - Constant extra space
+     *
+     * @param array<mixed> $list ⚠ Must be a 0 indexed list, 0 to n consecutive indexes !
+     * @phpstan-param list<mixed> $list
+     * @param int $index ⚠ Expected to be between 0 and 𝑛 !
+     * @param mixed $value
+     */
+    public static function insertAt(array &$list, int $index, mixed $value): void
+    {
+        $tailIdx = count($list) - 1;
+
+        // 1. Move values until the end of original list
+        $prevValue = $value;
+        while ($index <= $tailIdx) {
+            // Backup original value at $index + replace original value by the previous value
+            [$prevValue, $list[$index]] = [$list[$index], $prevValue]; // @phpstan-ignore parameterByRef.type
+            ++$index;
+        }
+
+        // 2. Append the original tail value at the end of the list (=new index !)
+        $list[$index] = $prevValue; // @phpstan-ignore parameterByRef.type
+    }
+}

tests/Technical/Helper/ArrayHelperTest.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Technical\Helper;
+
+use PHPUnit\Framework\TestCase;
+use Yoanm\CommonDSA\Helper\ArrayHelper as Helper;
+
+/**
+ * @covers \Yoanm\CommonDSA\Helper\ArrayHelper
+ */
+final class ArrayHelperTest extends TestCase
+{
+    /**
+     * @dataProvider provideFromLevelOrderListTestCases
+     */
+    public function testInsertAt(array $list, int $index, mixed $value, array $expected): void
+    {
+        Helper::insertAt($list, $index, $value);
+
+        self::assertSame($expected, $list);
+    }
+
+    public function provideFromLevelOrderListTestCases(): array
+    {
+        return [
+            'Insert in the middle of the list' => [
+                'list' => [1,2,3,4,5,7,8,9],
+                'index' => 5,
+                'value' => 6,
+                'expected' => [1,2,3,4,5,6,7,8,9],
+            ],
+            'Replace head value' => [
+                'list' => [2,3,4,5,6,7,8,9],
+                'index' => 0,
+                'value' => 1,
+                'expected' => [1,2,3,4,5,6,7,8,9],
+            ],
+            'Replace tail value' => [
+                'list' => [1,2,3,4,5,6,7,9],
+                'index' => 7,
+                'value' => 8,
+                'expected' => [1,2,3,4,5,6,7,8,9],
+            ],
+            'As new tail value' => [
+                'list' => [1,2,3,4,5,6,7,8],
+                'index' => 8,
+                'value' => 9,
+                'expected' => [1,2,3,4,5,6,7,8,9],
+            ],
+            'Empty list' => [
+                'list' => [],
+                'index' => 0,
+                'value' => 1,
+                'expected' => [1],
+            ],
+        ];
+    }
+}