Class ProbabilityTable<T>

java.lang.Object
com.github.yellowstonegames.core.ProbabilityTable<T>
Type Parameters:
T - The type of object to be held in the table
All Implemented Interfaces:
ISerializersNeeded
public class ProbabilityTable<T> extends Object implements ISerializersNeeded
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(ObjectIntMap) , 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(ObjectIntMap). Actually getting a randomly-selected item is easy; just use random().
You can serialize a ProbabilityTable in various ways. The class can be registered with Fory serialization using fory.register() as long as you have already registered the classes listed in getSerializersNeeded(). It can also be written and read with a specialized serializer from SquidStore or SquidFreeze, for JSON or Kryo respectively. All these options require having other types registered, which always includes T. Kryo and Fory also require ObjectList, NumberedSet, and IntList to be registered, plus the concrete subclass of EnhancedRandom used by the ProbabilityTable (which defaults to WhiskerRandom). Kryo also needs EnhancedRandom itself registered.
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    final com.github.tommyettinger.ds.ObjectList<ProbabilityTable<T>>
    extraTable
    The list of items that can be produced indirectly from random() (looking up values from inside the nested tables).
    com.github.tommyettinger.random.EnhancedRandom
    rng
    The random number generator; don't assign null to this, but otherwise it can be any EnhancedRandom.
    final com.github.tommyettinger.ds.NumberedSet<T>
    table
    The set of items that can be produced directly from random() (without additional lookups).
    int
    total
    The total of all weights.
    final com.github.tommyettinger.ds.IntList
    weights
    The list of weights associated with both table and extraTable, with all of table first and then all of extraTable.

  • 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(com.github.tommyettinger.random.EnhancedRandom rng)
    Creates a new probability table with the provided source of randomness used.
    ProbabilityTable(ProbabilityTable<? extends T> other)
    Copy constructor.
    ProbabilityTable(String seed)
    Creates a new probability table with the provided String seed 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(com.github.tommyettinger.ds.ObjectIntMap<T> itemsAndWeights)
    Given an ObjectIntMap of T element keys and int weight values, adds all T keys with their corresponding weights into this ProbabilityTable.
    ProbabilityTable<T>
    addAllNested(com.github.tommyettinger.ds.ObjectIntMap<ProbabilityTable<T>> itemsAndWeights)
    Given an ObjectIntMap of ProbabilityTable keys and int 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)
     
    com.github.tommyettinger.random.EnhancedRandom
    getRandom()
    Gets the random number generator (an EnhancedRandom) this uses.
    List<Class<?>>
    getSerializersNeeded()
    Gets a List of Class instances that must each be registered with a serialization library before this object can be successfully serialized or deserialized.
    int
    hashCode()
     
    com.github.tommyettinger.ds.ObjectOrderedSet<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(com.github.tommyettinger.ds.ObjectIntMap<T> itemsAndWeights)
    Given an ObjectIntMap of T item keys and int 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.
    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.
    void
    setRandom(com.github.tommyettinger.random.EnhancedRandom random)
    Sets the current random number generator to the given EnhancedRandom.
    com.github.tommyettinger.ds.NumberedSet<T>
    simpleItems()
    Provides a set of the items in this table that are not in nested tables, without reference to their weight.
    com.github.tommyettinger.ds.ObjectList<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 Object

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

  • Field Details

    • table

      public final com.github.tommyettinger.ds.NumberedSet<T> table
      The set of items that can be produced directly from random() (without additional lookups).

    • extraTable

      public final com.github.tommyettinger.ds.ObjectList<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 com.github.tommyettinger.ds.IntList weights
      The list of weights associated with both table and extraTable, with all of table first and then all of extraTable.

    • rng

      public com.github.tommyettinger.random.EnhancedRandom rng
      The random number generator; don't assign null to this, but otherwise it can be any EnhancedRandom.

    • total

      public int total
      The total of all weights. This is only public because weights is also public, and changes to weights must be reflected here.

  • Constructor Details

    • ProbabilityTable

      public ProbabilityTable()
      Creates a new probability table with a random seed.

    • ProbabilityTable

      public ProbabilityTable(com.github.tommyettinger.random.EnhancedRandom rng)
      Creates a new probability table with the provided source of randomness used.
      Parameters:
      rng - the source of randomness

    • ProbabilityTable

      public ProbabilityTable(ProbabilityTable<? extends T> other)
      Copy constructor.
      Parameters:
      other - another ProbabilityTable; must not contain cyclical references to tables that contain themselves

    • 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(String seed)
      Creates a new probability table with the provided String seed used.
      Parameters:
      seed - the RNG seed as a String

  • 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(com.github.tommyettinger.ds.ObjectIntMap<T> itemsAndWeights)
      Given an ObjectIntMap of T element keys and int weight values, adds all T keys with their corresponding weights into this ProbabilityTable. You may want to use ObjectIntMap.with(Object, Number, Object...) to produce the parameter, unless you already have one. You may also want to use ObjectIntOrderedMap to preserve the iteration order of items in this ProbabilityTable.
      Parameters:
      itemsAndWeights - an ObjectIntMap of T keys to int 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(com.github.tommyettinger.ds.ObjectIntMap<T> itemsAndWeights)
      Given an ObjectIntMap of T item keys and int 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 ObjectIntMap.with(Object, Number, 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(com.github.tommyettinger.ds.ObjectIntMap<ProbabilityTable<T>> itemsAndWeights)
      Given an ObjectIntMap of ProbabilityTable keys and int 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 ObjectIntMap.with(Object, Number, 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 ObjectIntMap of T keys to int 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 com.github.tommyettinger.ds.ObjectOrderedSet<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 ObjectOrderedSet of all items stored; iteration order should be predictable

    • simpleItems

      public com.github.tommyettinger.ds.NumberedSet<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(). Note that this returns a direct reference to the simple items in this ProbabilityTable, so you generally shouldn't modify the returned Set.
      Returns:
      a predictably-ordered set of the items in the top-level table

    • tables

      public com.github.tommyettinger.ds.ObjectList<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 List of all nested tables stored, in insertion order

    • setRandom

      public void setRandom(com.github.tommyettinger.random.EnhancedRandom random)
      Sets the current random number generator to the given EnhancedRandom.
      Parameters:
      random - an EnhancedRandom, typically with a seed you want control over; for instance, a WhiskerRandom

    • getRandom

      public com.github.tommyettinger.random.EnhancedRandom getRandom()
      Gets the random number generator (an EnhancedRandom) this uses.
      Returns:
      the EnhancedRandom used by this class

    • 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

    • getSerializersNeeded

      public List<Class<?>> getSerializersNeeded()
      Description copied from interface: ISerializersNeeded
      Gets a List of Class instances that must each be registered with a serialization library before this object can be successfully serialized or deserialized. This is GwtIncompatible; none of the serialization libraries this is meant for have any support for GWT.
      Specified by:
      getSerializersNeeded in interface ISerializersNeeded
      Returns:
      a List of Class instances that must each be registered with a serialization library