Random (GNU Classpath 0.94-pre Documentation)

This class generates pseudorandom numbers. It uses the same algorithm as the original JDK-class, so that your programs behave exactly the same way, if started with the same seed. The algorithm is described in The Art of Computer Programming, Volume 2 by Donald Knuth in Section 3.2.1. It is a 48-bit seed, linear congruential formula. If two instances of this class are created with the same seed and the same calls to these classes are made, they behave exactly the same way. This should be even true for foreign implementations (like this), so every port must use the same algorithm as described here. If you want to implement your own pseudorandom algorithm, you should extend this class and overload the next() and setSeed(long) method. In that case the above paragraph doesn't apply to you. This class shouldn't be used for security sensitive purposes (like generating passwords or encryption keys. See SecureRandom in package java.security for this purpose. For simple random doubles between 0.0 and 1.0, you may consider using Math.random instead.

Constructor Summary
	Random() Creates a new pseudorandom number generator.
	Random(long seed) Creates a new pseudorandom number generator, starting with the specified seed, using `setSeed(seed);`.

Method Summary
protected int	next(int bits) Generates the next pseudorandom number.
boolean	nextBoolean() Generates the next pseudorandom boolean.
void	nextBytes(byte[] bytes) Fills an array of bytes with random numbers.
double	nextDouble() Generates the next pseudorandom double uniformly distributed between 0.0 (inclusive) and 1.0 (exclusive).
float	nextFloat() Generates the next pseudorandom float uniformly distributed between 0.0f (inclusive) and 1.0f (exclusive).
double	nextGaussian() Generates the next pseudorandom, Gaussian (normally) distributed double value, with mean 0.0 and standard deviation 1.0.
int	nextInt() Generates the next pseudorandom number.
int	nextInt(int n) Generates the next pseudorandom number.
long	nextLong() Generates the next pseudorandom long number.
void	setSeed(long seed) Sets the seed for this pseudorandom number generator.

See Also: currentTimeMillis

Random

Creates a new pseudorandom number generator, starting with the specified seed, using setSeed(seed);.

Parameters: seed the initial seed

Method Detail

Generates the next pseudorandom number. This returns an int value whose bits low order bits are independent chosen random bits (0 and 1 are equally likely). The implementation for java.util.Random is:

protected synchronized int next(int bits)
{
  seed = (seed * 0x5DEECE66DL + 0xBL) & ((1L << 48) - 1);
  return (int) (seed >>> (48 - bits));
}

Parameters: bits the number of random bits to generate, in the range 1..32

Returns: the next pseudorandom value

Since: 1.1

nextBoolean

Generates the next pseudorandom boolean. True and false have the same probability. The implementation is:

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

Returns: the next pseudorandom boolean

Since: 1.2

nextBytes

Fills an array of bytes with random numbers. All possible values are (approximately) equally likely. The JDK documentation gives no implementation, but it seems to be:

public void nextBytes(byte[] bytes)
{
  for (int i = 0; i < bytes.length; i += 4)
  {
    int random = next(32);
    for (int j = 0; i + j < bytes.length && j < 4; j++)
    {
      bytes[i+j] = (byte) (random & 0xff)
      random >>= 8;
    }
  }
}

Parameters: bytes the byte array that should be filled

Throws: NullPointerException if bytes is null

Since: 1.1

nextDouble

Generates the next pseudorandom double uniformly distributed between 0.0 (inclusive) and 1.0 (exclusive). The implementation is as follows.

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

Returns: the next pseudorandom double

nextFloat

Generates the next pseudorandom float uniformly distributed between 0.0f (inclusive) and 1.0f (exclusive). The implementation is as follows.

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

Returns: the next pseudorandom float

nextGaussian

Generates the next pseudorandom, Gaussian (normally) distributed double value, with mean 0.0 and standard deviation 1.0. The algorithm is as follows.

public synchronized 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);

    double norm = Math.sqrt(-2 * Math.log(s) / s);
    nextNextGaussian = v2 * norm;
    haveNextNextGaussian = true;
    return v1 * norm;
  }
}

This is described in section 3.4.1 of The Art of Computer Programming, Volume 2 by Donald Knuth.

Returns: the next pseudorandom Gaussian distributed double

nextInt

Generates the next pseudorandom number. This returns an int value whose 32 bits are independent chosen random bits (0 and 1 are equally likely). The implementation for java.util.Random is:

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

Returns: the next pseudorandom value

nextInt

Generates the next pseudorandom number. This returns a value between 0(inclusive) and n(exclusive), and each value has the same likelihodd (1/n). (0 and 1 are equally likely). The implementation for java.util.Random is:

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

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

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

  return val;
}

This algorithm would return every value with exactly the same probability, if the next()-method would be a perfect random number generator. The loop at the bottom only accepts a value, if the random number was between 0 and the highest number less then 1<<31, which is divisible by n. The probability for this is high for small n, and the worst case is 1/2 (for n=(1<<30)+1). The special treatment for n = power of 2, selects the high bits of the random number (the loop at the bottom would select the low order bits). This is done, because the low order bits of linear congruential number generators (like the one used in this class) are known to be ``less random'' than the high order bits.

Parameters: n the upper bound

Returns: the next pseudorandom value

Throws: IllegalArgumentException if the given upper bound is negative

Since: 1.2

nextLong

Generates the next pseudorandom long number. All bits of this long are independently chosen and 0 and 1 have equal likelihood. The implementation for java.util.Random is:

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

Returns: the next pseudorandom value

setSeed

Sets the seed for this pseudorandom number generator. As described above, two instances of the same random class, starting with the same seed, should produce the same results, if the same methods are called. The implementation for java.util.Random is:

public synchronized void setSeed(long seed)
{
  this.seed = (seed ^ 0x5DEECE66DL) & ((1L << 48) - 1);
  haveNextNextGaussian = false;
}

Parameters: seed the new seed

Class Random

Constructor Detail

Random

Random

Method Detail

next

nextBoolean

nextBytes

nextDouble

nextFloat

nextGaussian

nextInt

nextInt

nextLong

setSeed