de.gurkenlabs.litiengine

Class GameRandom

java.lang.Object

java.util.Random

de.gurkenlabs.litiengine.GameRandom

All Implemented Interfaces:

java.io.Serializable

public final class GameRandom
extends java.util.Random

A random number generator instance that provides enhanced functionalities for the java default Random implementation.

See Also:

Serialized Form

Method Summary

Modifier and Type	Method and Description
<T> T	choose(java.util.Collection<T> coll) Chooses a pseudo-random element from the specified collection.
double	choose(double[] array) Chooses a pseudo-random element from the specified array.
int	choose(int[] array) Chooses a pseudo-random element from the specified array.
long	choose(long[] array) Chooses a pseudo-random element from the specified array.
<T> T	choose(T[] array) Chooses a pseudo-random element from the specified array.
int	getIndex(double[] indexProbabilities) Returns a pseudo-random index that is distributed by the weights of the defined probability array.
java.awt.geom.Point2D	getLocation(double x, double y, double width, double height) Gets a pseudo-random location within the specified boundaries.
java.awt.geom.Point2D	getLocation(java.awt.geom.Ellipse2D circle) Gets a pseudo-random location in the specified circle.
java.awt.geom.Point2D	getLocation(IEntity entity) Gets a pseudo-random location within the specified entity boundaries.
java.awt.geom.Point2D	getLocation(IMap map) Gets a pseudo-random location within the specified map boundaries.
java.awt.geom.Point2D	getLocation(java.awt.geom.Line2D line) Gets a pseudo-random location on the specified line.
java.awt.geom.Point2D	getLocation(java.awt.geom.Point2D start, java.awt.geom.Point2D end) Gets a pseudo-random location on the line connecting the two specified points.
java.awt.geom.Point2D	getLocation(java.awt.geom.Rectangle2D rect) Gets a pseudo-random location within the specified boundaries.
<T extends java.lang.Enum<?>> T	next(java.lang.Class<T> clazz)
java.lang.String	nextAlphabetic(int length) Gets a pseudo-random alphabetic String of the specified length.
java.lang.String	nextAlphabetic(int length, boolean lowerCase) Gets a pseudo-random alphabetic String of the specified length.
java.lang.String	nextAlphanumeric(int length) Gets a pseudo-random alphanumeric String of the specified length.
java.lang.String	nextAlphanumeric(int length, boolean lowerCase) Gets a pseudo-random alphanumeric String of the specified length.
java.lang.String	nextAlphanumeric(int length, boolean digit, boolean lowerCase) Gets a pseudo-random alphanumeric String of the specified length.
char	nextAscii() Gets a pseudo-random char value.
java.lang.String	nextAscii(int length) Gets a pseudo-random String of the specified length.
char	nextChar() Gets a pseudo-random char value.
char	nextChar(java.lang.String alphabet) Gets a pseudo-random char value from the specified alphabet.
double	nextDouble(double bound) Returns a pseudo-random double value between zero (inclusive) and the specified bound (exclusive).
double	nextDouble(double min, double bound) Returns a pseudo-random double value between the specified origin (inclusive) and the specified bound (exclusive).
float	nextFloat(float bound) Returns a pseudo-random float value between zero (inclusive) and the specified bound (exclusive).
float	nextFloat(float min, float bound) Returns a pseudo-random float value between the specified origin (inclusive) and the specified bound (exclusive).
int	nextInt(int min, int bound) Returns a pseudo-random int value between the specified origin (inclusive) and the specified bound (exclusive).
long	nextLong(long bound) Returns a pseudo-random long value between zero (inclusive) and the specified bound (exclusive).
long	nextLong(long min, long bound) Returns a pseudo-random long value between the specified origin (inclusive) and the specified bound (exclusive).
int	nextSign() Gets a random algebraic sign that can be used to multiply values with it.
boolean	probe(double probability) Probes a pseudo-random value between 0.0 and 1.0 and checks whether it matches the specified probability.
<T> java.util.Collection<T>	sample(java.util.Collection<T> collection, int amount, boolean replacement)
<T> T[]	sample(T[] array, int amount, boolean replacement)
void	setSeed(java.lang.String seed) Sets the seed of this random number generator using a String seed.
void	shuffle(double[] array) Shuffles the elements in the specified array.
void	shuffle(int[] array) Shuffles the elements in the specified array.
<T> void	shuffle(java.util.List<T> coll) Shuffles the elements in the specified collection.
void	shuffle(long[] array) Shuffles the elements in the specified array.
<T> void	shuffle(T[] array) Shuffles the elements in the specified array.
double	shuffleSign(double value) Shuffles the algebraic sign of the specified double value.
float	shuffleSign(float value) Shuffles the algebraic sign of the specified float value.
int	shuffleSign(int value) Shuffles the algebraic sign of the specified int value.
long	shuffleSign(long value) Shuffles the algebraic sign of the specified long value.

