Module java.base
Package java.util

Class Random

java.lang.Object
java.util.Random
所有已实现的接口:
Serializable, RandomGenerator
直接已知的子类:
SecureRandom, ThreadLocalRandom

public class Random extends Object implements RandomGenerator, Serializable
该类的实例用于生成伪随机数流;其周期仅为248。该类使用一个48位种子,该种子使用线性同余公式进行修改。(参见Donald E. Knuth,《计算机程序设计艺术,第2卷,第3版:半数值算法》第3.2.1节。)

如果使用相同的种子创建两个Random实例,并且为每个实例进行相同的方法调用序列,它们将生成并返回相同的数字序列。为了保证这一属性,为类Random指定了特定的算法。Java实现必须使用此处显示的类Random的所有算法,以确保Java代码的绝对可移植性。但是,类Random的子类可以使用其他算法,只要它们遵守所有方法的一般契约即可。

Random实现的算法使用一个protected实用方法,每次调用可以提供高达32个伪随机生成的位。

许多应用程序会发现方法Math.random()更容易使用。

java.util.Random的实例是线程安全的。但是,在跨线程使用相同的java.util.Random实例时可能会遇到争用和随之而来的性能不佳。在多线程设计中,考虑改用ThreadLocalRandom

java.util.Random的实例不具有密码学安全性。考虑改用SecureRandom,以获取密码学安全的伪随机数生成器,供安全敏感应用程序使用。

