Change Collection::slice() method to return an instance of Collection

instead of an array.

Author: jwage

UPGRADE.md

@@ -84,3 +84,7 @@ You can find a list of major changes to public API below.
 |             before           |                   after                  |
 |-----------------------------:|:-----------------------------------------|
 | matching(Criteria $criteria) | matching(Criteria $criteria): Collection |
+
+#### Doctrine\Common\Collections\Collection::slice()
+
+The `Collection::slice()` method returns a new `Collection` instance now instead of an array.

docs/en/index.rst

@@ -296,12 +296,16 @@ Sets an element in the collection at the specified key/index.
 slice
 -----
 
-Extracts a slice of $length elements starting at position $offset from the Collection. If $length is null it returns all elements from $offset to the end of the Collection. Keys have to be preserved by this method. Calling this method will only return the selected slice and NOT change the elements contained in the collection slice is called on.
+Extracts a slice of ``$length`` elements starting at position $offset from
+the Collection. If ``$length`` is null it returns all elements from $offset
+to the end of the Collection. Keys have to be preserved by this method.
+Calling this method will only return the selected slice and NOT change
+the elements contained in the collection slice is called on.
 
 .. code-block:: php
     $collection = new ArrayCollection([0, 1, 2, 3, 4, 5]);
 
-    $slice = $collection->slice(1, 2); // [1, 2]
+    $slice = $collection->slice(1, 2); // new ArrayCollection([1, 2])
 
 toArray
 -------

lib/Doctrine/Common/Collections/AbstractLazyCollection.php

@@ -254,7 +254,7 @@ public function indexOf($element): string|int|false
     /**
      * {@inheritDoc}
      */
-    public function slice(int $offset, ?int $length = null): array
+    public function slice(int $offset, ?int $length = null): Collection
     {
         $this->initialize();
 

lib/Doctrine/Common/Collections/ArrayCollection.php

@@ -381,9 +381,9 @@ public function clear(): void
     /**
      * {@inheritDoc}
      */
-    public function slice(int $offset, ?int $length = null): array
+    public function slice(int $offset, ?int $length = null) : Collection
     {
-        return array_slice($this->elements, $offset, $length, true);
+        return $this->createFrom(array_slice($this->elements, $offset, $length, true));
     }
 
     /**

lib/Doctrine/Common/Collections/Collection.php

@@ -290,5 +290,5 @@ public function indexOf(mixed $element): int|string|false;
      * @return mixed[]
      * @psalm-return array<TKey,T>
      */
-    public function slice(int $offset, ?int $length = null): array;
+    public function slice(int $offset, ?int $length = null): self;
 }

tests/Doctrine/Tests/Common/Collections/BaseCollectionTest.php

@@ -219,14 +219,14 @@ public function testSlice(): void
         $this->collection[] = 'two';
         $this->collection[] = 'three';
 
-        $slice = $this->collection->slice(0, 1);
+        $slice = $this->collection->slice(0, 1)->toArray();
         self::assertIsArray($slice);
         self::assertEquals(['one'], $slice);
 
-        $slice = $this->collection->slice(1);
+        $slice = $this->collection->slice(1)->toArray();
         self::assertEquals([1 => 'two', 2 => 'three'], $slice);
 
-        $slice = $this->collection->slice(1, 1);
+        $slice = $this->collection->slice(1, 1)->toArray();
         self::assertEquals([1 => 'two'], $slice);
     }