Add access with offset and first/last methods

+ Simplify/Correct template declarations
+ Fix method signatures (self → static)

src/Collections/Collection.php

@@ -2,52 +2,55 @@
 
 namespace jrosset\Collections;
 
+use Closure;
+
 /**
  * A collection
  *
- * @psalm-template     TKey of array-key
+ * @template TKey of array-key
- * @template-covariant TValue
+ * @template TValue
- * @template-extends ImmutableCollection<TKey, TValue>
+ *
- * @template-implements ICollection<TKey, TValue>
+ * @implements ImmutableCollection<TKey, TValue>
+ * @implements ICollection<TKey, TValue>
  */
 class Collection extends ImmutableCollection implements ICollection {
     /**
      * @inheritDoc
      */
-    public function set ($key, $value): self {
+    public function set ($key, $value) {
         return $this->_set($key, $value);
     }
     /**
      * @inheritDoc
      */
-    public function merge (IImmutableCollection ...$collections): ICollection {
+    public function merge (IImmutableCollection ...$collections) {
         return $this->_merge(...$collections);
     }
 
     /**
      * @inheritDoc
      */
-    public function add (...$values): self {
+    public function add (...$values) {
         return $this->_add(...$values);
     }
     /**
      * @inheritDoc
      */
-    public function addCollection (IImmutableCollection ...$collections): ICollection {
+    public function addCollection (IImmutableCollection ...$collections) {
         return $this->_addCollection(...$collections);
     }
 
     /**
      * @inheritDoc
      */
-    public function prepend (...$values): ICollection {
+    public function prepend (...$values) {
         array_unshift($this->elements, ...$values);
         return $this;
     }
     /**
      * @inheritDoc
      */
-    public function prependCollection (IImmutableCollection ...$collections): ICollection {
+    public function prependCollection (IImmutableCollection ...$collections) {
         $prepend = array_merge(
             ...array_map(
                    function (IImmutableCollection $collection): array {
@@ -62,21 +65,21 @@ class Collection extends ImmutableCollection implements ICollection {
     /**
      * @inheritDoc
      */
-    public function clear (): self {
+    public function clear () {
         $this->_initialize();
         return $this;
     }
     /**
      * @inheritDoc
      */
-    public function remove ($key): self {
+    public function remove ($key) {
         unset($this->elements[$this->_normalizeKey($key)]);
         return $this;
     }
     /**
      * @inheritDoc
      */
-    public function removeValue ($value, bool $strict = false): self {
+    public function removeValue ($value, bool $strict = false) {
         foreach ($this->elements as $currentKey => $currentValue) {
             if (($strict && $value === $currentValue) || (!$strict && $value == $currentValue)) {
                 unset($this->elements[$currentKey]);
@@ -85,6 +88,27 @@ class Collection extends ImmutableCollection implements ICollection {
         return $this;
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function removeFirst () {
+        $firstKey = $this->firstKey();
+        $firstValue = $this->get($firstKey);
+
+        $this->remove($firstKey);
+        return $firstValue;
+    }
+    /**
+     * @inheritDoc
+     */
+    public function removeLast () {
+        $lastKey = $this->lastKey();
+        $lastValue = $this->get($lastKey);
+
+        $this->remove($lastKey);
+        return $lastValue;
+    }
+
     /**
      * @inheritDoc
      */
@@ -97,4 +121,52 @@ class Collection extends ImmutableCollection implements ICollection {
     public function offsetUnset ($offset): void {
         $this->remove($offset);
     }
+
+    /**
+     * @inheritDoc
+     */
+    public function sliceSelf (int $offset, ?int $length = null) {
+        $this->_checkOffset($offset);
+
+        $this->elements = array_slice($this->elements, $offset, $length, true);
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function filterSelf (Closure $filter) {
+        $this->elements = array_filter($this->elements, $filter);
+        return $this;
+    }
+    /**
+     * @inheritDoc
+     */
+    public function removeEmpties () {
+        return $this->filterSelf(function ($value) {
+            return empty($value);
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    public function mapSelf (Closure $process) {
+        $this->elements = array_map($process, $this->elements);
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function sortSelf ($sorter = null) {
+        uasort($this->elements, self::_normalizeSorter($sorter));
+        return $this;
+    }
+    /**
+     * @inheritDoc
+     */
+    public function sortSelfByKey ($sorter) {
+        uksort($this->elements, self::_normalizeSorter($sorter));
+        return $this;
+    }
 }

src/Collections/IArrayCast.php

@@ -5,15 +5,14 @@ namespace jrosset\Collections;
 /**
  * Interface for PHP-native array cast
  *
- * @psalm-template     TKey of array-key
+ * @template TKey of array-key
- * @template-covariant TValue
+ * @template TValue
  */
 interface IArrayCast {
     /**
      * Transform to a PHP-native array
      *
-     * @return array The native array
+     * @return array<TKey, TValue> The native array
-     * @psalm-return array<TKey, TValue>
      */
     public function toArray (): array;
 }

src/Collections/ICollection.php

@@ -2,98 +2,206 @@
 
 namespace jrosset\Collections;
 
+use Closure;
+use Exception;
+use OutOfBoundsException;
+
 /**
  * Interface for a collection
  *
- * @psalm-template     TKey of array-key
+ * @template TKey of array-key
- * @template-covariant TValue
+ * @template TValue
- * @template-extends IImmutableCollection<TKey, TValue>
+ *
+ * @implements IImmutableCollection<TKey, TValue>
  */
 interface ICollection extends IImmutableCollection {
     /**
      * Set a value to a key
      *
-     * @param array-key    $key   The key
+     * @param TKey   $key   The key
-     * @param mixed        $value The value
+     * @param TValue $value The value
-     *
-     * @psalm-param TKey   $key
-     * @psalm-param TValue $value
      *
      * @return $this
+     *
+     * @noinspection PhpMissingReturnTypeInspection
      */
-    public function set ($key, $value): self;
+    public function set ($key, $value);
     /**
-     * Merge one or multiple collections in the current one
+     * Merge one or multiple collections into the current one
      *
-     * @param IImmutableCollection ...$collections The collections to merge
+     * @param IImmutableCollection<TKey, TValue> ...$collections The collections to merge
      *
      * @return $this
+     *
+     * @noinspection PhpMissingReturnTypeInspection
      */
-    public function merge (IImmutableCollection ...$collections): self;
+    public function merge (IImmutableCollection ...$collections);
 
     /**
      * Add one or multiple values
      *
-     * @param mixed        ...$values The values
+     * @param TValue ...$values The values
-     *
-     * @psalm-param TValue ...$values
      *
      * @return $this
+     *
+     * @noinspection PhpMissingReturnTypeInspection
      */
-    public function add (...$values): self;
+    public function add (...$values);
     /**
      * Add the <b>values</b> of one or multiple collections
      *
-     * @param IImmutableCollection ...$collections The collections to add
+     * @param IImmutableCollection<TKey, TValue> ...$collections The collections to add
+     *
+     * @return $this
      *
-     * @return mixed
+     * @noinspection PhpMissingReturnTypeInspection
      */
-    public function addCollection (IImmutableCollection ...$collections): self;
+    public function addCollection (IImmutableCollection ...$collections);
 
     /**
      * Add one or multiple values at the beginning of the current collection
      *
-     * @param mixed        ...$values The values
+     * @param TValue ...$values The values
-     *
-     * @psalm-param TValue ...$values
      *
      * @return $this
+     *
+     * @noinspection PhpMissingReturnTypeInspection
      */
-    public function prepend (...$values): self;
+    public function prepend (...$values);
     /**
      * Add the <b>values</b> of one or multiple collections at the beginning of the current collection
      *
-     * @param IImmutableCollection ...$collections The collections to add
+     * @param IImmutableCollection<TKey, TValue> ...$collections The collections to add
+     *
+     * @return $this
      *
-     * @return mixed
+     * @noinspection PhpMissingReturnTypeInspection
      */
-    public function prependCollection (IImmutableCollection ...$collections): self;
+    public function prependCollection (IImmutableCollection ...$collections);
 
     /**
-     * Empties the collection
+     * Empty the collection
      *
      * @return $this
+     *
+     * @noinspection PhpMissingReturnTypeInspection
      */
-    public function clear (): self;
+    public function clear ();
     /**
-     * Delete a key
+     * Remove a value from it's key
-     *
-     * @param array-key  $key The key
      *
-     * @psalm-param TKey $key
+     * @param TKey $key The key
      *
      * @return $this
+     *
+     * @noinspection PhpMissingReturnTypeInspection
      */
-    public function remove ($key): self;
+    public function remove ($key);
     /**
      * Delete all instances of a value
      *
-     * @param mixed        $value  The value
+     * @param TValue $value  The value
      * @param bool   $strict Strict comparison ?
      *
-     * @psalm-param TValue $value
+     * @return $this
+     *
+     * @noinspection PhpMissingReturnTypeInspection
+     */
+    public function removeValue ($value, bool $strict = false);
+
+    /**
+     * Get and remove the first element
+     *
+     * @return TValue The value
+     *
+     * @throws OutOfBoundsException If the collection is empty
+     */
+    public function removeFirst ();
+    /**
+     * Get and remove the last element
+     *
+     * @return TValue The value
+     *
+     * @throws OutOfBoundsException If the collection is empty
+     */
+    public function removeLast ();
+
+    /**
+     * Keep only a slice of the collection
+     *
+     * Preserves the keys
+     *
+     * @param int      $offset The start offset
+     * @param int|null $length The maximum length. Null if until end of the collection
+     *
+     * @return $this
+     *
+     * @throws OutOfBoundsException If the offset is not valid
+     *
+     * @noinspection PhpMissingReturnTypeInspection
+     */
+    public function sliceSelf (int $offset, ?int $length = null);
+
+    /**
+     * Keep only elements that satisfy predicate $filter
+     *
+     * @param Closure(TKey, TValue):bool $filter The filtering predicate
+     *
+     * @return $this
+     *
+     * @noinspection PhpMissingReturnTypeInspection
+     */
+    public function filterSelf (Closure $filter);
+    /**
+     * Keep only non-empty elements
+     *
+     * Use {@see https://www.php.net/manual/function.empty.php empty} to check if element is empty or not
+     *
+     * @return $this
+     *
+     * @noinspection PhpMissingReturnTypeInspection
+     */
+    public function removeEmpties ();
+    /**
+     * Applied <b>$process</b> on all elements
+     *
+     * @param Closure(TKey, TValue): TValue $process The process function to apply on each element
      *
      * @return $this
+     *
+     * @noinspection PhpMissingReturnTypeInspection
+     */
+    public function mapSelf (Closure $process);
+
+    /**
+     * Sort the elements (by value)
+     *
+     * @param null|IComparator|Closure(TValue, TValue):int $sorter The sorting method ; Null if values are object implementing {@see IComparable}.
+     *                                                             <br>Return :
+     *                                                             <br>&lt; 0 if value1 is before value2
+     *                                                             <br>= 0 if value1 equals value2
+     *                                                             <br>&gt; 0 if value1 is after value2
+     *
+     * @return $this
+     *
+     * @throws Exception If an error occurs
+     *
+     * @noinspection PhpMissingReturnTypeInspection
+     */
+    public function sortSelf ($sorter = null);
+    /**
+     * Sort the elements by key
+     *
+     * @param IComparator|Closure(TKey, TKey):int $sorter The sorting method. Return :
+     *                                                    <br>&lt; 0 if key1 is before key2
+     *                                                    <br>= 0 if key1 equals key2
+     *                                                    <br>&gt; 0 if key1 is after key2
+     *
+     * @return $this
+     *
+     * @throws Exception If an error occurs
+     *
+     * @noinspection PhpMissingReturnTypeInspection
      */
-    public function removeValue ($value, bool $strict = false): self;
+    public function sortSelfByKey ($sorter);
 }

src/Collections/IComparable.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace jrosset\Collections;
+
+/**
+ * Interface for comparable objects
+ *
+ * @template TObject of object
+ */
+interface IComparable {
+    /**
+     * Compare to another instance
+     *
+     * @param TObject $other The other instance
+     *
+     * @return int <br>&lt; 0 if current instance is classed before the other instance
+     *             <br>= 0 if current instance is classed equals the other instance
+     *             <br>&gt; 0 if current instance is classed after the other instance
+     *
+     * @noinspection PhpMissingParamTypeInspection
+     */
+    public function compareTo ($other): int;
+}

src/Collections/IComparator.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace jrosset\Collections;
+
+/**
+ * Interface for classes comparing external objects
+ *
+ * @template TObject of object
+ */
+interface IComparator {
+    /**
+     * Compare two objects
+     *
+     * @param TObject $object1 The first object
+     * @param TObject $object2 The second object
+     *
+     * @return int <br>&lt; 0 if the first object is classed before the second object
+     *             <br>= 0 if the first object is classed equals the second object
+     *             <br>&gt; 0 if the first object is classed after the second object
+     *
+     * @noinspection PhpMissingParamTypeInspection
+     */
+    public function compare ($object1, $object2): int;
+}

src/Collections/IImmutableCollection.php

@@ -7,16 +7,19 @@ use Closure;
 use Countable;
 use IteratorAggregate;
 use JsonSerializable;
+use OutOfBoundsException;
 use Serializable;
+use Throwable;
 
 /**
  * Interface for an immutable (read-only) collection
  *
- * @psalm-template     TKey of array-key
+ * @template TKey of array-key
- * @template-covariant TValue
+ * @template TValue
- * @template-extends IteratorAggregate<TKey, TValue>
+ *
- * @template-extends ArrayAccess<TKey, TValue>
+ * @implements IteratorAggregate<TKey, TValue>
- * @template-extends IArrayCast<TKey, TValue>
+ * @implements ArrayAccess<TKey, TValue>
+ * @implements IArrayCast<TKey, TValue>
  */
 interface IImmutableCollection extends IteratorAggregate, JsonSerializable, Serializable, Countable, ArrayAccess, IArrayCast {
     /**
@@ -29,9 +32,7 @@ interface IImmutableCollection extends IteratorAggregate, JsonSerializable, Seri
     /**
      * Checks if a key exists
      *
-     * @param array-key  $key The key
+     * @param TKey $key The key
-     *
-     * @psalm-param TKey $key
      *
      * @return bool TRUE if the key exists, FALSE otherwise
      */
@@ -39,11 +40,9 @@ interface IImmutableCollection extends IteratorAggregate, JsonSerializable, Seri
     /**
      * Checks if contains a value
      *
-     * @param mixed        $value  The value
+     * @param TValue $value  The value
      * @param bool   $strict Strict comparison ?
      *
-     * @psalm-param TValue $value
-     *
      * @return bool TRUE if the value exists, FALSE otherwise
      */
     public function contains ($value, bool $strict = false): bool;
@@ -51,26 +50,75 @@ interface IImmutableCollection extends IteratorAggregate, JsonSerializable, Seri
     /**
      * Get the value of a key or null if not found
      *
-     * @param array-key  $key The key
+     * @param TKey $key The key
-     *
-     * @psalm-param TKey $key
      *
-     * @return mixed The value
+     * @return TValue|null The value
-     * @psalm-return TValue|null
      */
     public function get ($key);
+    /**
+     * Get the value at an offset
+     *
+     * @param int $offset The offset
+     *
+     * @return TValue The value
+     *
+     * @throws OutOfBoundsException If the offset is not valid
+     */
+    public function getFromOffset (int $offset);
+
     /**
      * Get the first key of a value or null if not found
      *
-     * @param mixed        $value  The value
+     * @param TValue $value  The value
      * @param bool   $strict Strict comparison ?
      *
-     * @psalm-param TValue $value
+     * @return TKey|null
-     *
-     * @return array-key
-     * @psalm-return TKey|null
      */
     public function key ($value, bool $strict = false);
+    /**
+     * Get the key at an offset
+     *
+     * @param int $offset The offset
+     *
+     * @return TKey The key
+     *
+     * @throws OutOfBoundsException If the offset is not valid
+     */
+    public function keyFromOffset (int $offset);
+
+    /**
+     * Get the value of the first element
+     *
+     * @return TValue The value
+     *
+     * @throws OutOfBoundsException If the collection is empty
+     */
+    public function first ();
+    /**
+     * Get the key of the first element
+     *
+     * @return TKey The key
+     *
+     * @throws OutOfBoundsException If the collection is empty
+     */
+    public function firstKey ();
+
+    /**
+     * Get the value of the last element
+     *
+     * @return TValue The value
+     *
+     * @throws OutOfBoundsException If the collection is empty
+     */
+    public function last ();
+    /**
+     * Get the key of the last element
+     *
+     * @return TKey The key
+     *
+     * @throws OutOfBoundsException If the collection is empty
+     */
+    public function lastKey ();
 
     /**
      * Extract a slice of the collection
@@ -80,66 +128,93 @@ interface IImmutableCollection extends IteratorAggregate, JsonSerializable, Seri
      * @param int      $offset The start offset
      * @param int|null $length The maximum length. Null if until end of the collection
      *
-     * @return static
+     * @return static<TKey, TValue> The result collection
-     * @psalm-return static<TKey, TValue>
+     *
+     * @throws OutOfBoundsException If the offset is not valid
+     *
+     * @noinspection PhpMissingReturnTypeInspection
      */
-    public function slice (int $offset, ?int $length = null): self;
+    public function slice (int $offset, ?int $length = null);
 
     /**
      * Get a collection of all elements that satisfy predicate $filter
      *
-     * @param Closure                          $filter The filtering predicate
+     * @param Closure(TKey, TValue):bool $filter The filtering predicate
      *
-     * @psalm-param Closure(TKey, TValue):bool $filter
+     * @return static<TKey, TValue> The result collection
      *
-     * @return static The result collection
+     * @noinspection PhpMissingReturnTypeInspection
-     * @psalm-return static<TKey, TValue>
      */
-    public function filter (Closure $filter): self;
+    public function filter (Closure $filter);
     /**
      * Get a collection of all not empty elements
      *
      * Use {@see https://www.php.net/manual/function.empty.php empty} to check if element is empty or not
      *
-     * @return static The result collection
+     * @return static<TKey, TValue> The result collection
+     *
+     * @noinspection PhpMissingReturnTypeInspection
      */
-    public function withoutEmpties (): self;
+    public function withoutEmpties ();
     /**
-     * Remove all empty elements on current collection
+     * A new collection with <b>$process</b> applied on all elements
      *
-     * Use {@see https://www.php.net/manual/function.empty.php empty} to check if element is empty or not
+     * @template TResultValue
+     *
+     * @param Closure(TKey, TValue): TResultValue $process The process function to apply on each element
+     *
+     * @return static<TKey, TResultValue> The result collection
+     *
+     * @noinspection PhpMissingReturnTypeInspection
+     */
+    public function map (Closure $process);
+
+    /**
+     * Get a collection with the elements sorted (by value)
+     *
+     * @param null|IComparator|Closure(TValue, TValue):int $sorter The sorting method ; Null if values are object implementing {@see IComparable}.
+     *                                                             <br>Return :
+     *                                                             <br>&lt; 0 if value1 is before value2
+     *                                                             <br>= 0 if value1 equals value2
+     *                                                             <br>&gt; 0 if value1 is after value2
+     *
+     * @return static<TKey, TValue> The result collection
      *
-     * @return $this
+     * @throws Throwable If an error occurs
+     *
+     * @noinspection PhpMissingReturnTypeInspection
      */
-    public function removeEmpties (): self;
+    public function sort ($sorter = null);
     /**
-     * A new collection with $process applied on all elements
+     * Get a collection with the elements sorted by key
      *
-     * @psalm-template TResultValue
+     * @param IComparator|Closure(TKey, TKey):int $sorter The sorting method. Return :
+     *                                                    <br>&lt; 0 if key1 is before key2
+     *                                                    <br>= 0 if key1 equals key2
+     *                                                    <br>&gt; 0 if key1 is after key2
      *
-     * @param Closure                                   $process The process function to apply on each element
+     * @return static<TKey, TValue> The result collection
      *
-     * @psalm-param Closure(TKey, TValue): TResultValue $process
+     * @throws Throwable If an error occurs
      *
-     * @return static
+     * @noinspection PhpMissingReturnTypeInspection
-     * @psalm-return static<TKey, TResultValue>
      */
-    public function map (Closure $process): self;
+    public function sortByKey ($sorter);
 
     /**
      * The list of all keys
      *
-     * @return static The list of all keys
+     * @return IImmutableCollection<int, TKey> The list of all keys
-     * @psalm-return static<int, TKey>
      */
-    public function keys (): self;
+    public function keys (): IImmutableCollection;
     /**
      * The list of all values
      *
-     * @return static The list of all values
+     * @return static<int, TValue> The list of all values
-     * @psalm-return static<int, TValue>
+     *
+     * @noinspection PhpMissingReturnTypeInspection
      */
-    public function values (): self;
+    public function values ();
 
     /**
      * Join all values with a separator
@@ -155,16 +230,43 @@ interface IImmutableCollection extends IteratorAggregate, JsonSerializable, Seri
      * @param string $value     The value to split
      * @param string $separator The split separator
      *
-     * @return static
+     * @return static<int, string> The result collection
+     *
+     * @noinspection PhpMissingReturnTypeInspection
      */
-    public static function split (string $value, string $separator): self;
+    public static function split (string $value, string $separator);
 
     /**
-     * Combine the current collection with one or multiple other collections
+     * Create a collection filled with the same element
+     *
+     * @param int    $size  The collection size
+     * @param TValue $value The value to fill the collection
+     *
+     * @return static<int, TValue> The result collection
+     *
+     * @noinspection PhpMissingReturnTypeInspection
+     */
+    public static function fill (int $size, $value);
+    /**
+     * Create a collection filled with the same element, using a list of keys
+     *
+     * @param IImmutableCollection<TKey> $keys  The list of keys
+     * @param TValue                     $value The value to fill the collection
+     *
+     * @return static<TKey, TValue> The result collection
+     *
+     * @noinspection PhpMissingReturnTypeInspection
+     */
+    public static function fillWithKeys (IImmutableCollection $keys, $value);
+
+    /**
+     * Merge the current collection with one or multiple collections
+     *
+     * @param IImmutableCollection<TKey, TValue> ...$collections The other collections to merge
      *
-     * @param IImmutableCollection ...$collections The other collections to combine
+     * @return static<TKey, TValue> The result collection
      *
-     * @return static The combine collection
+     * @noinspection PhpMissingReturnTypeInspection
      */
-    public function combineWith (IImmutableCollection ...$collections): self;
+    public function mergeWith (IImmutableCollection ...$collections);
 }

src/Collections/ImmutableCollection.php

@@ -5,50 +5,44 @@ namespace jrosset\Collections;
 use ArrayIterator;
 use Closure;
 use InvalidArgumentException;
-use JsonException;
+use OutOfBoundsException;
 use Traversable;
 
 /**
  * An immutable collection
  *
- * @psalm-template     TKey of array-key
+ * @template TKey of array-key
- * @template-covariant TValue
+ * @template TValue
- * @template-implements IImmutableCollection<TKey, TValue>
+ *
+ * @implements IImmutableCollection<TKey, TValue>
  */
 class ImmutableCollection implements IImmutableCollection {
     /**
-     * @var array The internal array of elements
+     * @var array<TKey, TValue> The internal array of elements
-     * @psalm-var array<TKey, TValue>
-     *
-     * @internal
      */
     protected array $elements;
 
     /**
      * Initialise a new collection
      *
-     * @param array|Traversable|null $other The initial values
+     * @param iterable|null $other The initial values
-     *
-     * @psalm-param array<TKey, TValue>|Traversable<TKey, TValue>|null
      *
      * @throws InvalidArgumentException If the initial values aren't valid
      */
-    public function __construct ($other = null) {
+    public function __construct (?iterable $other = null) {
         $this->_initialize($other);
     }
 
     /**
      * Initialise the internals elements
      *
-     * @param array|Traversable|null $other The initial values
+     * @param iterable|null $other The initial values
-     *
-     * @psalm-param array<TKey, TValue>|Traversable<TKey, TValue>|null
      *
      * @throws InvalidArgumentException If the initial values aren't valid
-     * @internal
      *
+     * @internal
      */
-    protected function _initialize ($other = null) {
+    protected function _initialize (?iterable $other = null): void {
         $this->elements = [];
         if ($other !== null) {
             if (!is_array($other) && !$other instanceof Traversable) {
@@ -63,17 +57,16 @@ class ImmutableCollection implements IImmutableCollection {
     /**
      * Internally set a value to a key
      *
-     * @param array-key    $key   The key
+     * @param TKey   $key   The key
-     * @param mixed        $value The value
+     * @param TValue $value The value
-     *
-     * @psalm-param TKey   $key
-     * @psalm-param TValue $value
      *
      * @return $this
+     *
      * @internal
      *
+     * @noinspection PhpMissingReturnTypeInspection
      */
-    protected function _set ($key, $value): self {
+    protected function _set ($key, $value) {
         $this->elements[$this->_normalizeKey($key)] = $value;
         return $this;
     }
@@ -83,8 +76,12 @@ class ImmutableCollection implements IImmutableCollection {
      * @param IImmutableCollection ...$collections The collections to merge
      *
      * @return $this
+     *
+     * @internal
+     *
+     * @noinspection PhpMissingReturnTypeInspection
      */
-    protected function _merge (IImmutableCollection ...$collections): self {
+    protected function _merge (IImmutableCollection ...$collections) {
         foreach ($collections as $collection) {
             foreach ($collection as $key => $value) {
                 $this->_set($key, $value);
@@ -95,15 +92,15 @@ class ImmutableCollection implements IImmutableCollection {
     /**
      * Internally add a value
      *
-     * @param mixed        ...$values The value
+     * @param TValue ...$values The value
-     *
-     * @psalm-param TValue ...$value
      *
      * @return $this
+     *
      * @internal
      *
+     * @noinspection PhpMissingReturnTypeInspection
      */
-    protected function _add (...$values): self {
+    protected function _add (...$values) {
         foreach ($values as $value) {
             $this->elements[] = $value;
         }
@@ -114,9 +111,11 @@ class ImmutableCollection implements IImmutableCollection {
      *
      * @param IImmutableCollection ...$collections The collections to add
      *
-     * @return mixed
+     * @return $this
+     *
+     * @noinspection PhpMissingReturnTypeInspection
      */
-    protected function _addCollection (IImmutableCollection ...$collections): self {
+    protected function _addCollection (IImmutableCollection ...$collections) {
         foreach ($collections as $collection) {
             foreach ($collection as $value) {
                 $this->_add($value);
@@ -127,21 +126,32 @@ class ImmutableCollection implements IImmutableCollection {
     /**
      * Normalize a key
      *
-     * @param array-key  $key The key to normalize
+     * @param TKey $key The key to normalize
-     *
-     * @psalm-param TKey $key
      *
-     * @return array-key The normalized key
+     * @return TKey The normalized key
-     * @psalm-return TKey
      */
     protected function _normalizeKey ($key) {
         return $key;
     }
+    /**
+     * Vérifie un offset (&ge; 0, &lt; {@see static::count()})
+     *
+     * @param int $offset L'offset à vérifier
+     *
+     * @return void
+     *
+     * @throws OutOfBoundsException Si l'offset est invalide
+     */
+    protected function _checkOffset (int $offset): void {
+        if ($offset < 0 || $offset >= $this->count()) {
+            throw new OutOfBoundsException('The offset must be between 0 and ' . ($this->count() - 1));
+        }
+    }
 
     /**
      * @inheritDoc
      */
-    public function getIterator () {
+    public function getIterator (): ArrayIterator {
         return new ArrayIterator($this->elements);
     }
 
@@ -170,6 +180,16 @@ class ImmutableCollection implements IImmutableCollection {
         throw new ImmutableException();
     }
 
+    /**
+     * List of properties to {@see https://www.php.net/manual/function.serialize.php serialize}
+     *
+     * @return array[] List of properties to {@see https://www.php.net/manual/function.serialize.php serialize}
+     */
+    public function __serialize (): array {
+        return [
+            'elements' => $this->elements,
+        ];
+    }
     /**
      * @inheritDoc
      */
@@ -222,6 +242,14 @@ class ImmutableCollection implements IImmutableCollection {
     public function get ($key) {
         return $this->elements[$this->_normalizeKey($key)] ?? null;
     }
+    /**
+     * @inheritDoc
+     */
+    public function getFromOffset (int $offset) {
+        $this->_checkOffset($offset);
+        return array_values($this->elements)[$offset];
+    }
+
     /**
      * @inheritDoc
      */
@@ -233,11 +261,46 @@ class ImmutableCollection implements IImmutableCollection {
         }
         return null;
     }
+    /**
+     * @inheritDoc
+     */
+    public function keyFromOffset (int $offset) {
+        $this->_checkOffset($offset);
+        return array_keys($this->elements)[$offset];
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function first () {
+        return $this->getFromOffset(0);
+    }
+    /**
+     * @inheritDoc
+     */
+    public function firstKey () {
+        return $this->keyFromOffset(0);
+    }
 
     /**
      * @inheritDoc
      */
-    public function slice (int $offset, ?int $length = null): self {
+    public function last () {
+        return $this->getFromOffset($this->count() - 1);
+    }
+    /**
+     * @inheritDoc
+     */
+    public function lastKey () {
+        return $this->keyFromOffset($this->count() - 1);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function slice (int $offset, ?int $length = null) {
+        $this->_checkOffset($offset);
+
         $output = new static();
 
         $currentIndex = 0;
@@ -258,7 +321,7 @@ class ImmutableCollection implements IImmutableCollection {
     /**
      * @inheritDoc
      */
-    public function filter (Closure $filter): self {
+    public function filter (Closure $filter) {
         $output = new static();
         foreach ($this->elements as $key => $value) {
             if (!$filter($key, $value)) {
@@ -271,7 +334,7 @@ class ImmutableCollection implements IImmutableCollection {
     /**
      * @inheritDoc
      */
-    public function withoutEmpties (): self {
+    public function withoutEmpties () {
         return $this->filter(function ($value) {
             return empty($value);
         });
@@ -279,14 +342,7 @@ class ImmutableCollection implements IImmutableCollection {
     /**
      * @inheritDoc
      */
-    public function removeEmpties (): self {
+    public function map (Closure $process) {
-        $this->_initialize($this->withoutEmpties());
-        return $this;
-    }
-    /**
-     * @inheritDoc
-     */
-    public function map (Closure $process): self {
         $output = new static();
         foreach ($this->elements as $key => $value) {
             $output->_set($key, $process($key, $value));
@@ -297,23 +353,71 @@ class ImmutableCollection implements IImmutableCollection {
     /**
      * @inheritDoc
      */
-    public function keys (): self {
+    public function sort ($sorter = null) {
+        $elements = $this->toArray();
+        uasort($elements, self::_normalizeSorter($sorter));
+
+        return new static($elements);
+    }
+    /**
+     * @inheritDoc
+     */
+    public function sortByKey ($sorter) {
+        $elements = $this->toArray();
+        uksort($elements, self::_normalizeSorter($sorter));
+
+        return new static($elements);
+    }
+
+    /**
+     * Normalize a sorter method
+     *
+     * @param null|IComparator|Closure(TValue, TValue):int $sorter The sorting method ; Null if values are object implementing {@see IComparable}.
+     *                                                             <br>Return :
+     *                                                             <br>&lt; 0 if value1 is before value2
+     *                                                             <br>= 0 if value1 equals value2
+     *                                                             <br>&gt; 0 if value1 is after value2
+     *
+     * @return Closure(TValue, TValue):int The normalized sorter method
+     *                                     <br>Return :
+     *                                     <br>&lt; 0 if value1 is before value2
+     *                                     <br>= 0 if value1 equals value2
+     *                                     <br>&gt; 0 if value1 is after value2
+     */
+    public static function _normalizeSorter ($sorter): Closure {
+        if ($sorter === null) {
+            return function (IComparable $value1, IComparable $value2): int {
+                return $value1->compareTo($value2);
+            };
+        }
+        elseif ($sorter instanceof IComparator) {
+            return function ($value1, $value2) use ($sorter): int {
+                return $sorter->compare($value1, $value2);
+            };
+        }
+        else {
+            return $sorter;
+        }
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function keys (): IImmutableCollection {
         return new static(array_keys($this->elements));
     }
     /**
      * @inheritDoc
      */
-    public function values (): self {
+    public function values () {
         return new static(array_values($this->elements));
     }
 
     /**
      * @inheritDoc
-     *
-     * @throws JsonException
      */
     public function jsonSerialize () {
-        return json_encode($this->elements, JSON_THROW_ON_ERROR);
+        return $this->elements;
     }
 
     /**
@@ -325,14 +429,36 @@ class ImmutableCollection implements IImmutableCollection {
     /**
      * @inheritDoc
      */
-    public static function split (string $value, string $separator): self {
+    public static function split (string $value, string $separator) {
         return new static (explode($separator, $value));
     }
 
     /**
      * @inheritDoc
      */
-    public function combineWith (IImmutableCollection ...$collections): IImmutableCollection {
+    public static function fill (int $size, $value) {
+        $keys = new ImmutableCollection();
+        for ($curr = 0; $curr < $size; $curr++) {
+            $keys->_add($curr);
+        }
+
+        return static::fillWithKeys($keys, $value);
+    }
+    /**
+     * @inheritDoc
+     */
+    public static function fillWithKeys (IImmutableCollection $keys, $value) {
+        $collection = new static();
+        foreach ($keys as $key) {
+            $collection->_set($key, $value);
+        }
+        return $collection;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function mergeWith (IImmutableCollection ...$collections) {
         return (clone $this)->_merge(...$collections);
     }
 }

src/Collections/InsensitiveCaseKeyCollection.php

@@ -5,9 +5,10 @@ namespace jrosset\Collections;
 /**
  * A collection with insensitive case keys
  *
- * @psalm-template     TKey of array-key
+ * @template TKey of array-key
- * @template-covariant TValue
+ * @template TValue
- * @template-extends Collection<TKey, TValue>
+ *
+ * @implements Collection<TKey, TValue>
  */
 class InsensitiveCaseKeyCollection extends Collection {
     use TInsensitiveCaseKey;

src/Collections/InsensitiveCaseKeyImmutableCollection.php

@@ -5,9 +5,10 @@ namespace jrosset\Collections;
 /**
  * An immutable collection with insensitive case keys
  *
- * @psalm-template     TKey of array-key
+ * @template TKey of array-key
- * @template-covariant TValue
+ * @template TValue
- * @template-extends ImmutableCollection<TKey, TValue>
+ *
+ * @implements ImmutableCollection<TKey, TValue>
  */
 class InsensitiveCaseKeyImmutableCollection extends ImmutableCollection implements IImmutableCollection {
     use TInsensitiveCaseKey;

src/Collections/TUniqueValues.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace jrosset\Collections;
+
+/**
+ * Implementation for unique collection
+ *
+ * @template TKey of array-key
+ * @template TValue
+ */
+trait TUniqueValues {
+    /**
+     * @inheritDoc
+     */
+    protected function _set ($key, $value): self {
+        if ($this->contains($value)) {
+            return $this;
+        }
+
+        $this->elements[$this->_normalizeKey($key)] = $value;
+        return $this;
+    }
+    /**
+     * @inheritDoc
+     */
+    protected function _add (...$values): self {
+        foreach ($values as $value) {
+            if ($this->contains($value)) {
+                continue;
+            }
+            $this->elements[] = $value;
+        }
+        return $this;
+    }
+}

src/Collections/UniqueCollection.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace jrosset\Collections;
+
+/**
+ * A collection with unique values
+ *
+ * @template TKey of array-key
+ * @template TValue
+ *
+ * @implements Collection<TKey, TValue>
+ * @implements TUniqueValues<TKey, TValue>
+ */
+class UniqueCollection extends Collection {
+    use TUniqueValues;
+}

src/Collections/UniqueImmutableCollection.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace jrosset\Collections;
+
+/**
+ * An immutable collection with unique values
+ *
+ * @template TKey of array-key
+ * @template TValue
+ *
+ * @implements ImmutableCollection<TKey, TValue>
+ * @implements TUniqueValues<TKey, TValue>
+ */
+class UniqueImmutableCollection extends ImmutableCollection {
+    use TUniqueValues;
+}

tests/test.php

@@ -1,5 +1,6 @@
 <?php
 
+use jrosset\Collections\ImmutableCollection;
 use jrosset\Collections\InsensitiveCaseKeyCollection;
 use jrosset\Collections\InsensitiveCaseKeyImmutableCollection;
 
@@ -19,3 +20,8 @@ echo '-----' . PHP_EOL;
 $collection = new InsensitiveCaseKeyCollection($readOnlyCollection);
 $collection->add(28);
 echo 'Size : ' . $collection->count() . PHP_EOL;
+
+echo 'Fill :' . PHP_EOL;
+foreach (ImmutableCollection::fill(5, -1) as $key => $value) {
+    echo "\t#" . $key . ' = ' . $value . PHP_EOL;
+}

tests/test_class.php

@@ -1,11 +1,19 @@
 <?php
+/** @noinspection PhpUnhandledExceptionInspection */
 /** @noinspection PhpIllegalPsrClassPathInspection */
 
 use jrosset\Collections\Collection;
+use jrosset\Collections\IComparable;
+use jrosset\Collections\IComparator;
 
 require_once __DIR__ . '/../vendor/autoload.php';
 
-class Measure {
+/**
+ * Class Measure
+ *
+ * @implements IComparable<static>
+ */
+class Measure implements IComparable {
     private int    $value;
     private string $unit;
 
@@ -14,9 +22,33 @@ class Measure {
         $this->unit = $unit;
     }
 
+    public function getValue (): int {
+        return $this->value;
+    }
+
     public function asString (): string {
         return $this->value . $this->unit;
     }
+
+    /**
+     * @inheritDoc
+     */
+    public function compareTo ($other): int {
+        return $this->value <=> $other->value;
+    }
+}
+/**
+ * Class MeasureReverseComparator
+ *
+ * @implements IComparator<Measure>
+ */
+class MeasureReverseComparator implements IComparator {
+    /**
+     * @inheritDoc
+     */
+    public function compare ($object1, $object2): int {
+        return -($object1->getValue() <=> $object2->getValue());
+    }
 }
 
 /**
@@ -33,7 +65,15 @@ function getMeasures (): Collection {
     return $measures;
 }
 
+$measures = getMeasures();
+$measures->sortSelf();
+
 echo 'Measures :' . PHP_EOL;
-foreach (getMeasures() as $no => $measure) {
+foreach ($measures as $no => $measure) {
+    echo "\t#" . $no . ' = ' . $measure->asString() . PHP_EOL;
+}
+
+echo 'Measures (reversed) :' . PHP_EOL;
+foreach ($measures->sort(new MeasureReverseComparator()) as $no => $measure) {
     echo "\t#" . $no . ' = ' . $measure->asString() . PHP_EOL;
 }