ProbabilityTable (squidlib-util 3.0.6 API)

java.lang.Object
- squidpony.squidmath.ProbabilityTable<T>

Type Parameters:

T - The type of object to be held in the table

All Implemented Interfaces:

java.io.Serializable
```
public class ProbabilityTable<T>
extends java.lang.Object
implements java.io.Serializable
```
A generic method of holding a probability table to determine weighted random outcomes.
The weights do not need to add up to any particular value; they will be normalized when choosing a random entry. This class allows adding T items and the weights for those items after the ProbabilityTable has been constructed with add(Object, int) or addAll(OrderedMap), as well as removing items entirely with remove(Object) or adjusting the weight for an existing item with add(Object, int) or remove(Object, int). You can also add a nested ProbabilityTable, which has its own weight and can be chosen like any other item, except it makes its own random choice of its own T items; you can use the nested table with add(ProbabilityTable, int) and addAllNested(OrderedMap). Actually getting a randomly-selected item is easy; just use random().

See Also:

An alternative for when you want to track the items separately from their weights, and don't need nested tables., Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`java.util.ArrayList<ProbabilityTable<T>>`	`extraTable` The list of items that can be produced indirectly from `random()` (looking up values from inside the nested tables).
`protected int`	`normalTotal`
`GWTRNG`	`rng`
`Arrangement<T>`	`table` The set of items that can be produced directly from `random()` (without additional lookups).
`protected int`	`total`
`IntVLA`	`weights`

Constructor Summary

Constructors
Constructor and Description
`ProbabilityTable()` Creates a new probability table with a random seed.
`ProbabilityTable(long seed)` Creates a new probability table with the provided long seed used.
`ProbabilityTable(RandomnessSource rng)` Creates a new probability table with the provided source of randomness used.
`ProbabilityTable(java.lang.String seed)` Creates a new probability table with the provided String seed used.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`ProbabilityTable<T>`	`add(ProbabilityTable<T> table, int weight)` Adds the given probability table as a possible set of results for this table.
`ProbabilityTable<T>`	`add(T item, int weight)` Adds the given item to the table.
`ProbabilityTable<T>`	`addAll(OrderedMap<T,java.lang.Integer> itemsAndWeights)` Given an OrderedMap of T element keys and Integer weight values, adds all T keys with their corresponding weights into this ProbabilityTable.
`ProbabilityTable<T>`	`addAllNested(OrderedMap<ProbabilityTable<T>,java.lang.Integer> itemsAndWeights)` Given an OrderedMap of ProbabilityTable keys and Integer weight values, adds all keys as nested tables with their corresponding weights into this ProbabilityTable.
`boolean`	`contentEquals(ProbabilityTable<T> o)` Can avoid some checks that `equals(Object)` needs because this always takes a ProbabilityTable.
`ProbabilityTable<T>`	`copy()` Copies this ProbabilityTable so nothing in the copy is shared with the original, except for the T items (which might not be possible to copy).
`boolean`	`equals(java.lang.Object o)`
`GWTRNG`	`getRandom()` Gets the random number generator (a RandomnessSource) this uses.
`int`	`hashCode()`
`OrderedSet<T>`	`items()` Provides a set of the items in this table, without reference to their weight.
`T`	`random()` Returns an object randomly based on assigned weights.
`boolean`	`remove(T item)` Removes the possibility of generating the given T item, except by nested ProbabilityTable results.
`boolean`	`remove(T item, int weight)` Reduces the likelihood of generating the given T item by the given weight, which can reduce the chance below 0 and thus remove the item entirely.
`boolean`	`removeAll(java.lang.Iterable<T> items)` Given an Iterable of T item keys to remove, this tries to remove each item in items, though it can't affect items in nested ProbabilityTables, and returns true if any probabilities were changed.
`boolean`	`removeAll(OrderedMap<T,java.lang.Integer> itemsAndWeights)` Given an OrderedMap of T item keys and Integer weight values, reduces the weights in this ProbabilityTable for all T keys by their corresponding weights, removing them if the weight becomes 0 or less.
`void`	`setRandom(GWTRNG random)` Sets the current random number generator to the given GWTRNG.
`java.util.SortedSet<T>`	`simpleItems()` Provides a set of the items in this table that are not in nested tables, without reference to their weight.
`java.util.ArrayList<ProbabilityTable<T>>`	`tables()` Provides a set of the nested ProbabilityTable values in this table, without reference to their weight.
`int`	`weight(ProbabilityTable<T> item)` Returns the weight of the extra table if present.
`int`	`weight(T item)` Returns the weight of the item if the item is in the table.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - table
```
public final Arrangement<T> table
```
    The set of items that can be produced directly from random() (without additional lookups).
  - extraTable
