Класс Random

public Random()

public Random(long seed)

Требования к реализации:

Вызов new Random(seed) эквивалентен:

Random rnd = new Random();
rnd.setSeed(seed);

Параметры:

seed — начальное значение

См. также:

• setSeed(long)

public static Random from(RandomGenerator generator)

Параметры:

generator — объект, которому делегируются вызовы RandomGenerator

Возвращает:

делегирующий экземпляр Random

Выбрасывает:

NullPointerException — если генератор равен null

Начиная с версии:

19

public void setSeed(long seed)

Требования к реализации:

Реализация в этом классе изменяет состояние генератора случайных чисел так, чтобы оно совпадало с состоянием сразу после создания с помощью new Random(seed). Она атомарно обновляет начальное значение до

(seed ^ 0x5DEECE66DL) & ((1L << 48) - 1)

и сбрасывает флаг haveNextNextGaussian, используемый методом nextGaussian(). Обратите внимание, что используются только 48 бит заданного начального значения.

Параметры:

seed — начальное значение

Выбрасывает:

UnsupportedOperationException — если операция setSeed не поддерживается этим генератором случайных чисел

protected int next(int bits)

Примечание к API:

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

Требования к реализации:

Реализация в этом классе атомарно обновляет начальное значение до

(seed * 0x5DEECE66DL + 0xBL) & ((1L << 48) - 1)

и возвращает

(int)(seed >>> (48 - bits)).

Это линейный конгруэнтный генератор псевдослучайных чисел, определенный Д. Х. Лемером и описанный Дональдом Э. Кнутом в книге Искусство программирования, том 2, третье издание: Полу численные алгоритмы, раздел 3.2.1.

Параметры:

bits — случайные биты

Возвращает:

следующее псевдослучайное значение из последовательности этого генератора случайных чисел

Начиная с версии:

1.1

public void nextBytes(byte[] bytes)

Определено в:

nextBytes в интерфейсе RandomGenerator

Требования к реализации:

Метод nextBytes реализован классом Random так, как если бы он выполнял:

public void nextBytes(byte[] bytes) {
  for (int i = 0; i < bytes.length; )
    for (int rnd = nextInt(), n = Math.min(bytes.length - i, 4);
         n-- > 0; rnd >>= 8)
      bytes[i++] = (byte)rnd;
}

Параметры:

bytes — массив байтов для заполнения случайными байтами

Выбрасывает:

NullPointerException — если массив байтов равен null

Начиная с версии:

1.1

public int nextInt()

Определено в:

nextInt в интерфейсе RandomGenerator

Требования к реализации:

Метод nextInt реализован классом Random так, как если бы он выполнял:

public int nextInt() {
  return next(32);
}

Возвращает:

следующее псевдослучайное равномерно распределенное значение типа int из последовательности этого генератора случайных чисел

public int nextInt(int bound)

Определено в:

nextInt в интерфейсе RandomGenerator

Требования к реализации:

Метод nextInt(int bound) реализован классом Random так, как если бы он выполнял:

public int nextInt(int bound) {
  if (bound <= 0)
    throw new IllegalArgumentException("bound must be positive");

  if ((bound & -bound) == bound)  // i.e., bound is a power of 2
    return (int)((bound * (long)next(31)) >> 31);

  int bits, val;
  do {
      bits = next(31);
      val = bits % bound;
  } while (bits - val + (bound-1) < 0);
  return val;
}

Оговорка «приблизительно» в приведенном выше описании используется только потому, что следующий метод является лишь приблизительно несмещенным источником независимо выбираемых битов. Если бы он был идеальным источником случайно выбранных битов, показанный алгоритм выбирал бы значения int из указанного диапазона с идеальной равномерностью.

Алгоритм немного хитро устроен. Он отбрасывает значения, которые привели бы к неравномерному распределению (поскольку 2^31 не делится на n). Вероятность отбрасывания значения зависит от n. Худший случай — n=2^30+1, когда вероятность отбрасывания равна 1/2, а ожидаемое число итераций до завершения цикла — 2.

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

Параметры:

bound — верхняя граница (не включительно). Должна быть положительной.

Возвращает:

следующее псевдослучайное равномерно распределенное значение типа int в диапазоне от нуля (включительно) до bound (не включительно) из последовательности этого генератора случайных чисел

