<?php
namespace nur\m;

use Iterator;

/**
 * Interface IRowIterator: un itérateur pour lire le résultat d'une requête
 */
interface IRowIterator extends Iterator {
  /** @return true si cet itérateur a déjà été parcouru jusqu'à la fin */
  function isClosed(): bool;

  /** retourner toute les lignes du résultat sous forme de tableau */
  function all(): array;

  /**
   * retourner une liste de valeurs [$value] tel que $value = $row[$name] pour
   * chaque ligne de résultat de {@link all()}
   *
   * NB: si $name===null, prendre le premier champ de $row
   */
  function allVals(?string $name=null): array;

  /**
   * retourner la première ligne du résultat, ou $default si aucun élément
   * n'est trouvé.
   */
  function first($default=null);

  /**
   * retourner la valeur $row[$name] où $row est la valeur retournée par
   * {@link first()}. Retourner $default si {@link first()} ne retourne
   * pas de résultat
   *
   * NB: si $name===null, prendre le premier champ de $row
   */
  function firstVal(?string $name=null, $default=null);

  /**
   * méthode de convenance pour récupérer le nombre de ligne affectées par un
   * résultat. équivalent à first()["num_rows"]
   */
  function numRows(): int;

  /**
   * méthode de convenance pour récupérer l'identifiant de la dernière ligne
   * insérée. équivalent à first()["insert_id"]
   */
  function insertId();

  /**
   * retourner la première ligne du résultat, ou $default si aucun élément
   * n'est trouvé.
   *
   * si $rewind est true, appeler rewind() à la fin pour s'assurer que
   * l'itérateur est fermé correctement.
   *
   * retourner un tableau [$value, $have_next, $it_nexts]
   * - $have_next vaut true s'il y a encore des données qui suivent
   * - si $rewind==false, $it_nexts est un itérateur qui permet d'accéder aux
   *   données suivantes
   */
  function one($default=null, ?bool $rewind=null): array;

  function peek($default=null, bool $rewind=false): array;
}
