squidpony.squidmath

Interface IRNG

All Superinterfaces:

RandomnessSource, java.io.Serializable

All Known Subinterfaces:

IStatefulRNG

All Known Implementing Classes:

AbstractRNG, CriticalRNG, DeckRNG, DharmaRNG, DistributedRNG, EditRNG, GWTRNG, MoonwalkRNG, RNG, SilkRNG, StatefulRNG, TweakRNG

public interface IRNG
extends RandomnessSource

Interface for full-featured random number generators to implement (it does more than, and includes all of, RandomnessSource). It's a stripped down version of the original RNG. It's an interface instead of a class, to be able to implement using random number generators that don't implement RandomnessSource, like libGDX's RandomXS128, or to hard-code the RandomnessSource to avoid overhead or use some methods differently (like preferring 32-bit math or optimizing for GWT, as GWTRNG does). You can use any IRNG as a RandomnessSource, but that only allows its next(int), nextLong(), and RandomnessSource.copy() methods to be called, so most usage that can benefit from methods like nextDouble() or between(int, int) should prefer IRNG for parameter types.

Method Summary

Modifier and Type	Method and Description
double	between(double min, double max) Returns a value from a uniform distribution from min (inclusive) to max (exclusive).
int	between(int min, int max) Returns a value between min (inclusive) and max (exclusive) as ints.
long	between(long min, long max) Returns a value between min (inclusive) and max (exclusive) as longs.
<T> T	getRandomElement(java.util.Collection<T> coll) Returns a random element from the provided Collection, which should have predictable iteration order if you want predictable behavior for identical RNG seeds, though it will get a random element just fine for any Collection (just not predictably in all cases).
<T> T	getRandomElement(java.util.List<T> list) Returns a random element from the provided list.
<T> T	getRandomElement(T[] array) Returns a random element from the provided array and maintains object type.
int	next(int bits) Get up to 32 bits (inclusive) of random output; the int this produces will not require more than bits bits to represent.
boolean	nextBoolean() Get a random bit of state, interpreted as true or false with approximately equal likelihood.
double	nextDouble() Gets a random double between 0.0 inclusive and 1.0 exclusive.
double	nextDouble(double outer) This returns a random double between 0.0 (inclusive) and outer (exclusive).
float	nextFloat() Gets a random float between 0.0f inclusive and 1.0f exclusive.
float	nextFloat(float outer) This returns a random float between 0.0f (inclusive) and outer (exclusive).
int	nextInt() Get a random integer between Integer.MIN_VALUE to Integer.MAX_VALUE (both inclusive).
int	nextInt(int bound) Returns a random non-negative integer below the given bound, or 0 if the bound is 0 or negative.
long	nextLong() Get a random long between Long.MIN_VALUE to Long.MAX_VALUE (both inclusive).
long	nextLong(long bound) Returns a random long below the given bound, or 0 if the bound is 0 or negative.
int	nextSignedInt(int outerBound) Returns a random non-negative integer between 0 (inclusive) and the given bound (exclusive), or 0 if the bound is 0.
long	nextSignedLong(long outerBound) Exclusive on bound (which may be positive or negative), with an inner bound of 0.
int[]	randomOrdering(int length) Generates a random permutation of the range from 0 (inclusive) to length (exclusive).
int[]	randomOrdering(int length, int[] dest) Generates a random permutation of the range from 0 (inclusive) to length (exclusive) and stores it in the dest parameter, avoiding allocations.
<T> T[]	randomPortion(T[] data, T[] output) Gets a random portion of data (an array), assigns that portion to output (an array) so that it fills as much as it can, and then returns output.
<T> java.util.ArrayList<T>	shuffle(java.util.Collection<T> elements) Shuffles a Collection of T using the Fisher-Yates algorithm and returns an ArrayList of T.
<T> java.util.ArrayList<T>	shuffle(java.util.Collection<T> elements, java.util.ArrayList<T> buf) Shuffles a Collection of T using the Fisher-Yates algorithm and puts it in a buffer.
<T> T[]	shuffle(T[] elements) Shuffle an array using the Fisher-Yates algorithm and returns a shuffled copy, freshly-allocated, without modifying elements.
<T> T[]	shuffle(T[] elements, T[] dest) Shuffle an array using the Fisher-Yates algorithm.
<T> java.util.List<T>	shuffleInPlace(java.util.List<T> elements) Shuffles a Collection of T items in-place using the Fisher-Yates algorithm.
<T> T[]	shuffleInPlace(T[] elements) Shuffles an array in-place using the Fisher-Yates algorithm.
java.io.Serializable	toSerializable() Gets a view of this IRNG in a way that implements Serializable, which may simply be this IRNG if it implements Serializable as well as IRNG.

