<?php
namespace nulib\php\access;

/**
 * Interface IAccess: abstraction d'un accès complet à une valeur
 */
interface IAccess extends IGetter, ISetter, IDeleter {
  /** incrémenter la valeur et la retourner */
  function inc(): int;

  /** décrémenter la valeur et la retourner */
  function dec(bool $allowNegative=false): int;

  /**
   * fusionner le tableau $values dans la destination, qui est transformée en
   * tableau d'abord si nécessaire
   */
  function merge(?array $values): void;

  /**
   * ajouter la valeur à la destination, qui est transformée en tableau d'abord
   * si nécessaire
   *
   * la valeur est ajoutée avec la clé $key le cas échéant, ou à la fin du
   * tableau si $key===null
   */
  function append($value, $key=null): void;

  /** retourner une instance permettant d'accéder à $value[$key] */
  function addKey($key): IAccess;

  /**
   * s'assurer que la destination est un tableau associatif en remplaçant les
   * clés numériques par les clés correspondantes du tableau $keys
   */
  function ensureAssoc(array $keys, ?array $params=null): void;

  /**
   * s'assurer que toutes les clés mentionnées dans le tableau $defaults
   * existent. si elles n'existent pas, ou si elles ont la valeur correspondante
   * du tableau $missings, leur donner la valeur du tableau $defaults
   */
  function ensureKeys(array $defaults, ?array $missings, ?array $params=null): void;

  /**
   * supprimer toutes les clés dont la valeur est celle mentionnée dans le
   * tableau $missings
   */
  function deleteMissings(array $missings, ?array $params=null): void;

  /**
   * s'assure que les clés de la destination sont dans l'ordre mentionné dans le
   * tableau $keys. toutes les clés supplémentaires sont placées à la fin
   */
  function ensureOrder(array $keys, ?array $params=null): void;
}
