public class

Random

extends Random
java.lang.Object
   ↳ java.util.Random
     ↳ sofia.util.Random

Class Overview

This subclass of java.util.Random adds extra methods useful for testing purposes. Normally, you might generate a new random number by calling nextInt(), nextDouble(), or one of the other generation methods provided by Random. Normally, this intentionally makes your code behave in a random way, which may make it harder to test. This class allows you to control directly the sequence of numbers that will be generated by such calls.

Suppose your code is written this way:

  Random random = Random.generator();  // or new Random()
  ...
  int x = random.nextInt(64);

You can then write test cases that look like this:

  public void testSomeFeature()
  {
      // Set the return values for the next 6 calls to nextInt(),
      // No matter which instance of TestableRandom the method is called on
      Random.setNextInts(5, 10, 22, 13, 12, 47);

      // Perform tests, knowing in advance the exact sequence of numbers
      // That will now be generated
  }

This class provides separate methods to preset the sequence of booleans, ints, doubles, floats, bytes, or Gaussian-distributed doubles that will be generated. You can pass in as many specific values to the setNext...() methods that you like, or you can even pass in an array:

  int[] someValues = new int[] { 1, 2, 3, 4, 5, 6, 7 };
  Random.setNextInts(someValues);

Summary

Public Constructors
Random()
Creates a new random number generator.
Random(long seed)
Creates a new random number generator using a single long seed.
Public Methods
static Random generator()
Returns a Random instance that is shared across all classes in an application.
boolean nextBoolean()
Returns the next pseudorandom, uniformly distributed boolean value from this random number generator's sequence.
void nextBytes(byte[] bytes)
Generates random bytes and places them into a user-supplied byte array.
double nextDouble()
Returns the next pseudorandom, uniformly distributed double value between 0.0 and 1.0 from this random number generator's sequence.
double nextDouble(double low, double high)
Returns the next random real number in the specified range.
float nextFloat(float low, float high)
Returns the next random real number in the specified range.
float nextFloat()
Returns the next pseudorandom, uniformly distributed float value between 0.0f and 1.0f from this random number generator's sequence.
double nextGaussian()
Returns the next pseudorandom, Gaussian ("normally") distributed double value with mean 0.0 and standard deviation 1.0 from this random number generator's sequence.
int nextInt(int low, int high)
Returns the next random integer in the specified range.
int nextInt(int n)
Returns a pseudorandom, uniformly distributed int value between 0 (inclusive) and the specified value (exclusive), drawn from this random number generator's sequence.
int nextInt()
Returns the next pseudorandom, uniformly distributed int value from this random number generator's sequence.
long nextLong(long low, long high)
Returns the next random long in the specified range.
long nextLong()
Returns the next pseudorandom, uniformly distributed long value from this random number generator's sequence.
static void setNextBooleans(boolean... values)
This method allows one to provide a predefined series of values that will override the results provided by nextBoolean().
static void setNextBytes(byte... values)
This method allows one to provide a predefined series of values that will override the results provided by nextBytes(byte[]).
static void setNextDoubles(double... values)
This method allows one to provide a predefined series of values that will override the results provided by nextDouble().
static void setNextFloats(float... values)
This method allows one to provide a predefined series of values that will override the results provided by nextFloat().
static void setNextGaussians(double... values)
This method allows one to provide a predefined series of values that will override the results provided by nextGaussian().
static void setNextInts(int... values)
This method allows one to provide a predefined series of values that will override the results provided by nextInt() and nextInt(int).
static void setNextLongs(long... values)
This method allows one to provide a predefined series of values that will override the results provided by nextLong().
[Expand]
Inherited Methods
From class java.util.Random
From class java.lang.Object

Public Constructors

public Random ()

Creates a new random number generator. This constructor sets the seed of the random number generator to a value very likely to be distinct from any other invocation of this constructor.

Most clients will not use the constructor directly but will instead call generator() to obtain a Random object that is shared by all classes in the application.

public Random (long seed)

Creates a new random number generator using a single long seed. The seed is the initial value of the internal state of the pseudorandom number generator which is maintained by method next(int).

The invocation new Random(seed) is equivalent to:

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

Parameters
seed the initial seed
See Also

Public Methods

public static Random generator ()

Returns a Random instance that is shared across all classes in an application. Using this shared instance of the generator is preferable to allocating new instances of Random. If you create several random generators in succession, they will typically generate the same sequence of values.

Returns
  • A shared Random object.

public boolean nextBoolean ()

Returns the next pseudorandom, uniformly distributed boolean value from this random number generator's sequence. The general contract of nextBoolean is that one boolean value is pseudorandomly generated and returned. The values true and false are produced with (approximately) equal probability.

If setNextBooleans(boolean) has been called, the next available value from the provided sequence will be returned until that sequence is exhausted. One all provided values have been returned, then true pseudorandom generation will resume.

Returns
  • the next pseudorandom, uniformly distributed boolean value from this random number generator's sequence

public void nextBytes (byte[] bytes)

Generates random bytes and places them into a user-supplied byte array. The number of random bytes produced is equal to the length of the byte array.