Methods inherited from interface squidpony.squidmath.RandomnessSource

copy

Method Detail

next

int next(int bits)

Get up to 32 bits (inclusive) of random output; the int this produces will not require more than bits bits to represent.

Specified by:

next in interface RandomnessSource

Parameters:

bits - an int between 1 and 32, both inclusive

Returns:

a random number that fits in the specified number of bits

nextInt

int nextInt()

Get a random integer between Integer.MIN_VALUE to Integer.MAX_VALUE (both inclusive).

Returns:

a 32-bit random int.

nextInt

int nextInt(int bound)

Returns a random non-negative integer below the given bound, or 0 if the bound is 0 or negative.

Parameters:

bound - the upper bound (exclusive)

Returns:

the found number

nextLong

long nextLong()

Get a random long between Long.MIN_VALUE to Long.MAX_VALUE (both inclusive).

Specified by:

nextLong in interface RandomnessSource

Returns:

a 64-bit random long.

nextLong

long nextLong(long bound)

Returns a random long below the given bound, or 0 if the bound is 0 or negative.

Parameters:

bound - the upper bound (exclusive)

Returns:

the found number

nextBoolean

boolean nextBoolean()

Get a random bit of state, interpreted as true or false with approximately equal likelihood.

Returns:

a random boolean.

nextDouble

double nextDouble()

Gets a random double between 0.0 inclusive and 1.0 exclusive. This returns a maximum of 0.9999999999999999 because that is the largest double value that is less than 1.0 .

Returns:

a double between 0.0 (inclusive) and 0.9999999999999999 (inclusive)

nextDouble

double nextDouble(double outer)

This returns a random double between 0.0 (inclusive) and outer (exclusive). The value for outer can be positive or negative. Because of how math on doubles works, there are at most 2 to the 53 values this can return for any given outer bound, and very large values for outer will not necessarily produce all numbers you might expect.

Parameters:

outer - the outer exclusive bound as a double; can be negative or positive

Returns:

a double between 0.0 (inclusive) and outer (exclusive)

nextFloat

float nextFloat()

Gets a random float between 0.0f inclusive and 1.0f exclusive. This returns a maximum of 0.99999994 because that is the largest float value that is less than 1.0f .

Returns:

a float between 0f (inclusive) and 0.99999994f (inclusive)

nextFloat

float nextFloat(float outer)

This returns a random float between 0.0f (inclusive) and outer (exclusive). The value for outer can be positive or negative. Because of how math on floats works, there are at most 2 to the 24 values this can return for any given outer bound, and very large values for outer will not necessarily produce all numbers you might expect.

Parameters:

outer - the outer exclusive bound as a float; can be negative or positive

Returns:

a float between 0f (inclusive) and outer (exclusive)

nextSignedLong

long nextSignedLong(long outerBound)

Exclusive on bound (which may be positive or negative), with an inner bound of 0. If bound is negative this returns a negative long; if bound is positive this returns a positive long. The bound can even be 0, which will cause this to return 0L every time. This uses a biased technique to get numbers from large ranges, but the amount of bias is incredibly small (expected to be under 1/1000 if enough random ranged numbers are requested, which is about the same as an unbiased method that was also considered). It may have noticeable bias if the generator's period is exhausted by only calls to this method. Unlike all unbiased methods, this advances the state by an equivalent to exactly one call to nextLong(), where rejection sampling would sometimes advance by one call, but other times by arbitrarily many more.

Parameters:

