nulib/php/src_base/cl.php

<?php
namespace nulib;

use ArrayAccess;
use Traversable;

/**
 * Class cl: gestion de tableau de valeurs scalaires
 */
class cl {
  /** retourner un array non null à partir de $array */
  static final function with($array): array {
    if (is_array($array)) return $array;
    elseif ($array === null || $array === false) return [];
    elseif ($array instanceof Traversable) return iterator_to_array($array);
    else return [$array];
  }

  /** retourner un array à partir de $array, ou null */
  static final function withn($array): ?array {
    if (is_array($array)) return $array;
    elseif ($array === null || $array === false) return null;
    elseif ($array instanceof Traversable) return iterator_to_array($array);
    else return [$array];
  }

  /**
   * s'assurer que $array est un array non null. retourner true si $array n'a
   * pas été modifié (s'il était déjà un array), false sinon.
   */
  static final function ensure_array(&$array): bool {
    if (is_array($array)) return true;
    elseif ($array === null || $array === false) $array = [];
    elseif ($array instanceof Traversable) $array =  iterator_to_array($array);
    else $array = [$array];
    return false;
  }

  /**
   * s'assurer que $array est un array s'il est non null. retourner true si
   * $array n'a pas été modifié (s'il était déjà un array ou s'il valait null).
   */
  static final function ensure_narray(&$array): bool {
    if ($array === null || is_array($array)) return true;
    elseif ($array === false) $array = [];
    elseif ($array instanceof Traversable) $array =  iterator_to_array($array);
    else $array = [$array];
    return false;
  }

  /** tester si $array a au moins une clé numérique */
  static final function have_num_keys(?array $array): bool {
    if ($array === null) return false;
    foreach ($array as $key => $value) {
      if (is_int($key)) return true;
    }
    return false;
  }

  /**
   * tester si $array est une liste, c'est à dire un tableau non null avec
   * uniquement des clés numériques séquentielles commençant à zéro
   *
   * NB: is_list(null) === false
   * et  is_list([])   === true
   */
  static final function is_list(?array $array): bool {
    if ($array === null) return false;
    $index = -1;
    foreach ($array as $key => $value) {
      ++$index;
      if ($key !== $index) return false;
    }
    return true;
  }

  /**
   * tester si $array contient la clé $key
   *
   * @param array|ArrayAccess $array
   */
  static final function has($array, $key): bool {
    if (is_array($array)) {
      return array_key_exists($key, $array);
    } elseif ($array instanceof ArrayAccess) {
      return $array->offsetExists($key);
    }
    return false;
  }

  /**
   * retourner $array[$key] ou $default si la clé n'existe pas
   *
   * @param array|ArrayAccess $array
   */
  static final function get($array, $key, $default=null) {
    if (is_array($array)) {
      if (array_key_exists($key, $array)) return $array[$key];
    } elseif ($array instanceof ArrayAccess) {
      if ($array->offsetExists($key)) return $array->offsetGet($key);
    }
    return $default;
  }

  /**
   * si $array est un array ou une instance de ArrayAccess, créer ou modifier
   * l'élément dont la clé est $key
   *
   * @param array|ArrayAccess $array
   */
  static final function set(&$array, $key, $value): void {
    if (is_array($array) || $array === null) {
      if ($key === null) $array[] = $value;
      else $array[$key] = $value;
    } elseif ($array instanceof ArrayAccess) {
      $array->offsetSet($key, $value);
    }
  }

  /**
   * si $array est un array ou une instance de ArrayAccess, supprimer l'élément
   * dont la clé est $key
   *
   * @param array|ArrayAccess $array
   */
  static final function del(&$array, $key): void {
    if (is_array($array)) {
      unset($array[$key]);
    } elseif ($array instanceof ArrayAccess) {
      $array->offsetUnset($key);
    }
  }

  /** retourner le nombre d'éléments de $array */
  static final function count(?array $array): int {
    return $array !== null? count($array): 0;
  }

  /** retourner la liste des clés de $array */
  static final function keys(?array $array): array {
    return $array !== null? array_keys($array): [];
  }

  #############################################################################

  /**
   * Fusionner tous les tableaux spécifiés. Les valeurs null sont ignorées.
   * Retourner null si aucun tableau n'est fourni ou s'ils étaient tous null.
   */
  static final function merge(...$arrays): ?array {
    $merges = [];
    foreach ($arrays as $array) {
      self::ensure_narray($array);
      if ($array !== null) $merges[] = $array;
    }
    return $merges? array_merge(...$merges): null;
  }