Выбрасывает:

IllegalArgumentException — если верхняя граница не является положительной

Начиная с версии:

1.2

public long nextLong()

Определено в:

nextLong в интерфейсе RandomGenerator

Требования к реализации:

Метод nextLong реализован классом Random так, как если бы он выполнял:

public long nextLong() {
  return ((long)next(32) << 32) + next(32);
}

Поскольку класс Random использует начальное значение длиной всего 48 бит, этот алгоритм не возвращает все возможные значения типа long.

Возвращает:

следующее псевдослучайное равномерно распределенное значение типа long из последовательности этого генератора случайных чисел

public boolean nextBoolean()

Определено в:

nextBoolean в интерфейсе RandomGenerator

Требования к реализации:

Метод nextBoolean реализован классом Random так, как если бы он выполнял:

public boolean nextBoolean() {
  return next(1) != 0;
}

Возвращает:

следующее псевдослучайное равномерно распределенное значение типа boolean из последовательности этого генератора случайных чисел

Начиная с версии:

1.2

public float nextFloat()

Определено в:

nextFloat в интерфейсе RandomGenerator

Требования к реализации:

Метод nextFloat реализован классом Random так, как если бы он выполнял:

public float nextFloat() {
  return next(24) / ((float)(1 << 24));
}

Оговорка «приблизительно» в приведенном выше описании используется только потому, что следующий метод является лишь приблизительно несмещенным источником независимо выбираемых битов. Если бы он был идеальным источником случайно выбранных битов, показанный алгоритм выбирал бы значения float из указанного диапазона с идеальной равномерностью.

[В ранних версиях Java результат ошибочно вычислялся так:

 return next(30) / ((float)(1 << 30));

Это может показаться эквивалентным, если не лучшим вариантом, но на самом деле такой подход вносил небольшую неравномерность из-за смещения при округлении чисел с плавающей точкой: вероятность того, что младший бит значащей части будет равен 0, была немного выше, чем вероятность того, что он будет равен 1.]

Возвращает:

следующее псевдослучайное равномерно распределенное значение типа float в диапазоне от 0.0f до 1.0f из последовательности этого генератора случайных чисел

public double nextDouble()

Определено в:

nextDouble в интерфейсе RandomGenerator

Требования к реализации:

Метод nextDouble реализован классом Random так, как если бы он выполнял:

public double nextDouble() {
  return (((long)next(26) << 27) + next(27))
    / (double)(1L << 53);
}

Оговорка «приблизительно» в приведенном выше описании используется только потому, что метод next является лишь приблизительно несмещенным источником независимо выбираемых битов. Если бы он был идеальным источником случайно выбранных битов, показанный алгоритм выбирал бы значения double из указанного диапазона с идеальной равномерностью.

[В ранних версиях Java результат ошибочно вычислялся так:

 return (((long)next(27) << 27) + next(27)) / (double)(1L << 54);

Это может показаться эквивалентным, если не лучшим вариантом, но на самом деле такой подход вносил значительную неравномерность из-за смещения при округлении чисел с плавающей точкой: вероятность того, что младший бит значащей части будет равен 0, была втрое выше, чем вероятность того, что он будет равен 1! На практике эта неравномерность, вероятно, не имеет большого значения, но мы стремимся к совершенству.]

Возвращает:

следующее псевдослучайное равномерно распределенное значение типа double в диапазоне от 0.0 до 1.0 из последовательности этого генератора случайных чисел

См. также:

• Math.random()

public double nextGaussian()

Определено в:

nextGaussian в интерфейсе RandomGenerator

Требования к реализации:

Метод nextGaussian реализован классом Random как потокобезопасная версия следующего кода:

private double nextNextGaussian;
private boolean haveNextNextGaussian = false;

public double nextGaussian() {
  if (haveNextNextGaussian) {
    haveNextNextGaussian = false;
    return nextNextGaussian;
  } else {
    double v1, v2, s;
    do {
      v1 = 2 * nextDouble() - 1;   // between -1.0 and 1.0
      v2 = 2 * nextDouble() - 1;   // between -1.0 and 1.0
      s = v1 * v1 + v2 * v2;
    } while (s >= 1 || s == 0);
    double multiplier = StrictMath.sqrt(-2 * StrictMath.log(s)/s);
    nextNextGaussian = v2 * multiplier;
    haveNextNextGaussian = true;
    return v1 * multiplier;
  }
}

