Package squidpony.squidmath

Class ProbabilityTable<T>

java.lang.Object
squidpony.squidmath.ProbabilityTable<T>
Type Parameters:
T - The type of object to be held in the table
All Implemented Interfaces:
Serializable
public class ProbabilityTable<T>
extends Object
implements 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().
Author:
Eben Howard - http://squidpony.com - howard@squidpony.com
See Also:
An alternative for when you want to track the items separately from their weights., Serialized Form

  • Field Summary

    Fields 
    Modifier and Type Field Description
    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 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​(String seed)
    Creates a new probability table with the provided String seed used.
    ProbabilityTable​(RandomnessSource rng)
    Creates a new probability table with the provided source of randomness used.

  • Method Summary

    Modifier and Type Method 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,​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>,​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​(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​(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,​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.
    SortedSet<T> simpleItems()
    Provides a set of the items in this table that are not in nested tables, without reference to their weight.
    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 Details

  • Constructor Details

  • Method Details

    • 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,​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​(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,​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>,​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 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 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​(Object o)
      Overrides:
      equals in class 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 Object