nur-sery/src/cv.php

<?php
namespace nur\sery;

/**
 * Class cv: gestion de valeurs scalaires
 */
class cv {
  /** tester si $value vaut null ou false */
  static final function z($value): bool {
    return $value === false || $value === null;
  }

  /** tester si $value ne vaut ni null ni false */
  static final function nz($value): bool {
    return $value !== false && $value !== null;
  }

  /** tester si $value vaut null */
  static final function n($value): bool {
    return $value === null;
  }

  /** tester si $value n'est pas null */
  static final function nn($value): bool {
    return $value !== null;
  }

  /** tester si $value est vraie (y compris la chaine "0") */
  static final function t($value): bool {
    return $value || $value === "0";
  }
  
  /** tester si $value est fausse (cela n'inclue pas la chaine "0") */
  static final function f($value): bool {
    return !$value && $value !== "0";
  }

  /** tester si $value est vraie selon les règles de PHP. */
  static final function pt($value): bool {
    return boolval($value);
  }

  /** tester si $value est fausse selon les règles de PHP. */
  static final function pf($value): bool {
    return !$value;
  }

  /**
   * contruire une fonction qui retourne vrai si on lui passe en argument une
   * valeur égale à $value
   */
  static final function equals($value): callable {
    return function ($arg) use($value) { return $arg == $value; };
  }

  /**
   * contruire une fonction qui retourne vrai si on lui passe en argument une
   * valeur qui n'est pas égale à $value
   */
  static final function not_equals($value): callable {
    return function ($arg) use($value) { return $arg != $value; };
  }

  /**
   * contruire une fonction qui retourne vrai si on lui passe en argument une
   * valeur strictement égale à $value
   */
  static final function same($value): callable {
    return function ($arg) use($value) { return $arg === $value; };
  }

  /**
   * contruire une fonction qui retourne vrai si on lui passe en argument une
   * valeur qui n'est pas strictement égale à $value
   */
  static final function not_same($value): callable {
    return function ($arg) use($value) { return $arg !== $value; };
  }

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

  /** échanger les deux valeurs */
  static final function swap(&$a, &$b): void {
    $tmp = $a;
    $a = $b;
    $b = $tmp;
  }

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

  /** mettre à jour $dest avec $value si $cond($value) est vrai */
  static final function set_if(&$dest, $value, callable $cond) {
    if ($cond($value)) $dest = $value;
    return $dest;
  }
  static final function set_z(&$dest, $value) { return self::set_if($dest, $value, [self::class, "z"]);}
  static final function set_nz(&$dest, $value) { return self::set_if($dest, $value, [self::class, "nz"]);}
  static final function set_n(&$dest, $value) { return self::set_if($dest, $value, [self::class, "n"]);}
  static final function set_nn(&$dest, $value) { return self::set_if($dest, $value, [self::class, "nn"]);}
  static final function set_t(&$dest, $value) { return self::set_if($dest, $value, [self::class, "t"]);}
  static final function set_f(&$dest, $value) { return self::set_if($dest, $value, [self::class, "f"]);}
  static final function set_pt(&$dest, $value) { return self::set_if($dest, $value, [self::class, "pt"]);}
  static final function set_pf(&$dest, $value) { return self::set_if($dest, $value, [self::class, "pf"]);}

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

  /** mettre à jour $dest avec $value si $cond($dest) est vrai */
  static final function update_if(&$dest, $value, callable $cond) {
    if ($cond($dest)) $dest = $value;
    return $dest;
  }
  static final function update_z(&$dest, $value) { return self::update_if($dest, $value, [self::class, "z"]);}
  static final function update_nz(&$dest, $value) { return self::update_if($dest, $value, [self::class, "nz"]);}
  static final function update_n(&$dest, $value) { return self::update_if($dest, $value, [self::class, "n"]);}
  static final function update_nn(&$dest, $value) { return self::update_if($dest, $value, [self::class, "nn"]);}
  static final function update_t(&$dest, $value) { return self::update_if($dest, $value, [self::class, "t"]);}
  static final function update_f(&$dest, $value) { return self::update_if($dest, $value, [self::class, "f"]);}
  static final function update_pt(&$dest, $value) { return self::update_if($dest, $value, [self::class, "pt"]);}
  static final function update_pf(&$dest, $value) { return self::update_if($dest, $value, [self::class, "pf"]);}

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

  /** retourner $value si elle est vraie (y compris la chaine "0"), false sinon */
  static final function vf($value) {
    return $value || $value === "0"? $value: false;
  }

  /** retourner $value si elle est vraie (y compris la chaine "0"), null sinon */
  static final function vn($value) {
    return $value || $value === "0"? $value: null;
  }

  /**
   * retourner la première valeur vraie (y compris la chaine "0")
   *
   * si toutes les valeurs sont fausses, retourner la dernière valeur de la
   * liste, ou null si la liste est vide
   */
  static final function firstv(...$values) {
    $value = null;
    foreach ($values as $value) {
      if ($value || $value === "0") return $value;
    }
    return $value;
  }

  /**
   * retourner la première valeur vraie selon les règles de PHP.
   *
   * si toutes les valeurs sont fausses, retourner la dernière valeur de la
   * liste, ou null si la liste est vide
   */
  static final function firstpv(...$values) {
    $value = null;
    foreach ($values as $value) {
      if ($value) return $value;
    }
    return $value;
  }

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

  /** vérifier si $value est un booléen, sinon retourner null */
  static final function check_bool($value): ?bool {
    return is_bool($value)? $value: null;
  }

  /** vérifier si $value est un integer, sinon retourner null */
  static final function check_int($value): ?int {
    return is_int($value)? $value: null;
  }

  /** vérifier si $value est un string, sinon retourner null */
  static final function check_string($value): ?string {
    return is_string($value)? $value: null;
  }

  /** vérifier si $value est un array, sinon retourner null */
  static final function check_array($value): ?array {
    return is_array($value)? $value: null;
  }

  /**
   * retourner [$index, $key] initialisés chacun en fonction du type de $value
   * (index est numérique, key est une chaine)
   *
   * lever une exception si $value n'est d'aucun de ces types
   */
  static final function check_key($value, ?string $prefix=null, bool $throw_exception=true): array {
    $index = is_int($value)? $value : null;
    $key = is_string($value)? $value : null;
    if ($index === null && $key === null && $throw_exception) {
      throw ValueException::invalid_kind($value, "key", $prefix);
    } else {
      return [$index, $key];
    }
  }

  /**
   * retourner [$bool, $string, $array] initialisés chacun en fonction du type
   * de $value.
   *
   * @throws ValueException si $value n'est d'aucun de ces types
   */
  static final function check_bsa($value, ?string $prefix=null, bool $throw_exception=true): array {
    $bool = is_bool($value)? $value : null;
    $string = is_string($value)? $value : null;
    $array = is_array($value)? $value : null;
    if ($bool === null && $string === null && $array === null && $throw_exception) {
      throw ValueException::invalid_kind($value, "value", $prefix);
    } else {
      return [$bool, $string, $array];
    }
  }

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

  /** retourner -1, 0 ou 1 en fonction de l'ordre relatif entre $a et $b */
  static final function compare($a, $b): int {
    if ($a === $b) return 0;
    if ($a < $b) return -1;
    if ($a > $b) return 1;
    return 0;
  }
}