  #############################################################################

  /**
   * vérifier que le chemin $keys existe dans le tableau $array
   *
   * si $keys est vide ou null, retourner true
   */
  static final function phas($array, $pkey): bool {
    # optimisations
    if ($pkey === null || $pkey === []) {
      return true;
    } elseif (is_int($pkey) || (is_string($pkey) && strpos($pkey, ".") === false)) {
      return self::has($array, $pkey);
    } elseif (!is_array($pkey)) {
      $pkey = explode(".", strval($pkey));
    }
    # phas
    $first = true;
    foreach($pkey as $key) {
      if ($key === "" && $first) {
        # une chaine vide en première position est ignorée
        continue;
      } elseif (is_array($array)) {
        if (!array_key_exists($key, $array)) return false;
        $array = $array[$key];
      } elseif ($array instanceof ArrayAccess) {
        if (!$array->offsetExists($key)) return false;
        $array = $array->offsetGet($key);
      } else {
        return false;
      }
      $first = false;
    }
    return true;
  }

  static final function each_phas($array, ?array $pkeys): array {
    $result = [];
    if ($pkeys !== null) {
      foreach ($pkeys as $pkey) {
        $result[] = self::phas($array, $pkey);
      }
    }
    return $result;
  }

  /**
   * obtenir la valeur correspondant au chemin $keys dans $array
   *
   * si $keys est vide ou null, retourner $default
   */
  static final function pget($array, $pkey, $default=null) {
    # optimisations
    if ($pkey === null || $pkey === []) return $default;
    elseif ($pkey === "") return $array;
    elseif (is_int($pkey) || (is_string($pkey) && strpos($pkey, ".") === false)) {
      return self::get($array, $pkey, $default);
    } elseif (!is_array($pkey)) {
      $pkey = explode(".", strval($pkey));
    }
    # pget
    $value = $array;
    $first = true;
    foreach($pkey as $key) {
      if ($key === "" && $first) {
        # une chaine vide en première position est ignorée
        continue;
      } elseif (is_array($value)) {
        if (!array_key_exists($key, $value)) return $default;
        $value = $value[$key];
      } elseif ($value instanceof ArrayAccess) {
        if (!$value->offsetExists($key)) return $default;
        $value = $value->offsetGet($key);
      } else {
        return $default;
      }
      $first = false;
    }
    return $value;
  }

  static final function each_pget($array, ?array $pkeys): array {
    $result = [];
    if ($pkeys !== null) {
      foreach ($pkeys as $key => $pkey) {
        $result[$key] = self::pget($array, $pkey);
      }
    }
    return $result;
  }

  /**
   * modifier la valeur au chemin de clé $keys dans le tableau $array
   *
   * utiliser la clé "" (chaine vide) en dernière position pour rajouter à la fin, e.g
   * - pset($array, [""], $value) est équivalent à $array[] = $value
   * - pset($array, ["a", "b", ""], $value) est équivalent à $array["a"]["b"][] = $value
   * la clé "" n'a pas de propriété particulière quand elle n'est pas en dernière position
   *
   * si $keys est vide ou null, $array est remplacé par $value
   */
  static final function pset(&$array, $pkey, $value): void {
    # optimisations
    if ($pkey === null || $pkey === []) {
      $array = $value;
      return;
    } elseif ($pkey === "") {
      $array[] = $value;
      return;
    } elseif (is_int($pkey) || (is_string($pkey) && strpos($pkey, ".") === false)) {
      self::set($array, $pkey, $value);
      return;
    } elseif (!is_array($pkey)) {
      $pkey = explode(".", strval($pkey));
    }
    # pset
    self::ensure_array($array);
    $current =& $array;
    $key = null;
    $last = count($pkey) - 1;
    $i = 0;
    foreach ($pkey as $key) {
      if ($i == $last) break;
      if ($current instanceof ArrayAccess) {
        if (!$current->offsetExists($key)) $current->offsetSet($key, []);
        $current =& $current->offsetGet($key);
        if ($current === null) {
          $current = [];
        } elseif (!is_array($current) && !($current instanceof ArrayAccess)) {
          $current = [$current];
        }
      } else {
        self::ensure_array($current[$key]);
        $current =& $current[$key];
      }
      $i++;
    }
    if ($key === "") $current[] = $value;
    else $current[$key] = $value;
  }

