Интерфейс RandomGenerator
- Все известные подинтерфейсы:
-
RandomGenerator.ArbitrarilyJumpableGenerator,RandomGenerator.JumpableGenerator,RandomGenerator.LeapableGenerator,RandomGenerator.SplittableGenerator,RandomGenerator.StreamableGenerator
- Все известные реализующие классы:
-
Random,SecureRandom,SplittableRandom,ThreadLocalRandom
public interface RandomGenerator
RandomGenerator предназначен для обеспечения общего протокола для объектов, генерирующих случайные или (в большинстве случаев) псевдослучайные последовательности чисел (или булевых значений). Такую последовательность можно получить, либо многократно вызывая метод, возвращающий одно псевдослучайное значение, либо вызывая метод, возвращающий поток псевдослучайных значений. В идеале, учитывая неявный или явный диапазон значений, каждое значение выбирается независимо и равномерно из этого диапазона. На практике, возможно, придётся довольствоваться некоторым приближением независимости и равномерности.
В случае int, long, и boolean значений, если нет явного указания диапазона, то диапазон включает все возможные значения типа. В случае float и double значений, сначала всегда выбирается значение равномерно из набора из 2w значений между 0.0 (включительно) и 1.0 (исключительно), где w — Float.PRECISION для float значений и Double.PRECISION для double значений, так что соседние значения отличаются на 2−w (обратите внимание, что этот набор является подмножеством набора всех представимых значений с плавающей точкой между 0.0 (включительно) и 1.0 (исключительно)); затем, если был указан явный диапазон, выбранное число вычисляется масштабируется и сдвигается таким образом, чтобы казаться приблизительно равномерно выбранным из этого явного диапазона.
Каждый метод, возвращающий поток, генерирует поток значений, каждое из которых выбирается аналогично методу, возвращающему одно псевдослучайное значение. Например, если r реализует RandomGenerator, то вызов метода r.ints(100) возвращает поток из 100 int значений. Эти значения не обязательно являются точно такими же, которые были бы возвращены, если бы r.nextInt() был вызван 100 раз; гарантируется только, что каждое значение в потоке выбирается аналогичным псевдослучайным образом из того же диапазона.
Каждый объект, реализующий интерфейс RandomGenerator с помощью псевдослучайного алгоритма, предполагается, содержит конечное количество состояния. Использование такого объекта для генерации псевдослучайного значения изменяет его состояние, вычисляя новое состояние как функцию текущего состояния, без ссылки на какую-либо информацию, кроме текущего состояния. Количество различных возможных состояний такого объекта называется его периодом. (Некоторые реализации интерфейса RandomGenerator могут быть истинно случайными, а не псевдослучайными, например, опираясь на статистическое поведение физического объекта для получения выбранных значений. Такие реализации не имеют фиксированного периода.)
Как правило, объекты, реализующие интерфейс RandomGenerator, не должны быть потокобезопасными. Рекомендуется, чтобы многопоточные приложения использовали либо ThreadLocalRandom, или (предпочтительно) генераторы псевдослучайных чисел, реализующие интерфейсы RandomGenerator.SplittableGenerator или RandomGenerator.JumpableGenerator.
Объекты, реализующие RandomGenerator, обычно не являются криптографически безопасными. Вместо этого следует использовать SecureRandom для получения криптографически безопасного генератора псевдослучайных чисел для использования в приложениях, чувствительных к безопасности. Обратите внимание, однако, что SecureRandom реализует интерфейс RandomGenerator, поэтому экземпляры SecureRandom могут использоваться взаимозаменяемо с другими типами генераторов псевдослучайных чисел в приложениях, которым не требуется безопасный генератор.
Если не указано иное, использование null в качестве аргумента любого метода приведет к NullPointerException.
- С:
- 17
Краткое описание вложенных классов
| Modifier and Type | Interface | Description |
|---|---|---|
static interface |
RandomGenerator.ArbitrarilyJumpableGenerator |
Данный интерфейс предназначен для предоставления общего протокола для объектов, генерирующих последовательности псевдослучайных значений и способных легко перемещаться вперёд на произвольное расстояние к отдалённой точке в цикле состояния. |
static interface |
RandomGenerator.JumpableGenerator |
Данный интерфейс предназначен для предоставления общего протокола для объектов, генерирующих псевдослучайные значения и способных легко перемещаться вперёд на умеренное расстояние (например, 264) к отдалённой точке в цикле состояния. |
static interface |
RandomGenerator.LeapableGenerator |
Данный интерфейс предназначен для предоставления общего протокола для объектов, генерирующих последовательности псевдослучайных значений и способных легко не только перемещаться, но и перепрыгивать вперёд на большое расстояние (например, 2128) к очень отдалённой точке в цикле состояния. |
static interface |
RandomGenerator.SplittableGenerator |
Данный интерфейс предназначен для предоставления общего протокола для объектов, генерирующих последовательности псевдослучайных значений, и способных разделяться на два объекта (исходный и новый), каждый из которых подчиняется этому же протоколу (и, следовательно, может быть рекурсивно разделён бесконечно). |
static interface |
RandomGenerator.StreamableGenerator |
Интерфейс RandomGenerator.StreamableGenerator расширяет интерфейс RandomGenerator, предоставляя методы, возвращающие потоки объектов RandomGenerator. |
Краткое описание методов
| Modifier and Type | Метод | Описание |
|---|---|---|
default DoubleStream |
doubles() |
Возвращает эффективно неограниченный поток псевдослучайных значений double. |
default DoubleStream |
doubles |
Возвращает эффективно неограниченный поток псевдослучайных значений double, где каждое значение находится в диапазоне от указанного начала (включительно) до указанного конца (исключительно). |
default DoubleStream |
doubles |
Возвращает поток, генерирующий заданное количество streamSize псевдослучайных значений double. |
default DoubleStream |
doubles |
Возвращает поток, генерирующий заданное количество streamSize псевдослучайных значений double, где каждое значение находится в диапазоне от указанного начала (включительно) до указанного конца (исключительно). |
static RandomGenerator |
getDefault() |
Возвращает RandomGenerator, удовлетворяющий минимальному требованию наличия алгоритма, чьи биты состояния больше или равны 64. |
Подробное описание методов
of
static RandomGenerator of(String name)
- Параметры:
-
name- Название алгоритма генератора случайных чисел алгоритма - Возвращает:
- Экземпляр
RandomGenerator - Исключение:
-
NullPointerException- если имя равно null -
IllegalArgumentException- если алгоритм с заданным именем не найден
getDefault
static RandomGenerator getDefault()
RandomGenerator, удовлетворяющий минимальному требованию наличия алгоритма, биты состояния которого больше или равны 64.- Требования к реализации:
- Поскольку алгоритмы будут совершенствоваться со временем, нет гарантии, что этот метод будет возвращать тот же алгоритм со временем.
По умолчанию используется L32X64MixRandom.
- Возвращает:
- a
RandomGenerator
isDeprecated
default boolean isDeprecated()
- Требования к реализации:
- По умолчанию проверяется аннотация @Deprecated.
- Примечание к реализации:
- Алгоритмы генераторов случайных чисел эволюционируют со временем; будут введены новые алгоритмы, а старые утратят свою актуальность. Если старый алгоритм признан непригодным для дальнейшего использования, он помечается как устаревший, чтобы указать, что его могут удалить в какой-то момент в будущем.
- Возвращает:
- true, если реализация RandomGenerator (алгоритм) помечена как устаревшая
doubles
default DoubleStream doubles()
double значений.- Требования к реализации:
- По умолчанию генерируется последовательный поток, который многократно вызывает
nextDouble(). - Примечание к реализации:
- Разрешается реализовать этот метод способом, эквивалентным
doubles(Long.MAX_VALUE). - Возвращает:
- поток псевдослучайных
doubleзначений
doubles
default DoubleStream doubles(double randomNumberOrigin, double randomNumberBound)
double значений, где каждое значение находится между заданным началом (включительно) и заданной границей (исключительно).- Требования к реализации:
- По умолчанию генерируется последовательный поток, который многократно вызывает
nextDouble(randomNumberOrigin, randomNumberBound). - Примечание к реализации:
- Разрешается реализовать этот метод способом, эквивалентным
doubles(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound). - Параметры:
-
randomNumberOrigin- наименьшее значение, которое может быть сгенерировано -
randomNumberBound- верхняя граница (исключая) для каждого сгенерированного значения - Возвращает:
- поток псевдослучайных
doubleзначений, каждое из которых находится между заданным началом (включительно) и заданной границей (исключительно) - Исключение:
-
IllegalArgumentException- еслиrandomNumberOriginне является конечным, илиrandomNumberBoundне является конечным, илиrandomNumberOriginбольше или равноrandomNumberBound
doubles
default DoubleStream doubles(long streamSize)
streamSize псевдослучайных double значений.- Требования к реализации:
- По умолчанию генерируется последовательный поток, который многократно вызывает
nextDouble(). - Параметры:
-
streamSize- количество значений для генерации - Возвращает:
- поток псевдослучайных
doubleзначений - Исключение:
-
IllegalArgumentException- еслиstreamSizeменьше нуля
doubles
default DoubleStream doubles(long streamSize, double randomNumberOrigin, double randomNumberBound)
streamSize псевдослучайных double значений, где каждое значение находится между заданным началом (включительно) и заданной границей (исключительно).- Требования к реализации:
- По умолчанию генерируется последовательный поток, который многократно вызывает
nextDouble(randomNumberOrigin, randomNumberBound). - Параметры:
-
streamSize- количество значений для генерации -
randomNumberOrigin- наименьшее значение, которое может быть сгенерировано -
randomNumberBound- верхняя граница (исключая) для каждого сгенерированного значения - Возвращает:
- поток псевдослучайных
doubleзначений, каждое из которых находится между заданным началом (включительно) и заданной границей (исключительно) - Исключение:
-
IllegalArgumentException- еслиstreamSizeменьше нуля, илиrandomNumberOriginне является конечным, илиrandomNumberBoundне является конечным, илиrandomNumberOriginбольше или равноrandomNumberBound
ints
default IntStream ints()
int значений.- Требования к реализации:
- По умолчанию генерируется последовательный поток, который многократно вызывает
nextInt(). - Примечание к реализации:
- Разрешается реализовать этот метод способом, эквивалентным
ints(Long.MAX_VALUE). - Возвращает:
- поток псевдослучайных
intзначений
ints
default IntStream ints(int randomNumberOrigin, int randomNumberBound)
int значений, где каждое значение находится между заданным началом (включительно) и заданной границей (исключительно).- Требования к реализации:
- По умолчанию генерируется последовательный поток, который многократно вызывает
nextInt(randomNumberOrigin, randomNumberBound). - Примечание к реализации:
- Разрешается реализовать этот метод способом, эквивалентным
ints(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound). - Параметры:
-
randomNumberOrigin- наименьшее значение, которое может быть сгенерировано -
randomNumberBound- верхняя граница (исключая) для каждого сгенерированного значения - Возвращает:
- поток псевдослучайных
intзначений, каждое из которых находится между заданным началом (включительно) и заданной границей (исключительно) - Исключение:
-
IllegalArgumentException- еслиrandomNumberOriginбольше или равноrandomNumberBound
ints
default IntStream ints(long streamSize)
streamSize псевдослучайных int значений.- Требования к реализации:
- По умолчанию генерируется последовательный поток, который многократно вызывает
nextInt(). - Параметры:
-
streamSize- количество значений для генерации - Возвращает:
- поток псевдослучайных
intзначений - Исключение:
-
IllegalArgumentException- еслиstreamSizeменьше нуля
ints
default IntStream ints(long streamSize, int randomNumberOrigin, int randomNumberBound)
streamSize псевдослучайных int значений, где каждое значение находится между заданным началом (включительно) и заданной границей (исключительно).- Требования к реализации:
- По умолчанию генерируется последовательный поток, который многократно вызывает
nextInt(randomNumberOrigin, randomNumberBound). - Параметры:
-
streamSize- количество значений для генерации -
randomNumberOrigin- наименьшее значение, которое может быть сгенерировано -
randomNumberBound- верхняя граница (исключая) для каждого сгенерированного значения - Возвращает:
- поток псевдослучайных
intзначений, каждое из которых находится между заданным началом (включительно) и заданной границей (исключительно) - Исключение:
-
IllegalArgumentException- еслиstreamSizeменьше нуля, илиrandomNumberOriginбольше или равноrandomNumberBound
longs
default LongStream longs()
long значений.- Требования к реализации:
- По умолчанию генерируется последовательный поток, который многократно вызывает
nextLong(). - Примечание к реализации:
- Разрешается реализовать этот метод способом, эквивалентным
longs(Long.MAX_VALUE). - Возвращает:
- поток псевдослучайных
longзначений
longs
default LongStream longs(long randomNumberOrigin, long randomNumberBound)
long значений, где каждое значение находится между указанным началом (включительно) и указанным пределом (исключительно).- Требования к реализации:
- Базовая реализация генерирует последовательный поток, многократно вызывая
nextLong(randomNumberOrigin, randomNumberBound). - Примечание по реализации:
- Разрешается реализовать этот метод аналогично
longs(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound). - Параметры:
-
randomNumberOrigin- наименьшее значение, которое может быть сгенерировано -
randomNumberBound- верхняя граница (исключительно) для каждого сгенерированного значения - Возвращает:
- поток псевдослучайных
longзначений, каждое из которых находится между указанным началом (включительно) и указанным пределом (исключительно) - Исключение:
-
IllegalArgumentException- еслиrandomNumberOriginбольше или равноrandomNumberBound
longs
default LongStream longs(long streamSize)
streamSize псевдослучайных long значений.- Требования к реализации:
- Базовая реализация генерирует последовательный поток, многократно вызывая
nextLong(). - Параметры:
-
streamSize- количество значений для генерации - Возвращает:
- поток псевдослучайных
longзначений - Исключение:
-
IllegalArgumentException- еслиstreamSizeменьше нуля
longs
default LongStream longs(long streamSize, long randomNumberOrigin, long randomNumberBound)
streamSize псевдослучайных long значений, где каждое значение находится между указанным началом (включительно) и указанным пределом (исключительно).- Требования к реализации:
- Базовая реализация генерирует последовательный поток, многократно вызывая
nextLong(randomNumberOrigin, randomNumberBound). - Параметры:
-
streamSize- количество значений для генерации -
randomNumberOrigin- наименьшее значение, которое может быть сгенерировано -
randomNumberBound- верхняя граница (исключительно) для каждого сгенерированного значения - Возвращает:
- поток псевдослучайных
longзначений, каждое из которых находится между указанным началом (включительно) и указанным пределом (исключительно) - Исключение:
-
IllegalArgumentException- еслиstreamSizeменьше нуля илиrandomNumberOriginбольше или равноrandomNumberBound
nextBoolean
default boolean nextBoolean()
boolean значение. Базовая реализация проверяет старший бит (знаковый бит) значения, полученного из nextInt(), так как в некоторых алгоритмах генерации псевдослучайных чисел старшие биты обладают лучшими статистическими свойствами, чем младшие.
- Требования к реализации:
- Базовая реализация генерирует результат на основе знакового бита числа, сгенерированного с помощью
nextInt(). - Возвращает:
- псевдослучайное
booleanзначение
nextBytes
default void nextBytes(byte[] bytes)
- Требования к реализации:
- Базовая реализация генерирует результаты из многократных вызовов
nextLong(). - Примечание по реализации:
- Алгоритм, используемый для заполнения массива байтов;
void nextBytes(byte[] bytes) { int i = 0; int len = bytes.length; for (int words = len >> 3; words--> 0; ) { long rnd = nextLong(); for (int n = 8; n--> 0; rnd >>>= Byte.SIZE) bytes[i++] = (byte)rnd; } if (i < len) for (long rnd = nextLong(); i < len; rnd >>>= Byte.SIZE) bytes[i++] = (byte)rnd; } - Параметры:
-
bytes- массив байтов для заполнения псевдослучайными байтами - Исключение:
-
NullPointerException- если bytes равно null
nextFloat
default float nextFloat()
float значение между нулём (включительно) и единицей (исключительно).- Требования к реализации:
- Базовая реализация использует
Float.PRECISIONстаршие биты из вызоваnextInt(). - Возвращает:
- псевдослучайное
floatзначение между нулём (включительно) и единицей (исключительно)
nextFloat
default float nextFloat(float bound)
float значение между нулём (включительно) и указанным пределом (исключительно).- Требования к реализации:
- Базовая реализация проверяет, что
boundявляется положительным конечным float. Затем вызываетnextFloat(), масштабируя результат так, чтобы конечный результат находился между0.0f(включительно) иbound(исключительно). - Параметры:
-
bound- верхняя граница (исключительно) для возвращаемого значения. Должно быть положительным и конечным - Возвращает:
- псевдослучайно выбранное
floatзначение между нулём (включительно) и пределом (исключительно) - Исключение:
-
IllegalArgumentException- еслиboundне является одновременно положительным и конечным
nextFloat
default float nextFloat(float origin, float bound)
float значение между указанным началом (включительно) и указанным пределом (исключительно).- Требования к реализации:
- Базовая реализация проверяет, что
originиboundявляются допустимыми, затем вызываетnextFloat()масштабирования и трансляции результата для соответствия диапазону междуoriginиbound(исключительно). - Параметры:
-
origin- наименьшее значение, которое может быть возвращено -
bound- верхняя граница (исключительно) - Возвращает:
- псевдослучайно выбранное
floatзначение между началом (включительно) и пределом (исключительно) - Исключение:
-
IllegalArgumentException- еслиoriginне является конечным, илиboundне является конечным, илиoriginбольше или равноbound
nextDouble
default double nextDouble()
double значение между нулём (включительно) и единицей (исключительно).- Требования к реализации:
- Базовая реализация использует
Double.PRECISIONстаршие биты из вызоваnextLong(). - Возвращает:
- псевдослучайное
doubleзначение между нулём (включительно) и единицей (исключительно)
nextDouble
default double nextDouble(double bound)
double значение между нулём (включительно) и указанным пределом (исключительно).- Требования к реализации:
- Базовая реализация проверяет, что
boundявляется положительным конечным double. Затем вызываетnextDouble(), масштабируя результат так, чтобы конечный результат находился между0.0(включительно) иbound(исключительно). - Параметры:
-
bound- верхняя граница (исключительно) для возвращаемого значения. Должно быть положительным и конечным - Возвращает:
- псевдослучайно выбранное
doubleзначение между нулём (включительно) и пределом (исключительно) - Исключение:
-
IllegalArgumentException- еслиboundне является одновременно положительным и конечным
nextDouble
default double nextDouble(double origin, double bound)
double значение между указанным началом (включительно) и указанным пределом (исключительно).- Требования к реализации:
- Базовая реализация проверяет, что
originиboundявляются допустимыми, затем вызываетnextDouble()масштабирования и трансляции результата для соответствия диапазону междуoriginиbound(исключительно). - Параметры:
-
origin- наименьшее значение, которое может быть возвращено -
bound- верхняя граница (исключительно) для возвращаемого значения - Возвращает:
- псевдослучайно выбранное
doubleзначение между началом (включительно) и пределом (исключительно) - Исключение:
-
IllegalArgumentException- еслиoriginне является конечным, илиboundне является конечным, илиoriginбольше или равноbound
nextInt
default int nextInt()
int значение.- Требования к реализации:
- Базовая реализация использует 32 старших бита из вызова
nextLong(). - Возвращает:
- псевдослучайно выбранное
intзначение
nextInt
default int nextInt(int bound)
- Требования к реализации:
- Стандартная реализация проверяет, что
boundявляется положительнымint. Затем вызываетnextInt(), ограничивая результат значением больше или равным нулю и меньшеbound. Еслиboundявляется степенью двойки, то ограничение выполняется простой операцией побитового И. В противном случае результат пересчитывается, вызываяnextInt()до тех пор, пока результат не будет больше или равен нулю и меньшеbound. - Параметры:
-
bound- верхняя граница (исключительно) для возвращаемого значения. Должно быть положительным. - Возвращает:
- псевдослучайное целое значение между нулем (включительно) и пределом (исключительно)
- Исключения:
-
IllegalArgumentException- еслиboundне является положительным
nextInt
default int nextInt(int origin, int bound)
- Требования к реализации:
- Стандартная реализация проверяет, что
originиboundявляются положительнымиints. Затем вызываетnextInt(), ограничивая результат значением больше или равнымoriginи меньшеbound. Еслиboundявляется степенью двойки, то ограничение выполняется простой операцией побитового И. В противном случае результат пересчитывается, вызываяnextInt()до тех пор, пока результат не будет больше или равенoriginи меньшеbound. - Параметры:
-
origin- наименьшее возвращаемое значение -
bound- верхняя граница (исключительно) для возвращаемого значения - Возвращает:
- псевдослучайное целое значение между начальным значением (включительно) и пределом (исключительно)
- Исключения:
-
IllegalArgumentException- еслиoriginбольше или равноbound
nextLong
long nextLong()
- Возвращает:
- псевдослучайное значение типа long
nextLong
default long nextLong(long bound)
- Требования к реализации:
- Стандартная реализация проверяет, что
boundявляется положительнымlong. Затем вызываетnextLong(), ограничивая результат значением больше или равным нулю и меньшеbound. Еслиboundявляется степенью двойки, то ограничение выполняется простой операцией побитового И. В противном случае результат пересчитывается, вызываяnextLong()до тех пор, пока результат не будет больше или равен нулю и меньшеbound. - Параметры:
-
bound- верхняя граница (исключительно) для возвращаемого значения. Должно быть положительным. - Возвращает:
- псевдослучайное значение типа long между нулем (включительно) и пределом (исключительно)
- Исключения:
-
IllegalArgumentException- еслиboundне является положительным
nextLong
default long nextLong(long origin, long bound)
- Требования к реализации:
- Стандартная реализация проверяет, что
originиboundявляются положительнымиlongs. Затем вызываетnextLong(), ограничивая результат значением больше или равнымoriginи меньшеbound. Еслиboundявляется степенью двойки, то ограничение выполняется простой операцией побитового И. В противном случае результат пересчитывается, вызываяnextLong()до тех пор, пока результат не будет больше или равенoriginи меньшеbound. - Параметры:
-
origin- наименьшее возвращаемое значение -
bound- верхняя граница (исключительно) для возвращаемого значения - Возвращает:
- псевдослучайное значение типа long между начальным значением (включительно) и пределом (исключительно)
- Исключения:
-
IllegalArgumentException- еслиoriginбольше или равноbound
nextGaussian
default double nextGaussian()
- Требования к реализации:
- Стандартная реализация использует быстрый модифицированный алгоритм Зиггурата МакФарлейна (в основном основанный на таблицах, с редкими случаями, обрабатываемыми вычислением и отбором). Также используется метод алиасов Уокера для выборки из дискретного распределения.
- Возвращает:
- псевдослучайное значение из гауссовского распределения
nextGaussian
default double nextGaussian(double mean, double stddev)
- Требования к реализации:
- Стандартная реализация использует быстрый модифицированный алгоритм Зиггурата МакФарлейна (в основном основанный на таблицах, с редкими случаями, обрабатываемыми вычислением и отбором). Также используется метод алиасов Уокера для выборки из дискретного распределения.
- Параметры:
-
mean- среднее гауссовского распределения -
stddev- стандартное отклонение (корень из дисперсии) гауссовского распределения - Возвращает:
- псевдослучайное значение из заданного гауссовского распределения
- Исключения:
-
IllegalArgumentException- еслиstddevотрицательное
nextExponential
default double nextExponential()
- Требования к реализации:
- Стандартная реализация использует быстрый модифицированный алгоритм Зиггурата МакФарлейна (в основном основанный на таблицах, с редкими случаями, обрабатываемыми вычислением и отбором). Также используется метод алиасов Уокера для выборки из дискретного распределения.
- Возвращает:
- неотрицательное псевдослучайное значение из экспоненциального распределения
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/random/RandomGenerator.html