```
public final java.util.ArrayList<ProbabilityTable<T>> extraTable
```
    The list of items that can be produced indirectly from random() (looking up values from inside the nested tables).
  - weights
```
public final IntVLA weights
```
  - rng
```
public GWTRNG rng
```
  - total
```
protected int total
```
  - normalTotal
```
protected int normalTotal
```
- Constructor Detail
  - ProbabilityTable
```
public ProbabilityTable()
```
    Creates a new probability table with a random seed.
  - ProbabilityTable
```
public ProbabilityTable(RandomnessSource rng)
```
    Creates a new probability table with the provided source of randomness used.
    
    Parameters:
    
    rng - the source of randomness
  - ProbabilityTable
```
public ProbabilityTable(long seed)
```
    Creates a new probability table with the provided long seed used.
    
    Parameters:
    
    seed - the RNG seed as a long
  - ProbabilityTable
```
public ProbabilityTable(java.lang.String seed)
```
    Creates a new probability table with the provided String seed used.
    
    Parameters:
    
    seed - the RNG seed as a String
- Method Detail
  - random
```
public T random()
```
    Returns an object randomly based on assigned weights. Returns null if no elements have been put in the table.
    
    Returns:
    
    the chosen object or null
  - add
```
public ProbabilityTable<T> add(T item,
                               int weight)
```
    Adds the given item to the table. Weight must be greater than 0.
    
    Parameters:
    
    item - the object to be added
    
    weight - the weight to be given to the added object
    
    Returns:
    
    this for chaining
  - addAll
```
public ProbabilityTable<T> addAll(OrderedMap<T,java.lang.Integer> itemsAndWeights)
```
    Given an OrderedMap of T element keys and Integer weight values, adds all T keys with their corresponding weights into this ProbabilityTable. You may want to use OrderedMap.makeMap(Object, Object, Object...) to produce the parameter, unless you already have one.
    
    Parameters:
    
    itemsAndWeights - an OrderedMap of T keys to Integer values, where a key will be an item this can retrieve and a value will be its weight
    
    Returns:
    
    this for chaining
  - remove
```
public boolean remove(T item)
```
    Removes the possibility of generating the given T item, except by nested ProbabilityTable results. Returns true iff the item was removed.
    
    Parameters:
    
    item - the item to make less likely or impossible
    
    Returns:
    
    true if the probability changed or false if nothing changed
  - remove
```
public boolean remove(T item,
                      int weight)
```
    Reduces the likelihood of generating the given T item by the given weight, which can reduce the chance below 0 and thus remove the item entirely. Does not affect nested ProbabilityTables. The value for weight must be greater than 0, otherwise this simply returns false without doing anything. Returns true iff the probabilities changed.
    
    Parameters:
    
    item - the item to make less likely or impossible
    
    weight - how much to reduce the item's weight by, as a positive non-zero int (greater values here subtract more from the item's weight)
    
    Returns:
    
    true if the probability changed or false if nothing changed
  - removeAll
```
public boolean removeAll(java.lang.Iterable<T> items)
```
    Given an Iterable of T item keys to remove, this tries to remove each item in items, though it can't affect items in nested ProbabilityTables, and returns true if any probabilities were changed.
    
    Parameters:
    
    items - an Iterable of T items that will all be removed from the normal (non-nested) items in this
    
    Returns:
    
    true if the probabilities changed, or false otherwise
  - removeAll
```
public boolean removeAll(OrderedMap<T,java.lang.Integer> itemsAndWeights)
```
    Given an OrderedMap of T item keys and Integer weight values, reduces the weights in this ProbabilityTable for all T keys by their corresponding weights, removing them if the weight becomes 0 or less. You may want to use OrderedMap.makeMap(Object, Object, Object...) to produce the parameter, unless you already have one. Returns true iff the probabilities changed.
    
    Parameters:
    
    itemsAndWeights - an OrderedMap of T keys to Integer values, where a key will be an item that should be reduced in weight or removed and a value will be that item's weight
    
    Returns:
    
    true if the probabilities changed or false otherwise
  - add
```
public ProbabilityTable<T> add(ProbabilityTable<T> table,
                               int weight)
```
    Adds the given probability table as a possible set of results for this table. The table parameter should not be the same object as this ProbabilityTable, nor should it contain cycles that could reference this object from inside the values of table. This could cause serious issues that would eventually terminate in a StackOverflowError if the cycles randomly repeated for too long. Only the first case is checked for (if the contents of this and table are equivalent, it returns without doing anything; this also happens if table is empty or null). Weight must be greater than 0.
    
    Parameters:
    
    table - the ProbabilityTable to be added; should not be the same as this object (avoid cycles)
    
    weight - the weight to be given to the added table
    
    Returns:
    
    this for chaining
  - addAllNested