Здесь используется полярный метод Дж. Э. П. Бокса, М. Э. Мюллера и Дж. Марсальи, описанный Дональдом Э. Кнутом в книге Искусство программирования, том 2, третье издание: Полу численные алгоритмы, раздел 3.4.1, подраздел C, алгоритм P. Обратите внимание, что он генерирует два независимых значения ценой всего одного вызова StrictMath.log и одного вызова StrictMath.sqrt.

Возвращает:

следующее псевдослучайное значение типа double с гауссовым (нормальным) распределением, средним значением 0.0 и стандартным отклонением 1.0 из последовательности этого генератора случайных чисел

public IntStream ints(long streamSize)

Определено в:

ints в интерфейсе RandomGenerator

Параметры:

streamSize — количество генерируемых значений

Возвращает:

поток псевдослучайных значений типа int

Выбрасывает:

IllegalArgumentException — если streamSize меньше нуля

Начиная с версии:

1.8

public IntStream ints()

Определено в:

ints в интерфейсе RandomGenerator

Примечание к реализации:

Этот метод реализован так, чтобы быть эквивалентным ints(Long.MAX_VALUE).

Возвращает:

поток псевдослучайных значений типа int

Начиная с версии:

1.8

public IntStream ints(long streamSize, int randomNumberOrigin, int randomNumberBound)

int nextInt(int origin, int bound) {
  int n = bound - origin;
  if (n > 0) {
    return nextInt(n) + origin;
  }
  else {  // range not representable as int
    int r;
    do {
      r = nextInt();
    } while (r < origin || r >= bound);
    return r;
  }
}

Определено в:

ints в интерфейсе RandomGenerator

Параметры:

streamSize — количество генерируемых значений

randomNumberOrigin — начальная граница (включительно) каждого случайного значения

randomNumberBound — верхняя граница (не включительно) каждого случайного значения

Возвращает:

поток псевдослучайных значений типа int, каждое из которых находится между заданной начальной границей (включительно) и верхней границей (не включительно)

Выбрасывает:

IllegalArgumentException — если streamSize меньше нуля или randomNumberOrigin больше либо равно randomNumberBound

Начиная с версии:

1.8

public IntStream ints(int randomNumberOrigin, int randomNumberBound)

int nextInt(int origin, int bound) {
  int n = bound - origin;
  if (n > 0) {
    return nextInt(n) + origin;
  }
  else {  // range not representable as int
    int r;
    do {
      r = nextInt();
    } while (r < origin || r >= bound);
    return r;
  }
}

Определено в:

ints в интерфейсе RandomGenerator

Примечание к реализации:

Этот метод реализован так, чтобы быть эквивалентным ints(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound).

Параметры:

randomNumberOrigin — начальная граница (включительно) каждого случайного значения

randomNumberBound — верхняя граница (не включительно) каждого случайного значения

Возвращает:

поток псевдослучайных значений типа int, каждое из которых находится между заданной начальной границей (включительно) и верхней границей (не включительно)

Выбрасывает:

IllegalArgumentException — если randomNumberOrigin больше либо равно randomNumberBound

Начиная с версии:

1.8

public LongStream longs(long streamSize)

Определено в:

longs в интерфейсе RandomGenerator

Параметры:

streamSize — количество генерируемых значений

Возвращает:

поток псевдослучайных значений типа long

Выбрасывает:

IllegalArgumentException — если streamSize меньше нуля

Начиная с версии:

1.8

public LongStream longs()

Определено в:

longs в интерфейсе RandomGenerator

Примечание к реализации:

Этот метод реализован так, чтобы быть эквивалентным longs(Long.MAX_VALUE).

Возвращает:

поток псевдослучайных значений типа long

Начиная с версии:

1.8

public LongStream longs(long streamSize, long randomNumberOrigin, long randomNumberBound)