  static final function each_pset(&$array, ?array $values): void {
    if ($values !== null) {
      foreach ($values as $pkey => $value) {
        self::pset($array, $pkey, $value);
      }
    }
  }

  /**
   * supprimer la valeur au chemin de clé $keys dans $array
   *
   * si $array vaut null ou false, sa valeur est inchangée.
   * si $keys est vide ou null, $array devient null
   */
  static final function pdel(&$array, $pkey): void {
    # optimisations
    if ($array === null || $array === false) {
      return;
    } elseif ($pkey === null || $pkey === []) {
      $array = null;
      return;
    } elseif (is_int($pkey) || (is_string($pkey) && strpos($pkey, ".") === false)) {
      self::del($array, $pkey);
      return;
    } elseif (!is_array($pkey)) {
      $pkey = explode(".", strval($pkey));
    }
    # pdel
    self::ensure_array($array);
    $current =& $array;
    $key = null;
    $last = count($pkey) - 1;
    $i = 0;
    foreach ($pkey as $key) {
      if ($i == $last) break;
      if ($current instanceof ArrayAccess) {
        if (!$current->offsetExists($key)) break;
      } elseif (is_array($current)) {
        if (!array_key_exists($key, $current)) break;
      } else {
        break;
      }
      $current =& $current[$key];
      $i++;
    }
    if ($i == $last) {
      if ($current instanceof ArrayAccess) {
        $current->offsetUnset($key);
      } elseif (is_array($current)) {
        unset($current[$key]);
      }
    }
  }

  static final function each_pdel(&$array, ?array $pkeys): void {
    if ($pkeys !== null) {
      foreach ($pkeys as $pkey) {
        self::pdel($array, $pkey);
      }
    }
  }

  #############################################################################

  /**
   * retourner le tableau $array en "renommant" les clés selon le tableau
   * $mappings qui contient des associations de la forme [$from => $to]
   */
  static function rekey(?array $array, ?array $mappings): ?array {
    if ($array === null || $mappings === null) return $array;
    $mapped = [];
    foreach ($array as $key => $value) {
      if (array_key_exists($key, $mappings)) $key = $mappings[$key];
      $mapped[$key] = $value;
    }
    return $mapped;
  }

  #############################################################################

  /** tester si tous les éléments du tableau satisfont la condition */
  static final function all_if(?array $array, callable $cond): bool {
    if ($array !== null) {
      foreach ($array as $value) {
        if (!$cond($value)) return false;
      }
    }
    return true;
  }

  static final function all_z(?array $array): bool { return self::all_if($array, [cv::class, "z"]);}
  static final function all_nz(?array $array): bool { return self::all_if($array, [cv::class, "nz"]);}
  static final function all_n(?array $array): bool { return self::all_if($array, [cv::class, "n"]);}
  static final function all_nn(?array $array): bool { return self::all_if($array, [cv::class, "nn"]);}
  static final function all_t(?array $array): bool { return self::all_if($array, [cv::class, "t"]);}
  static final function all_f(?array $array): bool { return self::all_if($array, [cv::class, "f"]);}
  static final function all_pt(?array $array): bool { return self::all_if($array, [cv::class, "pt"]);}
  static final function all_pf(?array $array): bool { return self::all_if($array, [cv::class, "pf"]);}
  static final function all_equals(?array $array, $value): bool { return self::all_if($array, cv::equals($value)); }
  static final function all_not_equals(?array $array, $value): bool { return self::all_if($array, cv::not_equals($value)); }
  static final function all_same(?array $array, $value): bool { return self::all_if($array, cv::same($value)); }
  static final function all_not_same(?array $array, $value): bool { return self::all_if($array, cv::not_same($value)); }

  #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  /** tester si au moins un élément du tableau satisfait la condition */
  static final function any_if(?array $array, callable $cond): bool {
    if ($array !== null) {
      foreach ($array as $value) {
        if ($cond($value)) return true;
      }
    }
    return false;
  }

