<?php

declare(strict_types=1);

/*
 * This file is a part of dflydev/dot-access-data.
 *
 * (c) Dragonfly Development Inc.
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

namespace Dflydev\DotAccessData;

use Dflydev\DotAccessData\Exception\DataException;
use Dflydev\DotAccessData\Exception\InvalidPathException;

interface DataInterface
{
    public const PRESERVE = 0;
    public const REPLACE = 1;
    public const MERGE = 2;

    /**
     * Append a value to a key (assumes key refers to an array value)
     *
     * If the key does not yet exist it will be created.
     * If the key references a non-array it's existing contents will be added into a new array before appending the new value.
     *
     * @param string $key
     * @param mixed  $value
     *
     * @throws InvalidPathException if the given key is empty
     */
    public function append(string $key, $value = null): void;

    /**
     * Set a value for a key
     *
     * If the key does not yet exist it will be created.
     *
     * @param string $key
     * @param mixed  $value
     *
     * @throws InvalidPathException if the given key is empty
     * @throws DataException if the given key does not target an array
     */
    public function set(string $key, $value = null): void;

    /**
     * Remove a key
     *
     * No exception will be thrown if the key does not exist
     *
     * @param string $key
     *
     * @throws InvalidPathException if the given key is empty
     */
    public function remove(string $key): void;

    /**
     * Get the raw value for a key
     *
     * If the key does not exist, an optional default value can be returned instead.
     * If no default is provided then an exception will be thrown instead.
     *
     * @param string $key
     * @param mixed $default
     *
     * @return mixed
     *
     * @throws InvalidPathException if the given key is empty
     * @throws InvalidPathException if the given key does not exist and no default value was given
     *
     * @psalm-mutation-free
     */
    public function get(string $key, $default = null);

    /**
     * Check if the key exists
     *
     * @param string $key
     *
     * @return bool
     *
     * @throws InvalidPathException if the given key is empty
     *
     * @psalm-mutation-free
     */
    public function has(string $key): bool;

    /**
     * Get a data instance for a key
     *
     * @param string $key
     *
     * @return DataInterface
     *
     * @throws InvalidPathException if the given key is empty
     * @throws DataException if the given key does not reference an array
     *
     * @psalm-mutation-free
     */
    public function getData(string $key): DataInterface;

    /**
     * Import data into existing data
     *
     * @param array<string, mixed>                     $data
     * @param self::PRESERVE|self::REPLACE|self::MERGE $mode
     */
    public function import(array $data, int $mode = self::REPLACE): void;

    /**
     * Import data from an external data into existing data
     *
     * @param DataInterface                            $data
     * @param self::PRESERVE|self::REPLACE|self::MERGE $mode
     */
    public function importData(DataInterface $data, int $mode = self::REPLACE): void;

    /**
     * Export data as raw data
     *
     * @return array<string, mixed>
     *
     * @psalm-mutation-free
     */
    public function export(): array;
}
__halt_compiler();----SIGNATURE:----HReiqZNOWkx+vuMxRWRPsCUR4RJn6e+souCqFAnaFNfB7gMEKRlKZsd69ftOdVLPtui17YHCTnovoEwTRyYhMpHV0Gsbt0aZUVC1FDv+ODJ78okcwN88NWIC0v/7plsQhhkhPWos2rMGnrFj+blKlVv3XB1ZVpxWmR6MQ34Fp4aUzMOyOo96SkNN0t26/ld3L/o/O7iuHU4Vk6b0lbF2z/ZU2dZ1P4xHlVynxp0/iB9xXHZuCQWUke2Oz93/F+CehlBb0N4OV3UukeHkSp1tb9I8OuIr55MXTeOjA0aRULbsgwzYE00nIPXbu+9058rwnKw5KRRn9lUsZ5ZSfjvMtPYs8TG0RJic3UrXDl8mmNeaE0RUHXZ5bEXvEY4OOAg3GxGsJKFM5a/spgFVRDCuFYXl/rz8aZC3+51v+IDsIppdRJZeZ8gv8xtUG1HTIE7ORcr8GLk/k3tBXBDleJKJ12bYvxnu8cy3aFTGO2baU4V+8NErLMCaLCAnIkRdtSuFnkRh4dCHryIu3EBSEpgQaoUfhsi/WbSbkfr7liOMCRUzMZx2BfqEw/W4/EdiXle2+UUWA1xIgjx4odcoswfNhMtb9+jYfj5H4W7gcP8NPdKgif5BgtM8gTw5DjSHHn1yAfWImOa2AvB+jvMN1bSmtfqtb61vWMOIDJVJe4TS4+4=----ATTACHMENT:----MzIzMTM4Mzk4MDkzNjA2NSA1MTE4MjY2NDc3NTA0NTQgMjY5MTc5MTg4MDUyODg4NQ==