long nextLong(long origin, long bound) {
  long r = nextLong();
  long n = bound - origin, m = n - 1;
  if ((n & m) == 0L)  // power of two
    r = (r & m) + origin;
  else if (n > 0L) {  // reject over-represented candidates
    for (long u = r >>> 1;            // ensure nonnegative
         u + m - (r = u % n) < 0L;    // rejection check
         u = nextLong() >>> 1) // retry
        ;
    r += origin;
  }
  else {              // range not representable as long
    while (r < origin || r >= bound)
      r = nextLong();
  }
  return r;
}

Определено в:

longs в интерфейсе RandomGenerator

Параметры:

streamSize — количество генерируемых значений

randomNumberOrigin — начальная граница (включительно) каждого случайного значения

randomNumberBound — верхняя граница (не включительно) каждого случайного значения

Возвращает:

поток псевдослучайных значений типа long, каждое из которых находится между заданной начальной границей (включительно) и верхней границей (не включительно)

Выбрасывает:

IllegalArgumentException — если streamSize меньше нуля или randomNumberOrigin больше либо равно randomNumberBound

Начиная с версии:

1.8

public LongStream longs(long randomNumberOrigin, long randomNumberBound)

long nextLong(long origin, long bound) {
  long r = nextLong();
  long n = bound - origin, m = n - 1;
  if ((n & m) == 0L)  // power of two
    r = (r & m) + origin;
  else if (n > 0L) {  // reject over-represented candidates
    for (long u = r >>> 1;            // ensure nonnegative
         u + m - (r = u % n) < 0L;    // rejection check
         u = nextLong() >>> 1) // retry
        ;
    r += origin;
  }
  else {              // range not representable as long
    while (r < origin || r >= bound)
      r = nextLong();
  }
  return r;
}

Определено в:

longs в интерфейсе RandomGenerator

Примечание к реализации:

Этот метод реализован так, чтобы быть эквивалентным longs(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound).

Параметры:

randomNumberOrigin — начальная граница (включительно) каждого случайного значения

randomNumberBound — верхняя граница (не включительно) каждого случайного значения

Возвращает:

поток псевдослучайных значений типа long, каждое из которых находится между заданной начальной границей (включительно) и верхней границей (не включительно)

Выбрасывает:

IllegalArgumentException — если randomNumberOrigin больше либо равно randomNumberBound

Начиная с версии:

1.8

public DoubleStream doubles(long streamSize)

Определено в:

doubles в интерфейсе RandomGenerator

Параметры:

streamSize — количество генерируемых значений

Возвращает:

поток значений типа double

Выбрасывает:

IllegalArgumentException — если streamSize меньше нуля

Начиная с версии:

1.8

public DoubleStream doubles()

Определено в:

doubles в интерфейсе RandomGenerator

Примечание к реализации:

Этот метод реализован так, чтобы быть эквивалентным doubles(Long.MAX_VALUE).

Возвращает:

поток псевдослучайных значений типа double

Начиная с версии:

1.8

public DoubleStream doubles(long streamSize, double randomNumberOrigin, double randomNumberBound)

Определено в:

doubles в интерфейсе RandomGenerator

Параметры:

streamSize — количество генерируемых значений

randomNumberOrigin — начальная граница (включительно) каждого случайного значения

randomNumberBound — верхняя граница (не включительно) каждого случайного значения

Возвращает:

поток псевдослучайных значений типа double, каждое из которых находится между заданной начальной границей (включительно) и верхней границей (не включительно)

Выбрасывает:

IllegalArgumentException — если streamSize меньше нуля, или randomNumberOrigin не является конечным числом, или randomNumberBound не является конечным числом, или randomNumberOrigin больше либо равно randomNumberBound

Начиная с версии:

1.8

public DoubleStream doubles(double randomNumberOrigin, double randomNumberBound)

Определено в:

doubles в интерфейсе RandomGenerator

Примечание к реализации:

Этот метод реализован так, чтобы быть эквивалентным doubles(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound).

Параметры:

randomNumberOrigin — начальная граница (включительно) каждого случайного значения

randomNumberBound — верхняя граница (не включительно) каждого случайного значения

Возвращает:

поток псевдослучайных значений типа double, каждое из которых находится между заданной начальной границей (включительно) и верхней границей (не включительно)

Выбрасывает:

IllegalArgumentException — если randomNumberOrigin не является конечным числом, или randomNumberBound не является конечным числом, или randomNumberOrigin больше либо равно randomNumberBound

Начиная с версии:

1.8