Package squidpony.squidmath

Class DeckRNG

java.lang.Object
squidpony.squidmath.RNG
squidpony.squidmath.StatefulRNG
squidpony.squidmath.DeckRNG
All Implemented Interfaces:
Serializable, IRNG, IStatefulRNG, RandomnessSource, StatefulRandomness
public class DeckRNG
extends StatefulRNG
implements Serializable
An RNG variant that has 16 possible grades of value it can produce and shuffles them like a deck of cards. It repeats grades of value, but not exact values, every 16 numbers requested from it. Grades go in increments of 0.0625 from 0.0 to 0.9375, and are added to a random double less than 0.0625 to get the random number for that grade.

You can get values from this generator with: nextDouble(), nextInt(), nextLong(), and the bounded variants on each of those. Created by Tommy Ettinger on 5/2/2015.

See Also:
Serialized Form

  • Constructor Details

    • DeckRNG

      public DeckRNG()
      Constructs a DeckRNG with a pseudo-random seed from Math.random().

    • DeckRNG

      public DeckRNG​(long seed)
      Construct a new DeckRNG with the given seed.
      Parameters:
      seed - used to seed the default RandomnessSource.

    • DeckRNG

      public DeckRNG​(CharSequence seedString)
      String-seeded constructor uses the hash of the String as a seed for LightRNG, which is of high quality, but low period (which rarely matters for games), and has good speed and tiny state size.
      Parameters:
      seedString - a String to use as a seed; will be hashed in a uniform way across platforms.

    • DeckRNG

      public DeckRNG​(RandomnessSource random)
      Seeds this DeckRNG using the RandomnessSource it is given. Does not assign the RandomnessSource to any fields that would affect future pseudo-random number generation.
      Parameters:
      random - will be used to generate a new seed, but will not be assigned as this object's RandomnessSource

  • Method Details

    • nextDouble

      public double nextDouble()
      Generate a random double, altering the result if recently generated results have been leaning away from this class' fairness value.
      Specified by:
      nextDouble in interface IRNG
      Overrides:
      nextDouble in class RNG
      Returns:
      a double between 0.0 (inclusive) and 1.0 (exclusive)

    • nextDouble

      public double nextDouble​(double max)
      This returns a random double between 0.0 (inclusive) and max (exclusive).
      Specified by:
      nextDouble in interface IRNG
      Overrides:
      nextDouble in class RNG
      Parameters:
      max - the outer exclusive bound as a double; can be negative or positive
      Returns:
      a value between 0 (inclusive) and max (exclusive)

    • between

      public double between​(double min, double max)
      Returns a value from a even distribution from min (inclusive) to max (exclusive).
      Specified by:
      between in interface IRNG
      Overrides:
      between in class RNG
      Parameters:
      min - the minimum bound on the return value (inclusive)
      max - the maximum bound on the return value (exclusive)
      Returns:
      the found value

    • between

      public int between​(int min, int max)
      Returns a value between min (inclusive) and max (exclusive). The inclusive and exclusive behavior is to match the behavior of the similar method that deals with floating point values.
      Specified by:
      between in interface IRNG
      Overrides:
      between in class RNG
      Parameters:
      min - the minimum bound on the return value (inclusive)
      max - the maximum bound on the return value (exclusive)
      Returns:
      the found value

    • betweenWeighted

      public int betweenWeighted​(int min, int max, int samples)
      Returns the average of a number of randomly selected numbers from the provided range, with min being inclusive and max being exclusive. It will sample the number of times passed in as the third parameter. The inclusive and exclusive behavior is to match the behavior of the similar method that deals with floating point values. This can be used to weight RNG calls to the average between min and max.
      Overrides:
      betweenWeighted in class RNG
      Parameters:
      min - the minimum bound on the return value (inclusive)
      max - the maximum bound on the return value (exclusive)
      samples - the number of samples to take
      Returns:
      the found value

    • getRandomElement

      public <T> T getRandomElement​(T[] array)
      Returns a random element from the provided array and maintains object type.
      Specified by:
      getRandomElement in interface IRNG
      Overrides:
      getRandomElement in class RNG
      Type Parameters:
      T - the type of the returned object
      Parameters:
      array - the array to get an element from
      Returns:
      the randomly selected element

    • getRandomElement

      public <T> T getRandomElement​(List<T> list)
      Returns a random element from the provided list. If the list is empty then null is returned.
      Specified by:
      getRandomElement in interface IRNG
      Overrides:
      getRandomElement in class RNG
      Type Parameters:
      T - the type of the returned object
      Parameters:
      list - the list to get an element from
      Returns:
      the randomly selected element

    • getRandomElement

      public <T> T getRandomElement​(Collection<T> coll)
      Returns a random element from the provided Collection, which should have predictable iteration order if you want predictable behavior for identical RNG seeds, though it will get a random element just fine for any Collection (just not predictably in all cases). If you give this a Set, it should be a LinkedHashSet or some form of sorted Set like TreeSet if you want predictable results. Any List or Queue should be fine. Map does not implement Collection, thank you very much Java library designers, so you can't actually pass a Map to this, though you can pass the keys or values. If coll is empty, returns null.

      Requires iterating through a random amount of coll's elements, so performance depends on the size of coll but is likely to be decent, as long as iteration isn't unusually slow. This replaces getRandomElement(Queue), since Queue implements Collection and the older Queue-using implementation was probably less efficient.

      Specified by:
      getRandomElement in interface IRNG
      Overrides:
      getRandomElement in class RNG
      Type Parameters:
      T - the type of the returned object
      Parameters:
      coll - the Collection to get an element from; remember, Map does not implement Collection
      Returns:
      the randomly selected element

    • nextInt

      public int nextInt​(int bound)
      Returns a random integer below the given bound, or 0 if the bound is 0 or negative. Affects the current fortune.
      Specified by:
      nextInt in interface IRNG
      Overrides:
      nextInt in class RNG
      Parameters:
      bound - the upper bound (exclusive)
      Returns:
      the found number

    • shuffle

      public <T> T[] shuffle​(T[] elements)
      Shuffle an array using the Fisher-Yates algorithm. Not GWT-compatible; use the overload that takes two arrays.
      https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle
      Specified by:
      shuffle in interface IRNG
      Overrides:
      shuffle in class RNG
      Type Parameters:
      T - can be any non-primitive type.
      Parameters:
      elements - an array of T; will not be modified
      Returns:
      a shuffled copy of elements

    • randomOrdering

      public int[] randomOrdering​(int length)
      Generates a random permutation of the range from 0 (inclusive) to length (exclusive). Useful for passing to OrderedMap or OrderedSet's reorder() methods.
      Specified by:
      randomOrdering in interface IRNG
      Overrides:
      randomOrdering in class RNG
      Parameters:
      length - the size of the ordering to produce
      Returns:
      a random ordering containing all ints from 0 to length (exclusive)

    • nextIntHasty

      public int nextIntHasty​(int bound)
      Returns a random non-negative integer below the given bound, or 0 if the bound is 0. Uses a slightly optimized technique. This method is considered "hasty" since it should be faster than nextInt() doesn't check for "less-valid" bounds values. It also has undefined behavior if bound is negative, though it will probably produce a negative number (just how negative is an open question).
      Overrides:
      nextIntHasty in class RNG
      Parameters:
      bound - the upper bound (exclusive); behavior is undefined if bound is negative
      Returns:
      the found number

    • nextInt

      public int nextInt()
      Returns a random integer, which may be positive or negative.
      Specified by:
      nextInt in interface IRNG
      Overrides:
      nextInt in class RNG
      Returns:
      A random int

    • nextLong

      public long nextLong()
      Returns a random long, which may be positive or negative.
      Specified by:
      nextLong in interface IRNG
      Specified by:
      nextLong in interface RandomnessSource
      Overrides:
      nextLong in class RNG
      Returns:
      A random long

    • nextLong

      public long nextLong​(long bound)
      Returns a random long below the given bound, or 0 if the bound is 0 or negative.
      Specified by:
      nextLong in interface IRNG
      Overrides:
      nextLong in class RNG
      Parameters:
      bound - the upper bound (exclusive)
      Returns:
      the found number

    • next

      public int next​(int bits)
      Description copied from class: RNG
      Get up to 32 bits (inclusive) of random output; the int this produces will not require more than bits bits to represent.
      Specified by:
      next in interface IRNG
      Specified by:
      next in interface RandomnessSource
      Overrides:
      next in class RNG
      Parameters:
      bits - the number of bits to be returned
      Returns:
      a random int of the number of bits specified.

    • asRandom

      public Random asRandom()
      Overrides:
      asRandom in class RNG
      Returns:
      a Random instance that can be used for legacy compatibility

    • between

      public long between​(long min, long max)
      Returns a value between min (inclusive) and max (exclusive).

      The inclusive and exclusive behavior is to match the behavior of the similar method that deals with floating point values.

      Specified by:
      between in interface IRNG
      Overrides:
      between in class RNG
      Parameters:
      min - the minimum bound on the return value (inclusive)
      max - the maximum bound on the return value (exclusive)
      Returns:
      the found value

    • nextFloat

      public float nextFloat()
      Description copied from class: RNG
      Gets a random float between 0.0f inclusive and 1.0f exclusive. This returns a maximum of 0.99999994 because that is the largest float value that is less than 1.0f .
      Specified by:
      nextFloat in interface IRNG
      Overrides:
      nextFloat in class RNG
      Returns:
      a float between 0f (inclusive) and 0.99999994f (inclusive)

    • nextBoolean

      public boolean nextBoolean()
      Description copied from class: RNG
      Get a random bit of state, interpreted as true or false with approximately equal likelihood. This may have better behavior than rng.next(1), depending on the RandomnessSource implementation; the default DiverRNG will behave fine, as will LightRNG and ThrustAltRNG (these all use similar algorithms), but the normally-high-quality XoRoRNG will produce very predictable output with rng.next(1) and very good output with rng.nextBoolean(). This is a known and considered flaw of Xoroshiro128+, the algorithm used by XoRoRNG, and a large number of generators have lower quality on the least-significant bit than the most- significant bit, where this method only checks the most-significant bit.
      Specified by:
      nextBoolean in interface IRNG
      Overrides:
      nextBoolean in class RNG
      Returns:
      a random boolean.

    • getRandomness

      public RandomnessSource getRandomness()
      Overrides:
      getRandomness in class RNG

    • setRandomness

      public void setRandomness​(RandomnessSource random)
      Reseeds this DeckRNG using the RandomnessSource it is given. Does not assign the RandomnessSource to any fields that would affect future pseudo-random number generation.
      Overrides:
      setRandomness in class StatefulRNG
      Parameters:
      random - will be used to generate a new seed, but will not be assigned as this object's RandomnessSource

    • copy

      public DeckRNG copy()
      Creates a copy of this DeckRNG; it will generate the same random numbers, given the same calls in order, as this DeckRNG at the point copy() is called. The copy will not share references with this DeckRNG.
      Specified by:
      copy in interface IRNG
      Specified by:
      copy in interface RandomnessSource
      Specified by:
      copy in interface StatefulRandomness
      Overrides:
      copy in class StatefulRNG
      Returns:
      a copy of this DeckRNG

    • getState

      public long getState()
      Get a long that can be used to reproduce the sequence of random numbers this object will generate starting now.
      Specified by:
      getState in interface StatefulRandomness
      Overrides:
      getState in class StatefulRNG
      Returns:
      a long that can be used as state.

    • setState

      public void setState​(long state)
      Sets the state of the random number generator to a given long, which will alter future random numbers this produces based on the state. Setting the state always causes the "deck" of random grades to be shuffled.
      Specified by:
      setState in interface StatefulRandomness
      Overrides:
      setState in class StatefulRNG
      Parameters:
      state - any long (this can tolerate states of 0)

    • toString

      public String toString()
      Overrides:
      toString in class StatefulRNG

    • equals

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

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class RNG

    • getStep

      public int getStep()

    • setStep

      public void setStep​(int step)

    • toSerializable

      public Serializable toSerializable()
      Returns this DeckRNG in a way that can be deserialized even if only IRNG's methods can be called.
      Specified by:
      toSerializable in interface IRNG
      Overrides:
      toSerializable in class StatefulRNG
      Returns:
      a Serializable view of this DeckRNG; always this