```
public ProbabilityTable<T> addAllNested(OrderedMap<ProbabilityTable<T>,java.lang.Integer> itemsAndWeights)
```
    Given an OrderedMap of ProbabilityTable keys and Integer weight values, adds all keys as nested tables with their corresponding weights into this ProbabilityTable. All ProbabilityTable keys should have the same T type as this ProbabilityTable. You may want to use OrderedMap.makeMap(Object, Object, Object...) to produce the parameter, unless you already have one. The same rules apply to this as apply to add(ProbabilityTable, int); that is, no key in itemsAndWeights can be the same object as this ProbabilityTable, nor should any key contain cycles that could reference this object from inside the values of a key. This could cause serious issues that would eventually terminate in a StackOverflowError if the cycles randomly repeated for too long. Only the first case is checked for (if the contents of this and a key are equivalent, it ignores that key; this also happens if a key is empty or null).
    
    Parameters:
    
    itemsAndWeights - an OrderedMap of T keys to Integer values, where a key will be an item this can retrieve and a value will be its weight
    
    Returns:
    
    this for chaining
  - weight
```
public int weight(T item)
```
    Returns the weight of the item if the item is in the table. Returns zero if the item is not in the table.
    
    Parameters:
    
    item - the item searched for
    
    Returns:
    
    the weight of the item, or zero
  - weight
```
public int weight(ProbabilityTable<T> item)
```
    Returns the weight of the extra table if present. Returns zero if the extra table is not present.
    
    Parameters:
    
    item - the extra ProbabilityTable to search for
    
    Returns:
    
    the weight of the ProbabilityTable, or zero
  - items
```
public OrderedSet<T> items()
```
    Provides a set of the items in this table, without reference to their weight. Includes nested ProbabilityTable values, but as is the case throughout this class, cyclical references to ProbabilityTable values that reference this table will result in significant issues (such as a StackOverflowError crashing your program).
    
    Returns:
    
    an OrderedSet of all items stored; iteration order should be predictable
  - simpleItems
```
public java.util.SortedSet<T> simpleItems()
```
    Provides a set of the items in this table that are not in nested tables, without reference to their weight. These are the items that are simple to access, hence the name. If you want the items that are in both the top-level and nested tables, you can use items().
    
    Returns:
    
    a predictably-ordered set of the items in the top-level table
  - tables
```
public java.util.ArrayList<ProbabilityTable<T>> tables()
```
    Provides a set of the nested ProbabilityTable values in this table, without reference to their weight. Does not include normal values (non-table); for that, use items().
    
    Returns:
    
    a "sorted" set of all nested tables stored, really sorted in insertion order
  - setRandom
```
public void setRandom(GWTRNG random)
```
    Sets the current random number generator to the given GWTRNG.
    
    Parameters:
    
    random - an RNG, typically with a seed you want control over; may be a StatefulRNG or some other subclass
  - getRandom
```
public GWTRNG getRandom()
```
    Gets the random number generator (a RandomnessSource) this uses.
    
    Returns:
    
    the RandomnessSource used by this class, which is always a GWTRNG
  - copy
```
public ProbabilityTable<T> copy()
```
    Copies this ProbabilityTable so nothing in the copy is shared with the original, except for the T items (which might not be possible to copy). The RNG is also copied.
    
    Returns:
    
    a copy of this ProbabilityTable; no references should be shared except for T items
  - equals
```
public boolean equals(java.lang.Object o)
```
    Overrides:
    
    equals in class java.lang.Object
  - contentEquals
```
public boolean contentEquals(ProbabilityTable<T> o)
```
    Can avoid some checks that equals(Object) needs because this always takes a ProbabilityTable.
    
    Parameters:
    
    o - another ProbabilityTable
    
    Returns:
    
    true if both ProbabilityTables are equivalent in contents and likelihoods, not necessarily random state
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object

Class ProbabilityTable<T>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

table

extraTable

weights

rng

total

normalTotal

Constructor Detail

ProbabilityTable

ProbabilityTable

ProbabilityTable

ProbabilityTable

Method Detail

random

add

addAll

remove

remove

removeAll

removeAll

add

addAllNested

weight

weight

items

simpleItems

tables

setRandom

getRandom

copy

equals

contentEquals

hashCode