自版本:
1.0
另请参阅:
  • Nested Class Summary

  • Constructor Summary

    Constructors
    Constructor
    Description
    Random()
    创建一个新的随机数生成器。
    Random(long seed)
    使用单个long种子创建一个新的随机数生成器。
  • Method Summary

    Modifier and Type
    Method
    Description
    返回一个有效无限的伪随机 double值流,每个值介于零(包括)和一(不包括)之间。
    doubles(double randomNumberOrigin, double randomNumberBound)
    返回一个有效无限的伪随机 double值流,每个值符合给定的起始值(包括)和边界值(不包括)。
    doubles(long streamSize)
    返回一个生成给定streamSize数量的伪随机double值流,每个值介于零(包括)和一(不包括)之间。
    doubles(long streamSize, double randomNumberOrigin, double randomNumberBound)
    返回一个生成给定streamSize数量的伪随机double值流,每个值符合给定的起始值(包括)和边界值(不包括)。
    static Random
    from(RandomGenerator generator)
    返回一个将方法调用委托给RandomGenerator参数的Random实例。
    ints()
    返回一个有效无限的伪随机int值流。
    ints(int randomNumberOrigin, int randomNumberBound)
    返回一个有效无限的伪随机 int值流,每个值符合给定的起始值(包括)和边界值(不包括)。
    ints(long streamSize)
    返回一个生成给定streamSize数量的伪随机int值流。
    ints(long streamSize, int randomNumberOrigin, int randomNumberBound)
    返回一个生成给定streamSize数量的伪随机int值流,每个值符合给定的起始值(包括)和边界值(不包括)。
    longs()
    返回一个有效无限的伪随机long值流。
    longs(long streamSize)
    返回一个生成给定streamSize数量的伪随机long值流。
    longs(long randomNumberOrigin, long randomNumberBound)
    返回一个有效无限的伪随机 long值流,每个值符合给定的起始值(包括)和边界值(不包括)。
    longs(long streamSize, long randomNumberOrigin, long randomNumberBound)
    返回一个生成给定streamSize数量的伪随机long值流,每个值符合给定的起始值(包括)和边界值(不包括)。
    protected int
    next(int bits)
    生成下一个伪随机数。
    boolean
    从该随机数生成器的序列中返回下一个伪随机、均匀分布的boolean值。
    void
    nextBytes(byte[] bytes)
    生成随机字节并将其放入用户提供的字节数组中。
    double
    从该随机数生成器的序列中返回下一个伪随机、均匀分布的double值,介于0.01.0之间。
    float
    从该随机数生成器的序列中返回下一个伪随机、均匀分布的float值,介于0.01.0之间。
    double
    从该随机数生成器的序列中返回下一个伪随机、高斯(“正态”)分布的double值,均值为0.0,标准差为1.0
    int
    从该随机数生成器的序列中返回下一个伪随机、均匀分布的int值。
    int
    nextInt(int bound)
    从该随机数生成器的序列中返回一个伪随机、均匀分布的int值,介于0(包括)和指定值(不包括)之间。
    long
    从该随机数生成器的序列中返回下一个伪随机、均匀分布的long值。
    void
    setSeed(long seed)
    使用提供的long种子值设置或更新此随机数生成器的种子(可选操作)。

    Methods declared in class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Constructor Details

    • Random

      public Random()
      创建一个新的随机数生成器。此构造函数将随机数生成器的种子设置为一个非常可能与此构造函数的任何其他调用不同的值。
    • Random

      public Random(long seed)
      使用单个long种子创建一个新的随机数生成器。该种子是由方法next(int)维护的伪随机数生成器的内部状态的初始值。
      实现要求:
      调用new Random(seed)等效于:
      
       Random rnd = new Random();
       rnd.setSeed(seed);
       
      参数:
      seed - 初始种子
      另请参阅:
  • Method Details

    • from

      public static Random from(RandomGenerator generator)
      返回一个将方法调用委托给RandomGenerator参数的Random实例。如果生成器是Random的实例,则返回该实例。否则,此方法返回一个将所有方法(除了setSeed)委托给生成器的Random实例。返回的实例的setSeed方法始终抛出UnsupportedOperationException。返回的实例不可序列化。
      参数:
      generator - 调用RandomGenerator的委托
      返回:
      委托的Random实例
      抛出:
      NullPointerException - 如果生成器为null
      自版本:
      19
    • setSeed

      public void setSeed(long seed)
      使用提供的long种子值设置或更新此随机数生成器的种子(可选操作)。
      实现要求:
      此类中的实现更改此随机数生成器的状态,使其处于与刚刚使用new Random(seed)创建时相同的状态。它将种子原子地更新为(seed ^ 0x5DEECE66DL) & ((1L << 48) - 1),并清除由nextGaussian()使用的haveNextNextGaussian标志。请注意,这仅使用给定种子值的48位。
      参数:
      seed - 种子值
      抛出:
      UnsupportedOperationException - 如果此随机数生成器不支持setSeed操作
    • next

      protected int next(int bits)
      生成下一个伪随机数。此方法返回一个int值,使得如果参数bits介于132(包括)之间,则返回值的低位中的那么多位(大约)是独立选择的位值,每个位值(大约)等可能地为01
      API注释:
      此类中的其他生成随机数的方法是基于此方法实现的,因此子类可以仅覆盖此方法,为整个类提供不同的伪随机数来源。
      实现要求:
      此类中的实现原子地将种子更新为(seed * 0x5DEECE66DL + 0xBL) & ((1L << 48) - 1),并返回(int)(seed >>> (48 - bits))

      这是一个线性同余伪随机数生成器,由D. H. Lehmer定义,并由Donald E. Knuth在《计算机程序设计艺术,第2卷,第3版:半数值算法》第3.2.1节中描述。

      参数:
      bits - 随机位
      返回:
      该随机数生成器序列中的下一个伪随机值
      自版本:
      1.1
    • nextBytes

      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
    • nextInt

      public int nextInt()
      返回此随机数生成器序列中的下一个伪随机、均匀分布的int值。方法nextInt的一般约定是伪随机生成并返回一个int值。所有232个可能的int值以(大约)相等的概率产生。
      指定由:
      nextInt 在接口 RandomGenerator
      实现要求:
      方法nextInt由类Random实现,如下所示:
      
       public int nextInt() {
         return next(32);
       }
      返回:
      此随机数生成器序列中的下一个伪随机、均匀分布的int
    • nextInt

      public int nextInt(int bound)
      返回此随机数生成器序列中的下一个伪随机、均匀分布的int值,介于0(包括)和指定值(不包括)之间。方法nextInt的一般约定是在指定范围内伪随机生成并返回一个int值。所有bound个可能的int值以(大约)相等的概率产生。
      指定由:
      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)  // 即,bound是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;
       }

      在上述描述中使用“大约”这个词只是因为next方法只是大约是一个不偏的独立选择位的源。如果它是一个完美的随机选择位的源,那么所示的算法将以完美的均匀性从所述范围中选择int值。

      该算法稍微复杂。它拒绝会导致不均匀分布的值(因为2^31不能被n整除)。被拒绝的值的概率取决于n。最坏情况是n=2^30+1,拒绝的概率为1/2,循环终止前的预期迭代次数为2。

      该算法特殊处理n是2的幂的情况:它从底层伪随机数生成器返回正确数量的高阶位。在没有特殊处理的情况下,将返回正确数量的低阶位。诸如此类的线性同余伪随机数生成器,如此类实现的生成器,已知其低阶位值的序列中存在短周期。因此,如果n是2的小幂,则此特殊情况大大增加了通过连续调用此方法返回的值序列的长度。

      参数:
      bound - 上限(不包括)。必须为正数。
      返回:
      此随机数生成器序列中介于零(包括)和bound(不包括)之间的下一个伪随机、均匀分布的int
      抛出:
      IllegalArgumentException - 如果bound不是正数
      自:
      1.2
    • nextLong

      public long nextLong()
      返回此随机数生成器序列中的下一个伪随机、均匀分布的long值。方法nextLong的一般约定是伪随机生成并返回一个long值。
      指定由:
      nextLong 在接口 RandomGenerator
      实现要求:
      方法nextLong由类Random实现,如下所示:
      
       public long nextLong() {
         return ((long)next(32) << 32) + next(32);
       }
      因为类Random只使用48位种子,此算法不会返回所有可能的long值。
      返回:
      此随机数生成器序列中的下一个伪随机、均匀分布的long
    • nextBoolean

      public boolean nextBoolean()
      返回此随机数生成器序列中的下一个伪随机、均匀分布的boolean值。方法nextBoolean的一般约定是伪随机生成并返回一个boolean值。值truefalse以(大约)相等的概率产生。
      指定由:
      nextBoolean 在接口 RandomGenerator
      实现要求:
      方法nextBoolean由类Random实现,如下所示:
      
       public boolean nextBoolean() {
         return next(1) != 0;
       }
      返回:
      此随机数生成器序列中的下一个伪随机、均匀分布的boolean
      自:
      1.2
    • nextFloat

      public float nextFloat()
      返回此随机数生成器序列中的下一个伪随机、均匀分布的float值,介于0.01.0之间。

      方法nextFloat的一般约定是从范围0.0f(包括)到1.0f(不包括)中选择一个(大约)均匀的float值,并伪随机生成并返回。所有形式为m x 2-24的正整数m小于224的可能float值以(大约)相等的概率产生。

      指定由:
      nextFloat 在接口 RandomGenerator
      实现要求:
      方法nextFloat由类Random实现,如下所示:
      
       public float nextFloat() {
         return next(24) / ((float)(1 << 24));
       }

      在上述描述中使用“大约”这个词只是因为next方法只是大约是一个不偏的独立选择位的源。如果它是一个完美的随机选择位的源,那么所示的算法将以完美的均匀性从所述范围中选择float值。

      [在早期的Java版本中,结果错误地计算为:

       return next(30) / ((float)(1 << 30));
      这可能看起来是等效的,甚至更好,但实际上由于浮点数舍入的偏差,引入了轻微的不均匀性:低阶位的有效数字的最低位为0的概率略高于为1的概率。]
      返回:
      此随机数生成器序列中介于0.0f1.0f之间的下一个伪随机、均匀分布的float
    • nextDouble

      public double nextDouble()
      返回此随机数生成器序列中的下一个伪随机、均匀分布的double值,介于0.01.0之间。

      方法nextDouble的一般约定是从范围0.0d(包括)到1.0d(不包括)中选择一个(大约)均匀的double值,并伪随机生成并返回。

      指定由:
      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的三倍!这种不均匀性在实践中可能并不重要,但我们追求完美。]
      返回:
      此随机数生成器序列中介于0.01.0之间的下一个伪随机、均匀分布的double
      参见:
    • nextGaussian

      public double nextGaussian()
      返回该随机数生成器序列中具有平均值为0.0和标准差为1.0的正态分布的下一个伪随机double值。

      nextGaussian的一般约定是,从(大约)具有平均值为0.0和标准差为1.0的正态分布中选择一个double值,生成伪随机值并返回。

      指定者:
      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;   // 在 -1.0 和 1.0 之间
             v2 = 2 * nextDouble() - 1;   // 在 -1.0 和 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;
         }
       }
      这使用了 G. E. P. Box、M. E. Muller 和 G. Marsaglia 的极坐标法,如 Donald E. Knuth 在The Art of Computer Programming, Volume 2, third edition: Seminumerical Algorithms 第 3.4.1 节,子节 C,算法 P 中所述。请注意,它仅通过一次调用StrictMath.log和一次调用StrictMath.sqrt生成两个独立值。
      返回:
      该随机数生成器序列中具有平均值为0.0和标准差为1.0的正态分布的下一个伪随机double
    • ints

      public IntStream ints(long streamSize)
      返回一个生成给定streamSize数量的伪随机int值的流。

      生成的伪随机int值就好像是调用方法nextInt()的结果。

      指定者:
      ints 在接口 RandomGenerator
      参数:
      streamSize - 要生成的值的数量
      返回:
      一系列伪随机int
      抛出:
      IllegalArgumentException - 如果streamSize小于零
      自:
      1.8
    • ints

      public IntStream ints()
      返回一个无限流,生成伪随机int值。

      生成的伪随机int值就好像是调用方法nextInt()的结果。

      指定者:
      ints 在接口 RandomGenerator
      实现注意:
      该方法被实现为等效于 ints(Long.MAX_VALUE)
      返回:
      一系列伪随机int
      自:
      1.8
    • ints

      public IntStream ints(long streamSize, int randomNumberOrigin, int randomNumberBound)
      返回一个生成给定streamSize数量的伪随机int值的流,每个值符合给定的起始值(包括)和边界值(不包括)。

      生成的伪随机int值就好像是调用具有起始值和边界值的以下方法的结果:

       
       int nextInt(int origin, int bound) {
         int n = bound - origin;
         if (n > 0) {
           return nextInt(n) + origin;
         }
         else {  // 范围无法表示为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
    • ints

      public IntStream ints(int randomNumberOrigin, int randomNumberBound)
      返回一个无限流,生成伪随机int值,每个值符合给定的起始值(包括)和边界值(不包括)。

      生成的伪随机int值就好像是调用具有起始值和边界值的以下方法的结果:

       
       int nextInt(int origin, int bound) {
         int n = bound - origin;
         if (n > 0) {
           return nextInt(n) + origin;
         }
         else {  // 范围无法表示为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
    • longs

      public LongStream longs(long streamSize)
      返回一个生成给定streamSize数量的伪随机long值的流。

      生成的伪随机long值就好像是调用方法nextLong()的结果。

      指定者:
      longs 在接口 RandomGenerator
      参数:
      streamSize - 要生成的值的数量
      返回:
      一系列伪随机long
      抛出:
      IllegalArgumentException - 如果streamSize小于零
      自:
      1.8
    • longs

      public LongStream longs()
      返回一个无限流,生成伪随机long值。

      生成的伪随机long值就好像是调用方法nextLong()的结果。

      指定者:
      longs 在接口 RandomGenerator
      实现注意:
      该方法被实现为等效于 longs(Long.MAX_VALUE)
      返回:
      一系列伪随机long
      自:
      1.8
    • longs

      public LongStream longs(long streamSize, long randomNumberOrigin, long randomNumberBound)
      返回一个生成给定streamSize数量的伪随机long值的流,每个值符合给定的起始值(包括)和边界值(不包括)。

      生成的伪随机long值就好像是调用具有起始值和边界值的以下方法的结果:

       
       long nextLong(long origin, long bound) {
         long r = nextLong();
         long n = bound - origin, m = n - 1;
         if ((n & m) == 0L)  // 为2的幂
           r = (r & m) + origin;
         else if (n > 0L) {  // 拒绝过多的候选值
           for (long u = r >>> 1;            // 确保非负
                u + m - (r = u % n) < 0L;    // 拒绝检查
                u = nextLong() >>> 1) // 重试
               ;
           r += origin;
         }
         else {              // 范围无法表示为long
           while (r < origin || r >= bound)
             r = nextLong();
         }
         return r;
       }
      指定者:
      longs 在接口 RandomGenerator
      参数:
      streamSize - 要生成的值的数量
      randomNumberOrigin - 每个随机值的起始值(包括)
      randomNumberBound - 每个随机值的边界值(不包括)
      返回:
      一系列伪随机long值,每个值具有给定的起始值(包括)和边界值(不包括)
      抛出:
      IllegalArgumentException - 如果streamSize小于零,或randomNumberOrigin大于或等于randomNumberBound
      自:
      1.8
    • longs

      public LongStream longs(long randomNumberOrigin, long randomNumberBound)
      返回一个有效无限流的伪随机 long值,每个值都符合给定的起始值(包含)和边界值(不包含)。

      生成一个伪随机long值,就好像调用以下方法并传入起始值和边界值一样:

       
       long nextLong(long origin, long bound) {
         long r = nextLong();
         long n = bound - origin, m = n - 1;
         if ((n & m) == 0L)  // 二的幂
           r = (r & m) + origin;
         else if (n > 0L) {  // 拒绝过多的候选值
           for (long u = r >>> 1;            // 确保非负
                u + m - (r = u % n) < 0L;    // 拒绝检查
                u = nextLong() >>> 1) // 重试
               ;
           r += origin;
         }
         else {              // 范围无法表示为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
    • doubles

      public DoubleStream doubles(long streamSize)
      返回一个生成给定streamSize数量的伪随机double值流,每个值都介于零(包含)和一(不包含)之间。

      生成一个伪随机double值,就好像调用方法nextDouble()的结果一样。

      指定者:
      doubles 在接口 RandomGenerator
      参数:
      streamSize - 要生成的值的数量
      返回:
      一个double值流
      抛出:
      IllegalArgumentException - 如果streamSize小于零
      自版本:
      1.8
    • doubles

      public DoubleStream doubles()
      返回一个有效无限流的伪随机 double值流,每个值都介于零(包含)和一(不包含)之间。

      生成一个伪随机double值,就好像调用方法nextDouble()的结果一样。

      指定者:
      doubles 在接口 RandomGenerator
      实现说明:
      此方法实现等效于 doubles(Long.MAX_VALUE)
      返回:
      一个伪随机double值流
      自版本:
      1.8
    • doubles

      public DoubleStream doubles(long streamSize, double randomNumberOrigin, double randomNumberBound)
      返回一个生成给定streamSize数量的伪随机double值流,每个值都符合给定的起始值(包含)和边界值(不包含)。
      指定者:
      doubles 在接口 RandomGenerator
      参数:
      streamSize - 要生成的值的数量
      randomNumberOrigin - 每个随机值的起始值(包含)
      randomNumberBound - 每个随机值的边界值(不包含)
      返回:
      一个伪随机double值流,每个值都具有给定的起始值(包含)和边界值(不包含)
      抛出:
      IllegalArgumentException - 如果streamSize小于零,或randomNumberOrigin不是有限的,或randomNumberBound不是有限的,或randomNumberOrigin大于或等于randomNumberBound
      自版本:
      1.8
    • doubles

      public DoubleStream doubles(double randomNumberOrigin, double randomNumberBound)
      返回一个有效无限流的伪随机 double值流,每个值都符合给定的起始值(包含)和边界值(不包含)。
      指定者:
      doubles 在接口 RandomGenerator
      实现说明:
      此方法实现等效于 doubles(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)
      参数:
      randomNumberOrigin - 每个随机值的起始值(包含)
      randomNumberBound - 每个随机值的边界值(不包含)
      返回:
      一个伪随机double值流,每个值都具有给定的起始值(包含)和边界值(不包含)
      抛出:
      IllegalArgumentException - 如果randomNumberOrigin不是有限的,或randomNumberBound不是有限的,或randomNumberOrigin大于或等于randomNumberBound
      自版本:
      1.8