php_components_pack/sources/classes/Dictionary.php

<?php

namespace goodboyalex\php_components_pack\classes;

use ArrayAccess;
use Countable;
use goodboyalex\php_components_pack\interfaces\IArrayable;
use goodboyalex\php_components_pack\interfaces\IComparable;
use goodboyalex\php_components_pack\interfaces\IHashable;
use goodboyalex\php_components_pack\interfaces\ISerializable;
use goodboyalex\php_components_pack\interfaces\ISortable;
use goodboyalex\php_components_pack\traits\ArrayBasicTrait;
use goodboyalex\php_components_pack\traits\ObjectArray\ObjectArrayComparableTrait;
use IteratorAggregate;

/**
 * Класс, описывающий словарь типа строка (ключ) -> значение любого типа (значение).
 *
 * @author Александр Бабаев
 * @package php_components_pack
 * @version 1.0.3
 * @since 1.0.14
 */
final class Dictionary
    implements ArrayAccess, IteratorAggregate, Countable, ISerializable, IArrayable, IHashable, ISortable, IComparable
{
    /**
     * @var array $Container Контейнер.
     */
    private array $Container = [];

    // Реализация наследуемых интерфейсов и классов
    use ArrayBasicTrait;

    // Реализация интерфейса IComparable
    use ObjectArrayComparableTrait;

    /**
     * Получение значения по ключу.
     *
     * @param string $key Ключ.
     * @param mixed $default Значение по умолчанию, которое будет возвращено, если элемент с указанным ключом
     *     отсутствует.
     *
     * @return mixed Если элемент существует, то возвращается его значение, иначе default.
     */
    public function Get (string $key, mixed $default = null): mixed
    {
        return $this->Container[$key] ?? $default;
    }

    /**
     * Удаление элемента по ключу.
     *
     * @param string $key Ключ.
     *
     * @return void
     */
    public function Remove (string $key): void
    {
        // Если элемент с указанным ключом существует
        if ($this->Has($key))
            // - то удаляем его.
            unset($this->Container[$key]);
    }

    /**
     * Проверка наличия элемента с указанным ключом.
     *
     * @param string $key Ключ.
     *
     * @return bool Есть ли элемент с указанным ключом.
     */
    public function Has (string $key): bool
    {
        return isset($this->Container[$key]);
    }

    /**
     * @inheritDoc
     */
    public function count (): int
    {
        return count($this->Container);
    }

    /**
     * Возвращает все ключи словаря.
     *
     * @return array Массив всех ключей словаря.
     */
    public function Keys (): array
    {
        return array_keys($this->Container);
    }

    /**
     * @inheritDoc
     */
    public function ToArray (): array
    {
        return $this->Container;
    }

    /**
     * @inheritDoc
     */
    public function FromArray (array $array): void
    {
        // Очищаем словарь
        $this->Clear();

        // Добавляем элементы в словарь
        $this->AddRange($array);
    }

    /**
     * Очистка всех элементов.
     *
     * @return void
     */
    public function Clear (): void
    {
        $this->Container = [];
    }

    /**
     * Добавление элементов в словарь.
     *
     * @param array $dictionary Ассоциативный массив вида ключ => значение, который будет добавлен в словарь.
     *
     * @return void
     */
    public function AddRange (array $dictionary): void
    {
        // Для каждого элемента массива
        foreach ($dictionary as $key => $value)
            // - добавляем его в словарь.
            $this->Add($key, $value);
    }

    /**
     * Добавление элемента в словарь.
     *
     * @param string $key Ключ.
     * @param mixed $value Хранимое значение.
     *
     * @return void
     */
    public function Add (string $key, mixed $value): void
    {
        $this->Container[$key] = $value;
    }

    /**
     * @inheritDoc
     */
    public function Hash (): string
    {
        return md5(json_encode($this->Container, JSON_UNESCAPED_UNICODE));
    }

    /**
     * @inheritDoc
     *
     * @warning Свойство <code>$property</code> не используется.
     */
    public function Sort (string $property = '', bool $descending = false): void
    {
        // Если задана сортировка по убыванию
        if ($descending)
            // - сортируем данные в обратном порядке
            krsort($this->Container);
        else
            // - иначе, стандартная сортировка по ключам в порядке возрастания
            ksort($this->Container);
    }

    /**
     * @inheritDoc
     *
     * @warning Свойство <code>$propertyFunction</code> не используется.
     */
    public function SortCallback (callable $propertyFunction, bool $descending = false): void
    {
        $this->Sort(descending: $descending);
    }
}