  static final function any_z(?array $array): bool { return self::any_if($array, [cv::class, "z"]);}
  static final function any_nz(?array $array): bool { return self::any_if($array, [cv::class, "nz"]);}
  static final function any_n(?array $array): bool { return self::any_if($array, [cv::class, "n"]);}
  static final function any_nn(?array $array): bool { return self::any_if($array, [cv::class, "nn"]);}
  static final function any_t(?array $array): bool { return self::any_if($array, [cv::class, "t"]);}
  static final function any_f(?array $array): bool { return self::any_if($array, [cv::class, "f"]);}
  static final function any_pt(?array $array): bool { return self::any_if($array, [cv::class, "pt"]);}
  static final function any_pf(?array $array): bool { return self::any_if($array, [cv::class, "pf"]);}
  static final function any_equals(?array $array, $value): bool { return self::any_if($array, cv::equals($value)); }
  static final function any_not_equals(?array $array, $value): bool { return self::any_if($array, cv::not_equals($value)); }
  static final function any_same(?array $array, $value): bool { return self::any_if($array, cv::same($value)); }
  static final function any_not_same(?array $array, $value): bool { return self::any_if($array, cv::not_same($value)); }

  #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  
  static final function filter_if(?array $array, callable $cond): ?array {
    if ($array === null) return null;
    $filtered = [];
    $index = 0;
    foreach ($array as $key => $value) {
      if (!$cond($value)) {
        if ($key === $index) {
          $index++;
          $filtered[] = $value;
        } else {
          $filtered[$key] = $value;
        }
      } elseif ($key === $index) {
        $index++;
      }
    }
    return $filtered;
  }

  static final function filter_z(?array $array): ?array { return self::filter_if($array, [cv::class, "z"]);}
  static final function filter_nz(?array $array): ?array { return self::filter_if($array, [cv::class, "nz"]);}
  static final function filter_n(?array $array): ?array { return self::filter_if($array, [cv::class, "n"]);}
  static final function filter_nn(?array $array): ?array { return self::filter_if($array, [cv::class, "nn"]);}
  static final function filter_t(?array $array): ?array { return self::filter_if($array, [cv::class, "t"]);}
  static final function filter_f(?array $array): ?array { return self::filter_if($array, [cv::class, "f"]);}
  static final function filter_pt(?array $array): ?array { return self::filter_if($array, [cv::class, "pt"]);}
  static final function filter_pf(?array $array): ?array { return self::filter_if($array, [cv::class, "pf"]);}
  static final function filter_equals(?array $array, $value): ?array { return self::filter_if($array, cv::equals($value)); }
  static final function filter_not_equals(?array $array, $value): ?array { return self::filter_if($array, cv::not_equals($value)); }
  static final function filter_same(?array $array, $value): ?array { return self::filter_if($array, cv::same($value)); }
  static final function filter_not_same(?array $array, $value): ?array { return self::filter_if($array, cv::not_same($value)); }

  #############################################################################

  static final function sorted(?array $array, int $flags=SORT_REGULAR, bool $assoc=false): ?array {
    if ($array === null) return null;
    if ($assoc) asort($array, $flags);
    else sort($array, $flags);
    return $array;
  }

  static final function ksorted(?array $array, int $flags=SORT_REGULAR): ?array {
    if ($array === null) return null;
    ksort($array, $flags);
    return $array;
  }

  /**
   * retourner une fonction permettant de trier un tableau sur les clés
   * spécifiées.
   *
   * - les clés ayant le préfixe '+' ou le suffixe '|asc' indiquent un tri
   * ascendant
   * - les clés ayant le préfixe '-' ou le suffixe '|desc' indiquent un tri
   * descendant
   * - sinon, par défaut, le tri est ascendant
   */
  static final function compare(array $keys): callable {
    return function ($a, $b) use ($keys) {
      foreach ($keys as $key) {
        if (str::del_prefix($key, "+")) $w = 1;
        elseif (str::del_prefix($key, "-")) $w = -1;
        elseif (str::del_suffix($key, "|asc")) $w = 1;
        elseif (str::del_suffix($key, "|desc")) $w = -1;
        else $w = 1;
        if ($c = $w * cv::compare(cl::get($a, $key), cl::get($b, $key))) {
          return $c;
        }
      }
      return 0;
    };
  }

  static final function usorted(?array $array, array $keys, bool $assoc=false): ?array {
    if ($array === null) return null;
    if ($assoc) uasort($array, self::compare($keys));
    else usort($array, self::compare($keys));
    return $array;
  }
}