Methods inherited from class java.util.Random

doubles, doubles, doubles, doubles, ints, ints, ints, ints, longs, longs, longs, longs, next, nextBoolean, nextBytes, nextDouble, nextFloat, nextGaussian, nextInt, nextInt, nextLong, setSeed

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

setSeed

public void setSeed(java.lang.String seed)

Sets the seed of this random number generator using a String seed.

Parameters:

seed - The initial seed.

See Also:

Random.setSeed(long)

sample

public <T> T[] sample(T[] array,
                      int amount,
                      boolean replacement)

sample

public <T> java.util.Collection<T> sample(java.util.Collection<T> collection,
                                          int amount,
                                          boolean replacement)

choose

public <T> T choose(T[] array)

Chooses a pseudo-random element from the specified array.

Type Parameters:

T - The type of the elements in the array.

Parameters:

array - The array to choose from.

Returns:

A pseudo-random element from the array or null if the array is empty.

choose

public int choose(int[] array)

Chooses a pseudo-random element from the specified array.

Parameters:

array - The array to choose from.

Returns:

A pseudo-random element from the array or 0 if the array is empty.

Throws:

java.lang.IllegalArgumentException - When the specified array is null or empty.

choose

public long choose(long[] array)

Chooses a pseudo-random element from the specified array.

Parameters:

array - The array to choose from.

Returns:

A pseudo-random element from the array or 0 if the array is empty.

Throws:

java.lang.IllegalArgumentException - When the specified array is null or empty.

choose

public double choose(double[] array)

Chooses a pseudo-random element from the specified array.

Parameters:

array - The array to choose from.

Returns:

A pseudo-random element from the array or 0 if the array is empty.

Throws:

java.lang.IllegalArgumentException - When the specified array is null or empty.

choose

public <T> T choose(java.util.Collection<T> coll)

Chooses a pseudo-random element from the specified collection.

Type Parameters:

T - The type of the elements in the collection.

Parameters:

coll - The collection to choose from.

Returns:

A pseudo-random element from the array or null if the collection is empty.

shuffle

public <T> void shuffle(T[] array)

Shuffles the elements in the specified array.

Type Parameters:

T - The type of the elements in the collection.

Parameters:

array - The array to be shuffled.

shuffle

public void shuffle(int[] array)

Shuffles the elements in the specified array.

Parameters:

array - The array to be shuffled.

shuffle

public void shuffle(long[] array)

Shuffles the elements in the specified array.

Parameters:

array - The array to be shuffled.

shuffle

public void shuffle(double[] array)

Shuffles the elements in the specified array.

Parameters:

array - The array to be shuffled.

shuffle

public <T> void shuffle(java.util.List<T> coll)

Shuffles the elements in the specified collection.

Type Parameters:

T - The type of the elements in the collection.

Parameters:

coll - The collection to be shuffled.

nextSign

public int nextSign()

Gets a random algebraic sign that can be used to multiply values with it.

This either returns 1 or -1 depending on the random outcome.

Returns:

A random sign for algebraic operations.

shuffleSign

public int shuffleSign(int value)

Shuffles the algebraic sign of the specified int value.

Parameters:

value - The value to shuffle.

Returns:

Either the specified value; or its negative equivalent (multiplied by -1).

See Also:

nextSign()

shuffleSign

public float shuffleSign(float value)

Shuffles the algebraic sign of the specified float value.

Parameters:

value - The value to shuffle.

