Add with method

Author: dominikzogg

doc/Arr.md

@@ -498,6 +498,22 @@ $spliced = $arr->toSpliced(1, 2, 100);
 
 ---
 
+### `with(int $index, mixed $value): self`
+
+Returns a new array with the element at `index` replaced by `value` (does not modify the original). Supports negative indices.
+
+```php
+$arr = new Arr(1, 2, 3, 4, 5);
+$result = $arr->with(2, 99);
+// $result is [1, 2, 99, 4, 5], $arr is [1, 2, 3, 4, 5]
+
+$arr2 = new Arr(1, 2, 3);
+$result2 = $arr2->with(-1, 'x');
+// $result2 is [1, 2, 'x']
+```
+
+---
+
 ### `toString(): string`
 
 Returns a string representation by joining with `','`.

infection.json

@@ -35,12 +35,13 @@
                 "Chubbyphp\\Typescript\\Arr::reduceRight::601",
                 "Chubbyphp\\Typescript\\Arr::slice::674",
                 "Chubbyphp\\Typescript\\Arr::some::714",
-                "Chubbyphp\\Typescript\\Arr::toSpliced::876"
+                "Chubbyphp\\Typescript\\Arr::toSpliced::876",
+                "Chubbyphp\\Typescript\\Arr::with::907"
             ]
         },
         "GreaterThan": {
             "ignore": [
-                "Chubbyphp\\Typescript\\Arr::mixedToString::994",
+                "Chubbyphp\\Typescript\\Arr::mixedToString::1021",
                 "Chubbyphp\\Typescript\\Arr::slice::681",
                 "Chubbyphp\\Typescript\\Arr::slice::685",
                 "Chubbyphp\\Typescript\\Arr::splice::755",
@@ -64,13 +65,16 @@
                 "Chubbyphp\\Typescript\\Arr::map::495",
                 "Chubbyphp\\Typescript\\Arr::reduce::558",
                 "Chubbyphp\\Typescript\\Arr::reduce::573",
-                "Chubbyphp\\Typescript\\Arr::some::714"
+                "Chubbyphp\\Typescript\\Arr::some::714",
+                "Chubbyphp\\Typescript\\Arr::with::896",
+                "Chubbyphp\\Typescript\\Arr::with::900",
+                "Chubbyphp\\Typescript\\Arr::with::907"
             ]
         },
         "LogicalAndSingleSubExprNegation": {
             "ignore": [
-                "Chubbyphp\\Typescript\\Arr::strictlyEqual::1024",
-                "Chubbyphp\\Typescript\\Arr::strictlyEqual::1028"
+                "Chubbyphp\\Typescript\\Arr::strictlyEqual::1051",
+                "Chubbyphp\\Typescript\\Arr::strictlyEqual::1055"
             ]
         },
         "Minus": {
@@ -87,13 +91,13 @@
         "ReturnRemoval": {
             "ignore": [
                 "Chubbyphp\\Typescript\\Arr::lastIndexOf::464",
-                "Chubbyphp\\Typescript\\Arr::offsetSet::968",
-                "Chubbyphp\\Typescript\\Arr::offsetSet::972",
-                "Chubbyphp\\Typescript\\Arr::strictlyEqual::1025",
-                "Chubbyphp\\Typescript\\Arr::strictlyEqual::1029",
-                "Chubbyphp\\Typescript\\Arr::strictlyEqual::1032",
-                "Chubbyphp\\Typescript\\Arr::strictlyEqual::1035"
+                "Chubbyphp\\Typescript\\Arr::offsetSet::995",
+                "Chubbyphp\\Typescript\\Arr::offsetSet::999",
+                "Chubbyphp\\Typescript\\Arr::strictlyEqual::1052",
+                "Chubbyphp\\Typescript\\Arr::strictlyEqual::1056",
+                "Chubbyphp\\Typescript\\Arr::strictlyEqual::1059",
+                "Chubbyphp\\Typescript\\Arr::strictlyEqual::1062"
             ]
         }
     }