If setNextBytes(byte) has been called, unused values from the provided sequence will be used to fill the provided array until that sequence is exhausted. One all provided values have been used up, true pseudorandom generation will resume for filling any remaining slots in this or future calls.

Parameters
bytes the byte array to fill with random bytes
Throws
NullPointerException if the byte array is null

public double nextDouble ()

Returns the next pseudorandom, uniformly distributed double value between 0.0 and 1.0 from this random number generator's sequence.

If setNextDoubles(double) has been called, the next available value from the provided sequence will be returned until that sequence is exhausted. One all provided values have been returned, then true pseudorandom generation will resume.

Returns
  • the next pseudorandom, uniformly distributed double value from this random number generator's sequence

public double nextDouble (double low, double high)

Returns the next random real number in the specified range. The resulting value is always at least low but always strictly less than high. You can use this method to generate continuous random values. For example, you can set the variables x and y to specify a random point inside the unit square as follows: 

      double x = generator.nextDouble(0.0, 1.0);
      double y = generator.nextDouble(0.0, 1.0);

Parameters
low The low end of the range.
high The high end of the range.
Returns
  • A random double value d in the range low ≤ d < high.

public float nextFloat (float low, float high)

Returns the next random real number in the specified range. The resulting value is always at least low but always strictly less than high. You can use this method to generate continuous random values. For example, you can set the variables x and y to specify a random point inside the unit square as follows: 

      float x = generator.nextFloat(0.0f, 1.0f);
      float y = generator.nextFloat(0.0f, 1.0f);

Parameters
low The low end of the range.
high The high end of the range.
Returns
  • A random float value d in the range low ≤ d < high.

public float nextFloat ()

Returns the next pseudorandom, uniformly distributed float value between 0.0f and 1.0f from this random number generator's sequence.

If setNextFloats(float) has been called, the next available value from the provided sequence will be returned until that sequence is exhausted. One all provided values have been returned, then true pseudorandom generation will resume.

Returns
  • the next pseudorandom, uniformly distributed float value from this random number generator's sequence

public double nextGaussian ()

Returns the next pseudorandom, Gaussian ("normally") distributed double value with mean 0.0 and standard deviation 1.0 from this random number generator's sequence.

If setNextGaussians(double) has been called, the next available value from the provided sequence will be returned until that sequence is exhausted. One all provided values have been returned, then true pseudorandom generation will resume.

Returns
  • the next pseudorandom, Gaussian ("normally") distributed double value with mean 0.0 and standard deviation 1.0 from this random number generator's sequence

public int nextInt (int low, int high)

Returns the next random integer in the specified range. For example, you can generate the roll of a six-sided die by calling: 

 generator.nextInt(1, 6);

or a random decimal digit by calling::

 generator.nextInt(0, 9);

Parameters
low The low end of the range.
high The high end of the range.
Returns
  • The next random int between low and high, inclusive.

public int nextInt (int n)

Returns a pseudorandom, uniformly distributed int value between 0 (inclusive) and the specified value (exclusive), drawn from this random number generator's sequence. The general contract of nextInt is that one int value in the specified range is pseudorandomly generated and returned. All n possible int values are produced with (approximately) equal probability.

If setNextInts(int) has been called, the next available value from the provided sequence (modulo n) will be returned until that sequence is exhausted. One all provided values have been returned, then true pseudorandom generation will resume.

Parameters
n the bound on the random number to be returned. Must be positive.
Returns
  • the next pseudorandom, uniformly distributed int value between 0 (inclusive) and n (exclusive) from this random number generator's sequence
Throws
IllegalArgumentException if n is not positive

public int nextInt ()

Returns the next pseudorandom, uniformly distributed int value from this random number generator's sequence. The general contract of nextInt is that one int value is pseudorandomly generated and returned. All 232 possible int values are produced with (approximately) equal probability.

If setNextInts(int) has been called, the next available value from the provided sequence will be returned until that sequence is exhausted. One all provided values have been returned, then true pseudorandom generation will resume.

Returns
  • the next pseudorandom, uniformly distributed int value from this random number generator's sequence

public long nextLong (long low, long high)

Returns the next random long in the specified range. Behaves exactly like nextInt(int, int), but for long values.

Parameters
low The low end of the range.
high The high end of the range.
Returns
  • The next random int between low and high, inclusive.

public long nextLong ()

Returns the next pseudorandom, uniformly distributed long value from this random number generator's sequence. The general contract of nextLong is that one long value is pseudorandomly generated and returned.

If setNextLongs(long) has been called, the next available value from the provided sequence will be returned until that sequence is exhausted. One all provided values have been returned, then true pseudorandom generation will resume.

Returns
  • the next pseudorandom, uniformly distributed long value from this random number generator's sequence

public static void setNextBooleans (boolean... values)

This method allows one to provide a predefined series of values that will override the results provided by nextBoolean(). This is useful during testing, when you want to control the results generated by a random number generator. If you do not use this method, nextBoolean() behaves normally.

Note that the sequence of boolean values you provide will be shared by all instances of this class--so, no matter how many TestableRandom instances you have created, the sequence of random booleans generated by calls to their methods will be determined by what you pass in here.