Returns:

Either the specified value; or its negative equivalent (multiplied by -1).

See Also:

nextSign()

shuffleSign

public long shuffleSign(long value)

Shuffles the algebraic sign of the specified long value.

Parameters:

value - The value to shuffle.

Returns:

Either the specified value; or its negative equivalent (multiplied by -1).

See Also:

nextSign()

shuffleSign

public double shuffleSign(double value)

Shuffles the algebraic sign of the specified double value.

Parameters:

value - The value to shuffle.

Returns:

Either the specified value; or its negative equivalent (multiplied by -1).

See Also:

nextSign()

nextLong

public long nextLong(long bound)

Returns a pseudo-random long value between zero (inclusive) and the specified bound (exclusive).

Parameters:

bound - the upper bound (exclusive). Must be positive.

Returns:

a pseudo-random long value between zero (inclusive) and the bound (exclusive)

Throws:

java.lang.IllegalArgumentException - if bound is not positive

nextLong

public long nextLong(long min,
                     long bound)

Returns a pseudo-random long value between the specified origin (inclusive) and the specified bound (exclusive).

Parameters:

min - the least value returned

bound - the upper bound (exclusive)

Returns:

a pseudo-random long value between the origin (inclusive) and the bound (exclusive)

Throws:

java.lang.IllegalArgumentException - if origin is greater than bound

nextDouble

public double nextDouble(double bound)

Returns a pseudo-random double value between zero (inclusive) and the specified bound (exclusive).

Parameters:

bound - the upper bound (exclusive). Must be positive.

Returns:

a pseudo-random double value between zero (inclusive) and the bound (exclusive)

Throws:

java.lang.IllegalArgumentException - if bound is not positive

nextDouble

public double nextDouble(double min,
                         double bound)

Returns a pseudo-random double value between the specified origin (inclusive) and the specified bound (exclusive).

Parameters:

min - the least value returned

bound - the upper bound (exclusive)

Returns:

a pseudo-random double value between the origin (inclusive) and the bound (exclusive)

Throws:

java.lang.IllegalArgumentException - if origin is greater than bound

nextFloat

public float nextFloat(float bound)

Returns a pseudo-random float value between zero (inclusive) and the specified bound (exclusive).

Parameters:

bound - the upper bound (exclusive). Must be positive.

Returns:

a pseudo-random float value between zero (inclusive) and the bound (exclusive)

Throws:

java.lang.IllegalArgumentException - if bound is not positive

nextFloat

public float nextFloat(float min,
                       float bound)

Returns a pseudo-random float value between the specified origin (inclusive) and the specified bound (exclusive).

Parameters:

min - the least value returned

bound - the upper bound (exclusive)

Returns:

a pseudo-random float value between the origin (inclusive) and the bound (exclusive)

Throws:

java.lang.IllegalArgumentException - if origin is greater than bound

nextInt

public int nextInt(int min,
                   int bound)

Returns a pseudo-random int value between the specified origin (inclusive) and the specified bound (exclusive).

Parameters:

min - the least value returned

bound - the upper bound (exclusive)

Returns:

a pseudo-random int value between the origin (inclusive) and the bound (exclusive)

Throws:

java.lang.IllegalArgumentException - if origin is greater than bound

next

public <T extends java.lang.Enum<?>> T next(java.lang.Class<T> clazz)

probe

public boolean probe(double probability)

Probes a pseudo-random value between 0.0 and 1.0 and checks whether it matches the specified probability.

Example: if the specified probability is 0.5, the sampled value needs to be less than or equal to the specified value in order for this method to return true.

Parameters:

probability - The probability to check.

Returns:

True if the sampled value matches the probability; otherwise false.

getIndex

public int getIndex(double[] indexProbabilities)

Returns a pseudo-random index that is distributed by the weights of the defined probability array. The index probabilities must sum up to 1;

Parameters:

indexProbabilities - The index with the probabilities for the related index.

Returns:

A random index within the range of the specified array.

getLocation

public java.awt.geom.Point2D getLocation(double x,
                                         double y,
                                         double width,
                                         double height)

Gets a pseudo-random location within the specified boundaries.

Parameters:

x - The min-x coordinate of the boundaries.

y - The min-y coordinate of the boundaries.

width - The width of the boundaries.

height - The height of the boundaries.

Returns:

A pseudo-random location within the specified bounds.

getLocation

public java.awt.geom.Point2D getLocation(java.awt.geom.Rectangle2D rect)

Gets a pseudo-random location within the specified boundaries.

Parameters:

rect - The rectangle that defines the boundaries.

Returns:

A pseudo-random location within the specified bounds.

getLocation

public java.awt.geom.Point2D getLocation(IEntity entity)

Gets a pseudo-random location within the specified entity boundaries.

Parameters:

entity - The entity that defines the boundaries.

Returns:

A pseudo-random location within the specified bounds.

See Also:

IEntity.getBoundingBox()

getLocation

public java.awt.geom.Point2D getLocation(IMap map)

Gets a pseudo-random location within the specified map boundaries.

Parameters:

map - The map that defines the boundaries.

Returns:

A pseudo-random location within the specified bounds.

See Also:

IMap.getBounds()

getLocation

public java.awt.geom.Point2D getLocation(java.awt.geom.Ellipse2D circle)

Gets a pseudo-random location in the specified circle.

Parameters:

circle - The circle that defines the boundaries.

Returns:

A pseudo-random location on the specified circle.

getLocation

public java.awt.geom.Point2D getLocation(java.awt.geom.Line2D line)

Gets a pseudo-random location on the specified line.

Parameters:

line - The line that defines the boundaries.

Returns:

A pseudo-random location on the specified line.

See Also:

Line2D.getP1(), Line2D.getP2()

getLocation

public java.awt.geom.Point2D getLocation(java.awt.geom.Point2D start,
                                         java.awt.geom.Point2D end)

Gets a pseudo-random location on the line connecting the two specified points.

Parameters:

start - The start point.

end - The end point.

Returns:

A pseudo-random location on the line connecting the two specified points.

nextChar

public char nextChar()

Gets a pseudo-random char value.

Returns:

A pseudo-random character.

nextChar

public char nextChar(java.lang.String alphabet)

Gets a pseudo-random char value from the specified alphabet.

Parameters:

alphabet - The alphabet to chose the character from.

Returns:

A pseudo-random character from the specified alphabet.

nextAscii

public char nextAscii()

Gets a pseudo-random char value.

Returns:

A pseudo-random character.

nextAscii

public java.lang.String nextAscii(int length)

Gets a pseudo-random String of the specified length.

Characters will be chosen from the set of characters whose ASCII value is between 32 and 126 (inclusive)

Parameters:

length - The length of the String.

Returns:

A pseudo-random ASCII String.

nextAlphanumeric

public java.lang.String nextAlphanumeric(int length)

Gets a pseudo-random alphanumeric String of the specified length.

Parameters:

length - The length of the String.

Returns:

A pseudo-random alphanumeric String.

nextAlphanumeric

public java.lang.String nextAlphanumeric(int length,
                                         boolean lowerCase)

Gets a pseudo-random alphanumeric String of the specified length.

Parameters:

length - The length of the String.

lowerCase - Indicates whether lower-case letters will be included in the String.

Returns:

A pseudo-random alphanumeric String.

nextAlphanumeric

public java.lang.String nextAlphanumeric(int length,
                                         boolean digit,
                                         boolean lowerCase)

Gets a pseudo-random alphanumeric String of the specified length.

Parameters:

length - The length of the String.

digit - Indicates whether digits will be included in the string.

lowerCase - Indicates whether lower-case letters will be included in the String.

Returns:

A pseudo-random alphanumeric String.

nextAlphabetic

public java.lang.String nextAlphabetic(int length)

Gets a pseudo-random alphabetic String of the specified length.

Parameters:

length - The length of the String.

Returns:

A pseudo-random alphabetic String.

nextAlphabetic

public java.lang.String nextAlphabetic(int length,
                                       boolean lowerCase)

Gets a pseudo-random alphabetic String of the specified length.

Parameters:

length - The length of the String.

lowerCase - Indicates whether lower-case letters will be included in the String.

Returns:

A pseudo-random alphabetic String.