outerBound - the outer exclusive bound; can be positive or negative

Returns:

a random long between 0 (inclusive) and bound (exclusive)

nextSignedInt

int nextSignedInt(int outerBound)

Returns a random non-negative integer between 0 (inclusive) and the given bound (exclusive), or 0 if the bound is 0. The bound can be negative, which will produce 0 or a negative result.
Credit goes to Daniel Lemire, http://lemire.me/blog/2016/06/27/a-fast-alternative-to-the-modulo-reduction/

Parameters:

outerBound - the outer bound (exclusive), can be negative or positive

Returns:

the found number

between

int between(int min,
            int max)

Returns a value between min (inclusive) and max (exclusive) as ints.
The inclusive and exclusive behavior is to match the behavior of the similar method that deals with floating point values.
If min and max happen to be the same, min is returned (breaking the exclusive behavior, but it's convenient to do so).

Parameters:

min - the minimum bound on the return value (inclusive)

max - the maximum bound on the return value (exclusive)

Returns:

the found value

between

long between(long min,
             long max)

Returns a value between min (inclusive) and max (exclusive) as longs.
The inclusive and exclusive behavior is to match the behavior of the similar method that deals with floating point values.
If min and max happen to be the same, min is returned (breaking the exclusive behavior, but it's convenient to do so).

Parameters:

min - the minimum bound on the return value (inclusive)

max - the maximum bound on the return value (exclusive)

Returns:

the found value

between

double between(double min,
               double max)

Returns a value from a uniform distribution from min (inclusive) to max (exclusive).

Parameters:

min - the minimum bound on the return value (inclusive)

max - the maximum bound on the return value (exclusive)

Returns:

the found value

getRandomElement

<T> T getRandomElement(T[] array)

Returns a random element from the provided array and maintains object type.

Type Parameters:

T - the type of the returned object

Parameters:

array - the array to get an element from

Returns:

the randomly selected element

getRandomElement

<T> T getRandomElement(java.util.List<T> list)

Returns a random element from the provided list. If the list is empty then null is returned.

Type Parameters:

T - the type of the returned object

Parameters:

list - the list to get an element from

Returns:

the randomly selected element

getRandomElement

<T> T getRandomElement(java.util.Collection<T> coll)

Returns a random element from the provided Collection, which should have predictable iteration order if you want predictable behavior for identical RNG seeds, though it will get a random element just fine for any Collection (just not predictably in all cases). If you give this a Set, it should be a LinkedHashSet or some form of sorted Set like TreeSet if you want predictable results. Any List or Queue should be fine. Map does not implement Collection, thank you very much Java library designers, so you can't actually pass a Map to this, though you can pass the keys or values. If coll is empty, returns null.
Requires iterating through a random amount of coll's elements, so performance depends on the size of coll but is likely to be decent, as long as iteration isn't unusually slow. This replaces getRandomElement(Queue), since Queue implements Collection and the older Queue-using implementation was probably less efficient.
You should generally prefer getRandomElement(List) whenever possible, or in some cases you can use methods that get a random value on the Collection (or Map, in the case of OrderedMap) itself.

Type Parameters:

T - the type of the returned object

Parameters:

coll - the Collection to get an element from; remember, Map does not implement Collection

Returns:

the randomly selected element

shuffle

<T> T[] shuffle(T[] elements)

Shuffle an array using the Fisher-Yates algorithm and returns a shuffled copy, freshly-allocated, without modifying elements.
Wikipedia has more on this algorithm.

Type Parameters:

T - can be any non-primitive type.

Parameters:

elements - an array of T; will not be modified

Returns:

a shuffled copy of elements

shuffleInPlace

<T> T[] shuffleInPlace(T[] elements)

Shuffles an array in-place using the Fisher-Yates algorithm. If you don't want the array modified, use shuffle(Object[], Object[]).
Wikipedia has more on this algorithm.

Type Parameters:

T - can be any non-primitive type.

Parameters:

elements - an array of T; will be modified

Returns:

elements after shuffling it in-place

shuffle

<T> T[] shuffle(T[] elements,
                T[] dest)

Shuffle an array using the Fisher-Yates algorithm. DO NOT give the same array for both elements and dest, since the prior contents of dest are rearranged before elements is used, and if they refer to the same array, then you can end up with bizarre bugs where one previously-unique item shows up dozens of times. If possible, create a new array with the same length as elements and pass it in as dest; the returned value can be assigned to whatever you want and will have the same items as the newly-formed array.
Wikipedia has more on this algorithm.

Type Parameters:

T - can be any non-primitive type.

Parameters:

elements - an array of T; will not be modified

dest - Where to put the shuffle. If it does not have the same length as elements, this will use the randomPortion method of this class to fill the smaller dest. MUST NOT be the same array as elements!

Returns:

dest after modifications

shuffle

<T> java.util.ArrayList<T> shuffle(java.util.Collection<T> elements)

Shuffles a Collection of T using the Fisher-Yates algorithm and returns an ArrayList of T.
Wikipedia has more on this algorithm.

Type Parameters:

T - can be any non-primitive type.

Parameters:

elements - a Collection of T; will not be modified

Returns:

a shuffled ArrayList containing the whole of elements in pseudo-random order.

shuffle

<T> java.util.ArrayList<T> shuffle(java.util.Collection<T> elements,
                                   java.util.ArrayList<T> buf)

Shuffles a Collection of T using the Fisher-Yates algorithm and puts it in a buffer. The result is allocated if buf is null or if buf isn't empty, otherwise elements is poured into buf.
Wikipedia has more on this algorithm.

Type Parameters:

T - can be any non-primitive type.

Parameters:

elements - a Collection of T; will not be modified

buf - a buffer as an ArrayList that will be filled with the shuffled contents of elements; if null or non-empty, a new ArrayList will be allocated and returned

Returns:

a shuffled ArrayList containing the whole of elements in pseudo-random order, which may be buf

shuffleInPlace

<T> java.util.List<T> shuffleInPlace(java.util.List<T> elements)

Shuffles a Collection of T items in-place using the Fisher-Yates algorithm. This only shuffles List data structures. If you don't want the array modified, use shuffle(Collection), which returns a List as well.
Wikipedia has more on this algorithm.

Type Parameters:

T - can be any non-primitive type.

Parameters:

elements - a Collection of T; will be modified

Returns:

elements after shuffling it in-place

randomOrdering

int[] randomOrdering(int length)

Generates a random permutation of the range from 0 (inclusive) to length (exclusive). Useful for passing to OrderedMap or OrderedSet's reorder() methods.

Parameters:

length - the size of the ordering to produce

Returns:

a random ordering containing all ints from 0 to length (exclusive)

randomOrdering

int[] randomOrdering(int length,
                     int[] dest)

Generates a random permutation of the range from 0 (inclusive) to length (exclusive) and stores it in the dest parameter, avoiding allocations. Useful for passing to OrderedMap or OrderedSet's reorder() methods.

Parameters:

length - the size of the ordering to produce

dest - the destination array; will be modified

Returns:

dest, filled with a random ordering containing all ints from 0 to length (exclusive)

randomPortion

<T> T[] randomPortion(T[] data,
                      T[] output)

Gets a random portion of data (an array), assigns that portion to output (an array) so that it fills as much as it can, and then returns output. Will only use a given position in the given data at most once.

Type Parameters:

T - can be any non-primitive type.

Parameters:

data - an array of T; will not be modified.

output - an array of T that will be overwritten; should always be instantiated with the portion length

Returns:

output, after Math.min(output.length, data.length) unique items have been put into it from data

toSerializable

java.io.Serializable toSerializable()

Gets a view of this IRNG in a way that implements Serializable, which may simply be this IRNG if it implements Serializable as well as IRNG.
For implementors: It is suggested to return an RNG initialized by calling RNG(long) with nextLong() if you are unable to save the current state of this IRNG and the caller still needs something saved. This won't preserve the current state or the choice of IRNG implementation, however, so it is simply a last resort in case you don't want to throw an exception.

Returns:

a Serializable view of this IRNG or a similar one; may be this