tripleplay.util

## Class Randoms

• ```public class Randoms
extends Object```
Provides utility routines to simplify obtaining randomized values.
• ### Method Summary

All Methods
Modifier and Type Method and Description
`boolean` `getBoolean()`
Returns `true` or `false` with approximately even probability.
`boolean` `getChance(int n)`
Returns true approximately one in `n` times.
`float` `getFloat(float high)`
Returns a pseudorandom, uniformly distributed `float` value between `0.0` (inclusive) and the `high` (exclusive).
`float` ```getInRange(float low, float high)```
Returns a pseudorandom, uniformly distributed `float` value between `low` (inclusive) and `high` (exclusive).
`int` ```getInRange(int low, int high)```
Returns a pseudorandom, uniformly distributed `int` value between `low` (inclusive) and `high` (exclusive).
`int` `getInt(int high)`
Returns a pseudorandom, uniformly distributed `int` value between `0` (inclusive) and `high` (exclusive).
`float` ```getNormal(float mean, float dev)```
Returns a pseudorandom, normally distributed `float` value around the `mean` with the standard deviation `dev`.
`boolean` `getProbability(float p)`
Has a probability `p` of returning true.
`<T> T` ```pick(Iterable<? extends T> iterable, T ifEmpty)```
Pick a random element from the specified Iterable, or return `ifEmpty` if it is empty.
`<T> T` ```pick(Iterator<? extends T> iterator, T ifEmpty)```
Pick a random element from the specified Iterator, or return `ifEmpty` if it is empty.
`<T> T` ```pick(Map<? extends T,? extends Number> weightMap, T ifEmpty)```
Pick a random key from the specified mapping of weight values, or return `ifEmpty` if no mapping has a weight greater than `0`.
`<T> T` ```pluck(Iterable<? extends T> iterable, T ifEmpty)```
Pluck (remove) a random element from the specified Iterable, or return `ifEmpty` if it is empty.
`<T> void` `shuffle(List<T> list)`
Shuffle the specified list using our Random.
`static Randoms` `with(Random rand)`
A factory to create a new Randoms object.
• ### Methods inherited from class java.lang.Object

`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`
• ### Method Detail

• #### with

`public static Randoms with(Random rand)`
A factory to create a new Randoms object.
• #### getInt

`public int getInt(int high)`
Returns a pseudorandom, uniformly distributed `int` value between `0` (inclusive) and `high` (exclusive).
Parameters:
`high` - the high value limiting the random number sought.
Throws:
`IllegalArgumentException` - if `high` is not positive.
• #### getInRange

```public int getInRange(int low,
int high)```
Returns a pseudorandom, uniformly distributed `int` value between `low` (inclusive) and `high` (exclusive).
Throws:
`IllegalArgumentException` - if `high - low` is not positive.
• #### getFloat

`public float getFloat(float high)`
Returns a pseudorandom, uniformly distributed `float` value between `0.0` (inclusive) and the `high` (exclusive).
Parameters:
`high` - the high value limiting the random number sought.
• #### getInRange

```public float getInRange(float low,
float high)```
Returns a pseudorandom, uniformly distributed `float` value between `low` (inclusive) and `high` (exclusive).
• #### getChance

`public boolean getChance(int n)`
Returns true approximately one in `n` times.
Throws:
`IllegalArgumentException` - if `n` is not positive.
• #### getProbability

`public boolean getProbability(float p)`
Has a probability `p` of returning true.
• #### getBoolean

`public boolean getBoolean()`
Returns `true` or `false` with approximately even probability.
• #### getNormal

```public float getNormal(float mean,
float dev)```
Returns a pseudorandom, normally distributed `float` value around the `mean` with the standard deviation `dev`.
• #### shuffle

`public <T> void shuffle(List<T> list)`
Shuffle the specified list using our Random.
• #### pick

```public <T> T pick(Iterator<? extends T> iterator,
T ifEmpty)```
Pick a random element from the specified Iterator, or return `ifEmpty` if it is empty.

Implementation note: because the total size of the Iterator is not known, the random number generator is queried after the second element and every element thereafter.

Throws:
`NullPointerException` - if the iterator is null.
• #### pick

```public <T> T pick(Iterable<? extends T> iterable,
T ifEmpty)```
Pick a random element from the specified Iterable, or return `ifEmpty` if it is empty.

Implementation note: optimized implementations are used if the Iterable is a List or Collection. Otherwise, it behaves as if calling `pick(Iterator, Object)` with the Iterable's Iterator.

Throws:
`NullPointerException` - if the iterable is null.
• #### pick

```public <T> T pick(Map<? extends T,? extends Number> weightMap,
T ifEmpty)```
Pick a random key from the specified mapping of weight values, or return `ifEmpty` if no mapping has a weight greater than `0`. Each weight value is evaluated as a double.

Implementation note: a random number is generated for every entry with a non-zero weight after the first such entry.

Throws:
`NullPointerException` - if the map is null.
`IllegalArgumentException` - if any weight is less than 0.
• #### pluck

```public <T> T pluck(Iterable<? extends T> iterable,
T ifEmpty)```
Pluck (remove) a random element from the specified Iterable, or return `ifEmpty` if it is empty.

Implementation note: optimized implementations are used if the Iterable is a List or Collection. Otherwise, two Iterators are created from the Iterable and a random number is generated after the second element and all beyond.

Throws:
`NullPointerException` - if the iterable is null.
`UnsupportedOperationException` - if the iterable is unmodifiable or its Iterator does not support `Iterator.remove()`.