Random\Engine::generate

(PHP 8 >= 8.2.0)

Random\Engine::generate — Génère de l'aléatoire

Description

public Random\Engine::generate(): string

Retourne de l'aléatoire et fait avancer l'état de l'algorithme d'un pas.

L'aléatoire est représenté par une chaîne binaire contenant des octets aléatoires. Cette représentation permet d'interpréter sans ambiguïté les bits aléatoires générés par l'algorithme, par exemple pour tenir compte des différentes tailles de sortie utilisées par les différents algorithmes.

Les algorithmes qui opèrent nativement sur des valeurs entières doivent retourner l'entier avec les octets dans l'ordre petit-boutiste (little-endian), par exemple en utilisant la fonction pack() avec le code de format P. L'interface de haut niveau fournie par le Random\Randomizer interprétera les octets aléatoires retournés comme des entiers non signés petit-boutiste (little-endian) si une représentation numérique est nécessaire.

Il est fortement recommandé que chaque bit de la chaîne retournée soit sélectionné de manière uniforme et indépendante, car certaines applications nécessitent de l'aléatoire basé au niveau des bits pour fonctionner correctement. Par exemple, les générateurs congruentiels linéaires génèrent souvent de l'aléatoire de moindre qualité pour les bits de poids faible de la valeur entière retournée et ne conviendraient donc pas aux applications qui requièrent de l'aléatoire au niveau des bits.

Liste de paramètres

Cette fonction ne contient aucun paramètre.

Valeurs de retour

Une chaîne non vide contenant des octets aléatoires.

Note: Le Random\Randomizer utilise en interne des entiers non signés de 64 bits. Si la chaîne retournée contient plus de 64 bits (8 octets) d'aléatoire, les octets excédentaires seront ignorés. D'autres applications peuvent être en mesure de traiter plus de 64 bits à la fois.

Erreurs / Exceptions

Si la génération d'aléatoire échoue, une Random\RandomException doit être émise. Tout autre Exception émise pendant la génération devrait être attrapée et enveloppée dans une Random\RandomException.
Si la chaîne retournée est vide, une Random\BrokenRandomEngineError sera émise par le Random\Randomizer.
Si l'algorithme implémenté est fortement biaisé, une Random\BrokenRandomEngineError peut être émise par le Random\Randomizer pour éviter les boucles infinies si un échantillonnage par rejet est nécessaire pour retourner des résultats non biaisés.

Exemples

Exemple #1 Exemple de Random\Engine::generate()

<?php
/**
 * Implémente un Générateur Congruentiel Linéaire de module 65536,
 * un multiplicateur de 61 et un incrément de 17, retournant un entier de 8 bits.
 *
 * Note: Ce moteur ne peut être utilisé qu'à des fins de démonstration..
 *       Les générateurs congruentiels linéaires génèrent généralement
 *       de l'aléatoire de faible qualité et cette implémentation spécifique a
 *       une période très courte de 16 bits qui n'est pas adaptée à
 *       presque tous les cas d'utilisation dans le monde réel.
 */
final class LinearCongruentialGenerator implements \Random\Engine
{
    private int $state;

    public function __construct(?int $seed = null)
    {
        if ($seed === null) {
            $seed = random_int(0, 0xffff);
        }

        $this->state = $seed & 0xffff;
    }

    public function generate(): string
    {
        $this->state = (61 * $this->state + 17) & 0xffff;

        return pack('C', $this->state >> 8);
    }
}

$r = new \Random\Randomizer(
    new LinearCongruentialGenerator(seed: 1)
);

echo "Nombre chanceux: ", $r->getInt(0, 99), "\n";
?>

L'exemple ci-dessus va afficher :

Nombre chanceux: 4