Class WeightedTable

java.lang.Object
com.github.yellowstonegames.core.WeightedTable
public class WeightedTable extends Object
A different approach to the same task as a probability table, though this only looks up an appropriate index instead of also storing items it can choose; allows positive floats for weights but does not allow nested tables for simplicity. This doesn't store a Random in this class, and instead expects either a Random as a parameter, or a long to be given for each random draw from the table (these long parameters can be random, sequential, or in some other way different every time).
Uses Vose's Alias Method, and is based fairly-closely on the code given by Keith Schwarz at that link. Because Vose's Alias Method is remarkably fast (it takes O(1) time to get a random index, and takes O(n) time to construct a WeightedTable instance), this may be useful to consider if you don't need all the features of ProbabilityTable or if you want deeper control over the random aspects of it.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected int[]
    mixed
     
    protected int
    size
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    WeightedTable()
    Constructs a useless WeightedTable that always returns the index 0.
    WeightedTable(float... probabilities)
    Constructs a WeightedTable with the given array of weights for each index.
    WeightedTable(float[] probabilities, int offset, int length)
    Constructs a WeightedTable with the given array of weights for each index.
    WeightedTable(com.github.tommyettinger.ds.FloatList probabilities)
    Constructs a WeightedTable with the given array of weights for each index.
    WeightedTable(WeightedTable other)
    Copy constructor; avoids sharing any state between this and the original.

  • Method Summary

    Modifier and Type
    Method
    Description
    WeightedTable
    copy()
    Copies this WeightedTable; avoids sharing any state between this and the copy.
    boolean
    equals(Object o)
     
    int
    getSize()
     
    int
    hashCode()
     
    int
    random(long state)
    Gets an index of one of the weights in this WeightedTable, with the choice determined deterministically by the given long, but higher weights will be returned by more possible inputs than lower weights.
    int
    random(Random rng)
    Gets an index of one of the weights in this WeightedTable, with the choice determined by the given random number generator, but higher weights will be returned more frequently than lower weights.
    static WeightedTable
    stringDeserialize(String data)
     
    String
    stringSerialize()
     

    Methods inherited from class Object

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

  • Field Details

    • mixed

      protected int[] mixed

    • size

      protected int size

  • Constructor Details

    • WeightedTable

      public WeightedTable()
      Constructs a useless WeightedTable that always returns the index 0.

    • WeightedTable

      public WeightedTable(float... probabilities)
      Constructs a WeightedTable with the given array of weights for each index. The array can also be a varargs for convenience. The weights can be any positive non-zero floats, but should usually not be so large or small that precision loss is risked. Each weight will be used to determine the likelihood of that weight's index being returned by random(long).
      Parameters:
      probabilities - an array or varargs of positive floats representing the weights for their own indices

    • WeightedTable

      public WeightedTable(com.github.tommyettinger.ds.FloatList probabilities)
      Constructs a WeightedTable with the given array of weights for each index. The array can also be a varargs for convenience. The weights can be any positive non-zero floats, but should usually not be so large or small that precision loss is risked. Each weight will be used to determine the likelihood of that weight's index being returned by random(long).
      Parameters:
      probabilities - a FloatList of positive floats representing the weights for their own indices

    • WeightedTable

      public WeightedTable(float[] probabilities, int offset, int length)
      Constructs a WeightedTable with the given array of weights for each index. The array can also be a varargs for convenience. The weights can be any positive non-zero floats, but should usually not be so large or small that precision loss is risked. Each weight will be used to determine the likelihood of that weight's index being returned by random(long).
      Parameters:
      probabilities - an array or varargs of positive floats representing the weights for their own indices

    • WeightedTable

      public WeightedTable(WeightedTable other)
      Copy constructor; avoids sharing any state between this and the original.
      Parameters:
      other - another WeightedTable to copy; no state will be shared

  • Method Details

    • copy

      public WeightedTable copy()
      Copies this WeightedTable; avoids sharing any state between this and the copy.
      Returns:
      an exact copy of this WeightedTable

    • random

      public int random(long state)
      Gets an index of one of the weights in this WeightedTable, with the choice determined deterministically by the given long, but higher weights will be returned by more possible inputs than lower weights. The state parameter can be from a random source, but this will randomize it again anyway, so it is also fine to just give sequential longs. The important thing is that each state input this is given will produce the same result for this WeightedTable every time, so you should give different state values when you want random-seeming results. You may want to call this like weightedTable.random(++state), where state is a long, to ensure the inputs change. This will always return an int between 0 (inclusive) and size (exclusive).
      Internally, this uses a unary hash (a function that converts one number to a random-seeming but deterministic other number) to generate two ints, one used for probability and treated as a 31-bit integer and the other used to determine the chosen column, which is bounded to an arbitrary positive int. It does this with just one randomized 64-bit value, allowing the state parameter to be just one long.
      You can also use random(Random) to avoid handling state directly; this can be faster if using a particularly fast Random implementation such as one from juniper.
      Parameters:
      state - a long that should be different every time; consider calling with ++state
      Returns:
      a random-seeming index from 0 to size - 1, determined by weights and the given state

    • random

      public int random(Random rng)
      Gets an index of one of the weights in this WeightedTable, with the choice determined by the given random number generator, but higher weights will be returned more frequently than lower weights. The rng parameter can be any implementation of Random, and some implementations are likely to be faster than the unary hash used by random(long). This will return an int between 0 (inclusive) and size (exclusive).
      Parameters:
      rng - an Random; its Random.nextLong() method will be called once
      Returns:
      a random index from 0 to size - 1, determined by weights and the given rng

    • stringSerialize

      public String stringSerialize()

    • stringDeserialize

      public static WeightedTable stringDeserialize(String data)

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • getSize

      public int getSize()