<?php

namespace jrosset\Collections;

use ArrayAccess;
use Closure;
use Countable;
use IteratorAggregate;
use JsonSerializable;
use Throwable;

/**
 * Interface for an immutable (read-only) collection
 *
 * @psalm-template     TKey of array-key
 * @template-covariant TValue
 * @template-extends IteratorAggregate<TKey, TValue>
 * @template-extends ArrayAccess<TKey, TValue>
 * @template-extends IArrayCast<TKey, TValue>
 */
interface IImmutableCollection extends IteratorAggregate, JsonSerializable, Countable, ArrayAccess, IArrayCast {
    /**
     * Checks if the collection is empty
     *
     * @return bool TRUE if the collection is empty, FALSE otherwise
     */
    public function empty (): bool;

    /**
     * Checks if a key exists
     *
     * @param array-key  $key The key
     *
     * @psalm-param TKey $key
     *
     * @return bool TRUE if the key exists, FALSE otherwise
     */
    public function exists (int|string $key): bool;
    /**
     * Checks if contains a value
     *
     * @param mixed        $value  The value
     * @param bool         $strict Strict comparison ?
     *
     * @psalm-param TValue $value
     *
     * @return bool TRUE if the value exists, FALSE otherwise
     */
    public function contains (mixed $value, bool $strict = false): bool;

    /**
     * Get the value of a key or null if not found
     *
     * @param array-key  $key The key
     *
     * @psalm-param TKey $key
     *
     * @return mixed The value
     * @psalm-return TValue|null
     */
    public function get (int|string $key): mixed;
    /**
     * Get the first key of a value or null if not found
     *
     * @param mixed        $value  The value
     * @param bool         $strict Strict comparison ?
     *
     * @psalm-param TValue $value
     *
     * @return array-key|null
     * @psalm-return TKey|null
     */
    public function key (mixed $value, bool $strict = false): int|string|null;

    /**
     * Extract 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 static
     * @psalm-return static<TKey, TValue>
     */
    public function slice (int $offset, ?int $length = null): self;

    /**
     * Get a collection of all elements that satisfy predicate $filter
     *
     * @param Closure                          $filter The filtering predicate
     *
     * @psalm-param Closure(TKey, TValue):bool $filter
     *
     * @return static The result collection
     * @psalm-return static<TKey, TValue>
     */
    public function filter (Closure $filter): self;
    /**
     * 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
     */
    public function withoutEmpties (): self;
    /**
     * Remove all empty elements on current collection
     *
     * Use {@see https://www.php.net/manual/function.empty.php empty} to check if element is empty or not
     *
     * @return $this
     */
    public function removeEmpties (): self;
    /**
     * A new collection with $process applied on all elements
     *
     * @psalm-template TResultValue
     *
     * @param Closure                                   $process The process function to apply on each element
     *
     * @psalm-param Closure(TKey, TValue): TResultValue $process
     *
     * @return static
     * @psalm-return static<TKey, TResultValue>
     */
    public function map (Closure $process): self;

    /**
     * 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 static The sorted collection
     * @psalm-return static<TKey, TValue>
     *
     * @throws Throwable If an error occurs
     */
    public function sort (Closure|IComparator|null $sorter = null): static;
    /**
     * 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 static The sorted collection
     * @psalm-return static<TKey, TValue>
     *
     * @throws Throwable If an error occurs
     */
    public function sortByKey (Closure|IComparator $sorter): static;

    /**
     * The list of all keys
     *
     * @return static The list of all keys
     * @psalm-return static<int, TKey>
     */
    public function keys (): self;
    /**
     * The list of all values
     *
     * @return static The list of all values
     * @psalm-return static<int, TValue>
     */
    public function values (): self;

    /**
     * Join all values with a separator
     *
     * @param string $separator The separator
     *
     * @return string The joined values
     */
    public function join (string $separator): string;
    /**
     * Create a collection of split values
     *
     * @param string $value     The value to split
     * @param string $separator The split separator
     *
     * @return static
     */
    public static function split (string $value, string $separator): self;

    /**
     * Combine the current collection with one or multiple other collections
     *
     * @param IImmutableCollection ...$collections The other collections to combine
     *
     * @return static The combined collection
     */
    public function combineWith (IImmutableCollection ...$collections): self;
}