feature: add OrderedListInterface#prepend

This provides the ability of adding a value in front of the ordered list

Signed-off-by: Maximilian Bösing <2189546+boesing@users.noreply.github.com>

src/OrderedList.php

@@ -17,6 +17,7 @@
 use function array_slice;
 use function array_udiff;
 use function array_uintersect;
+use function array_unshift;
 use function array_values;
 use function assert;
 use function hash;
@@ -396,4 +397,12 @@ public function join(string $separator = ''): string
             throw new RuntimeException('Could not join ordered list.', 0, $throwable);
         }
     }
+
+    public function prepend($value): OrderedListInterface
+    {
+        $instance = clone $this;
+        array_unshift($instance->data, $value);
+
+        return $instance;
+    }
 }

src/OrderedListInterface.php

@@ -155,4 +155,12 @@ public function toNativeArray(): array;
      * @psalm-return list<TValue>
      */
     public function jsonSerialize(): array;
+
+    /**
+     * Adds an item at the beginning of the list.
+     *
+     * @param TValue $value
+     * @return OrderedListInterface<TValue>
+     */
+    public function prepend($value): self;
 }

tests/GenericOrderedListTest.php

@@ -1422,4 +1422,16 @@ public function testWillJoinValuesWithSeperator(): void
 
         self::assertSame('foo:bar:baz', $list->join(':'));
     }
+
+    public function testWillPrependValueToTheList(): void
+    {
+        /** @var OrderedListInterface<non-empty-string> $list */
+        $list = new GenericOrderedList([
+            'bar',
+            'baz',
+        ]);
+
+        $list = $list->prepend('foo');
+        self::assertSame(['foo', 'bar', 'baz'], $list->toNativeArray());
+    }
 }