If previous values from an earlier call to this method have not yet been used, they will be replaced by any parameters you provide in the next call to this method. If previous values from an earlier call to this method have not yet been used, and you provide no arguments in your next call to this method, those unused values will be replaced with nothing, so normal pseudorandom generation behavior will resume immediately.

Parameters
values a sequence of boolean values to use as the results in subsequent calls to nextBoolean()

public static void setNextBytes (byte... values)

This method allows one to provide a predefined series of values that will override the results provided by nextBytes(byte[]). This is useful during testing, when you want to control the results generated by a random number generator. If you do not use this method, nextBytes(byte[]) behaves normally.

Note that the sequence of byte values you provide will be shared by all instances of this class--so, no matter how many TestableRandom instances you have created, the sequence of random numbers generated by calls to their methods will be determined by what you pass in here.

If previous values from an earlier call to this method have not yet been used, they will be replaced by any parameters you provide in the next call to this method. If previous values from an earlier call to this method have not yet been used, and you provide no arguments in your next call to this method, those unused values will be replaced with nothing, so normal pseudorandom generation behavior will resume immediately.

Parameters
values a sequence of byte values to use as the results in subsequent calls to nextBytes(byte[])

public static void setNextDoubles (double... values)

This method allows one to provide a predefined series of values that will override the results provided by nextDouble(). This is useful during testing, when you want to control the results generated by a random number generator. If you do not use this method, nextDouble() behaves normally.

Note that the sequence of double values you provide will be shared by all instances of this class--so, no matter how many TestableRandom instances you have created, the sequence of random numbers generated by calls to their methods will be determined by what you pass in here.

If previous values from an earlier call to this method have not yet been used, they will be replaced by any parameters you provide in the next call to this method. If previous values from an earlier call to this method have not yet been used, and you provide no arguments in your next call to this method, those unused values will be replaced with nothing, so normal pseudorandom generation behavior will resume immediately.

Parameters
values a sequence of double values to use as the results in subsequent calls to nextDouble()

public static void setNextFloats (float... values)

This method allows one to provide a predefined series of values that will override the results provided by nextFloat(). This is useful during testing, when you want to control the results generated by a random number generator. If you do not use this method, nextFloat() behaves normally.

Note that the sequence of float values you provide will be shared by all instances of this class--so, no matter how many TestableRandom instances you have created, the sequence of random numbers generated by calls to their methods will be determined by what you pass in here.

If previous values from an earlier call to this method have not yet been used, they will be replaced by any parameters you provide in the next call to this method. If previous values from an earlier call to this method have not yet been used, and you provide no arguments in your next call to this method, those unused values will be replaced with nothing, so normal pseudorandom generation behavior will resume immediately.

Parameters
values a sequence of float values to use as the results in subsequent calls to nextFloat()

public static void setNextGaussians (double... values)

This method allows one to provide a predefined series of values that will override the results provided by nextGaussian(). This is useful during testing, when you want to control the results generated by a random number generator. If you do not use this method, nextGaussian() behaves normally.

Note that the sequence of double values you provide will be shared by all instances of this class--so, no matter how many TestableRandom instances you have created, the sequence of random numbers generated by calls to their methods will be determined by what you pass in here.

If previous values from an earlier call to this method have not yet been used, they will be replaced by any parameters you provide in the next call to this method. If previous values from an earlier call to this method have not yet been used, and you provide no arguments in your next call to this method, those unused values will be replaced with nothing, so normal pseudorandom generation behavior will resume immediately.

Parameters
values a sequence of double values to use as the results in subsequent calls to nextGaussian()

public static void setNextInts (int... values)

This method allows one to provide a predefined series of values that will override the results provided by nextInt() and nextInt(int). This is useful during testing, when you want to control the results generated by a random number generator. If you do not use this method, nextInt() and nextInt(int) behave normally.

Note that the sequence of int values you provide will be shared by all instances of this class--so, no matter how many TestableRandom instances you have created, the sequence of random numbers generated by calls to their methods will be determined by what you pass in here.

If previous values from an earlier call to this method have not yet been used, they will be replaced by any parameters you provide in the next call to this method. If previous values from an earlier call to this method have not yet been used, and you provide no arguments in your next call to this method, those unused values will be replaced with nothing, so normal pseudorandom generation behavior will resume immediately.

Parameters
values a sequence of int values to use as the results in subsequent calls to nextInt() or nextInt(int)

public static void setNextLongs (long... values)

This method allows one to provide a predefined series of values that will override the results provided by nextLong(). This is useful during testing, when you want to control the results generated by a random number generator. If you do not use this method, nextLong() behaves normally.

Note that the sequence of long values you provide will be shared by all instances of this class--so, no matter how many TestableRandom instances you have created, the sequence of random numbers generated by calls to their methods will be determined by what you pass in here.

If previous values from an earlier call to this method have not yet been used, they will be replaced by any parameters you provide in the next call to this method. If previous values from an earlier call to this method have not yet been used, and you provide no arguments in your next call to this method, those unused values will be replaced with nothing, so normal pseudorandom generation behavior will resume immediately.

Parameters
values a sequence of long values to use as the results in subsequent calls to nextLong()