-}
+}

src/Arr.php

@@ -884,6 +884,33 @@ public function toSpliced(int $start, ?int $deleteCount = null, mixed ...$items)
         return $result;
     }
 
+    /**
+     * @param T $value
+     *
+     * @return self<T>
+     */
+    public function with(int $index, mixed $value): self
+    {
+        $len = $this->internalLength;
+
+        if ($index < 0) {
+            $index = $len + $index;
+        }
+
+        if ($index < 0 || $index >= $len) {
+            throw new RangeError('Invalid index: '.$index);
+        }
+
+        /** @var self<T> $result */
+        $result = new self($this->internalLength);
+
+        for ($i = 0; $i < $len; ++$i) {
+            $result->internalArray[$i] = ($i === $index) ? $value : ($this->internalArray[$i] ?? null);
+        }
+
+        return $result;
+    }
+
     public function toString(): string
     {
         return $this->join();

tests/Integration/DocumentationExamplesTest.php

@@ -358,6 +358,20 @@ public function testDocToSplicedExample(): void
         self::assertSame([1, 2, 3, 4], $arr->toArray());
     }
 
+    public function testDocWithExample(): void
+    {
+        $arr = new Arr(1, 2, 3, 4, 5);
+        $result = $arr->with(2, 99);
+
+        self::assertSame([1, 2, 99, 4, 5], $result->toArray());
+        self::assertSame([1, 2, 3, 4, 5], $arr->toArray());
+
+        $arr2 = new Arr(1, 2, 3);
+        $result2 = $arr2->with(-1, 'x');
+
+        self::assertSame([1, 2, 'x'], $result2->toArray());
+    }
+
     public function testDocToStringExample(): void
     {
         $arr = new Arr(1, 2, 3);

tests/Unit/ArrTest.php

@@ -2799,6 +2799,54 @@ public function testToSplicedWithExplicitNullDeleteCountReturnsUnchangedCopy():
         self::assertSame([0, 1, 2, 3], iterator_to_array($array->values()));
     }
 
+    // Array.prototype.with
+
+    public function testWithReplacesElementAtPositiveIndex(): void
+    {
+        self::assertSame([1, 2, 99, 4, 5], iterator_to_array((new Arr(1, 2, 3, 4, 5))->with(2, 99)->values()));
+    }
+
+    public function testWithReplacesElementAtNegativeIndex(): void
+    {
+        self::assertSame([1, 2, 'x'], iterator_to_array((new Arr(1, 2, 3))->with(-1, 'x')->values()));
+    }
+
+    public function testWithDoesNotModifyOriginalArray(): void
+    {
+        $array = new Arr(1, 2, 3);
+        $result = $array->with(1, 99);
+
+        self::assertNotSame($array, $result);
+        self::assertSame([1, 2, 3], iterator_to_array($array->values()));
+        self::assertSame([1, 99, 3], iterator_to_array($result->values()));
+    }
+
+    public function testWithThrowsRangeErrorForOutOfBoundsIndex(): void
+    {
+        $this->expectException(RangeError::class);
+        $this->expectExceptionMessage('Invalid index: 10');
+
+        (new Arr(1, 2, 3))->with(10, 'x');
+    }
+
+    public function testWithThrowsRangeErrorForEmptyArray(): void
+    {
+        $this->expectException(RangeError::class);
+        $this->expectExceptionMessage('Invalid index: 0');
+
+        (new Arr())->with(0, 'x');
+    }
+
+    public function testWithReplacesHoleInSparseArray(): void
+    {
+        $array = new Arr(5);
+        $array[2] = 'present';
+
+        $result = $array->with(3, 'filled');
+
+        self::assertSame('filled', $result->at(3));
+    }
+
     // Array.prototype.toString
 
     public function testToStringReturnsEmptyStringForEmptyArray(): void