Random\Engine::generate

(PHP 8 >= 8.2.0)

Random\Engine::generate — Генерирует случайную последовательность

Описание

public Random\Engine::generate(): string

Метод возвращает случайную последовательность и продвигает состояние алгоритма на один шаг.

Случайная последовательность возвращается в виде строки, которая состоит из случайных байтов в фиксированном порядке — от младшего к старшему. В фиксированном строковом представлении случайные биты интерпретируются однозначно, при этом строка, в отличие от других скалярных типов данных, вмещает случайные последовательности произвольной длины, какого бы размера вывод ни сгенерировал конкретный алгоритм.

В пользовательских реализациях метода потребуется вернуть двоичное строковое представление числа с порядком байтов от младшего к старшему, например путём вызова функции pack() с кодом формата P, если случайная последовательность генерируется через алгоритм, который возвращает целочисленное значение. Класс Random\Randomizer предоставляет высокоуровневый интерфейс, который интерпретирует возвращаемые случайные байты как беззнаковые целочисленные значения с порядком байтов от младшего к старшему, когда требуется числовое представление.

Из метода стараются возвращать строку, каждый бит которой выбирался равномерно и независимо, поскольку отдельным приложениям для корректной работы требуется случайность на уровне битов. Линейные конгруэнтные генераторы часто возвращают случайную последовательность меньшего качества в младших битах целочисленного значения и поэтому оказываются неприемлемыми для приложений, которым требуется случайность на уровне битов.

Список параметров

Сигнатура функции не содержит параметров.

Возвращаемые значения

Метод возвращает непустую строку случайных байтов.

Замечание: Класс Random\Randomizer внутренне работает с беззнаковыми 64-разрядными целочисленными значениями, поэтому проигнорирует лишние байты, если метод вернёт строку со случайной последовательностью, размер которой превышает 64 бита, или 8 байтов, но другие приложения умеют обрабатывать случайные последовательности длиннее 64 битов.

Ошибки

При ошибке генерации случайной последовательности из метода выбрасывают исключение Random\RandomException. Остальные исключения семейства Exception, которые метод выбрасывает при генерации, перехватывают и оборачивают исключением Random\RandomException.
При возврате пустой строки объект Random\Randomizer выбросит ошибку Random\BrokenRandomEngineError.
При избыточном статистическом смещении реализованного алгоритма объект Random\Randomizer выбрасывает ошибку Random\BrokenRandomEngineError, чтобы предотвратить бесконечный цикл, когда алгоритм выборки с отклонением требует возврата несмещённых результатов.

Примеры

Пример #1 Пример генерации случайной последовательности методом Random\Engine::generate()

<?php

/**
 * Класс реализует метод генерации случайных последовательностей
 * через линейный конгруэнтный генератор, который возвращает
 * двоичное строковое представление 8-битного целочисленного значения.
 * Параметры генератора — модуль: 65536, множитель: 61, инкремент: 17.
 *
 * Примечание: Движок реализовали только в целях демонстрации.
 *       Линейные конгруэнтные генераторы часто выдают низкокачественную случайную
 *       последовательность, а конкретная реализация примера ограничивается
 *       недопустимо коротким 16-битным периодом, который нельзя применять
 *       в производственном окружении.
 */
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 "Счастливое число: ", $r->getInt(0, 99), "\n";

Результат выполнения приведённого примера:

Счастливое число: 4