Package com.github.tommyettinger.random

Class DeckWrapper

java.lang.Object
java.util.Random
com.github.tommyettinger.random.EnhancedRandom
com.github.tommyettinger.random.DeckWrapper
All Implemented Interfaces:
Externalizable, Serializable, RandomGenerator
public class DeckWrapper extends EnhancedRandom
A wrapper around another EnhancedRandom instance that stores an array of 16 long results that it generates in batches, and modifies so that the most significant 4 bits of each result are each distinct. This shuffles the 16 different results when it starts and whenever 16 results have been generated. This is meant for cases where independent random results are undesirable, and any sequence of "bad luck" (low results) can be followed in short order by "good luck" (high results), and vice versa. This allows an uninformed expectation of how randomness works (the "Gambler's Fallacy") to be closer to how it actually works in practice.
This doesn't generate more results with its wrapped generator's nextLong() than it has to; because 4 bits of each result are replaced by distinct nybbles, those bits are reused to shuffle the 16 results. This works best with any generator that has an efficient nextLong() implementation, so preferably one where mainlyGeneratesInt() is false. The most-significant 4 bits of each nextLong() call to the wrapped generator are used to shuffle the results, and the rest are left as-is.
See Also:

  • Field Details

    • wrapped

      protected EnhancedRandom wrapped

    • index

      protected int index

    • buffer

      protected long[] buffer

  • Constructor Details

    • DeckWrapper

      public DeckWrapper()

    • DeckWrapper

      public DeckWrapper(long seed)

    • DeckWrapper

      public DeckWrapper(EnhancedRandom toWrap)

    • DeckWrapper

      public DeckWrapper(DeckWrapper other)

  • Method Details

    • getTag

      public String getTag()
      Description copied from class: EnhancedRandom
      Gets the tag used to identify this type of EnhancedRandom, as a String. This tag should be unique, and for uniformity purposes, all tags used in this library are 4 characters long. User-defined tags should have a different length.
      Specified by:
      getTag in class EnhancedRandom
      Returns:
      "DecW"

    • setSeed

      public void setSeed(long seed)
      Description copied from class: EnhancedRandom
      Sets the seed of this random number generator using a single long seed. This should behave exactly the same as if a new object of this type was created with the constructor that takes a single long value. This does not necessarily assign the state variable(s) of the implementation with the exact contents of seed, so EnhancedRandom.getSelectedState(int) should not be expected to return seed after this, though it may. If this implementation has more than one long of state, then the expectation is that none of those state variables will be exactly equal to seed (almost all the time).
      Specified by:
      setSeed in class EnhancedRandom
      Parameters:
      seed - the initial seed

    • nextLong

      public long nextLong()
      Description copied from class: EnhancedRandom
      Returns the next pseudorandom, uniformly distributed long value from this random number generator's sequence. The general contract of nextLong is that one long value is pseudorandomly generated and returned.
      The only methods that need to be implemented by this interface are this and EnhancedRandom.copy(), though other methods can be implemented as appropriate for generators that, for instance, natively produce ints rather than longs.
      Specified by:
      nextLong in interface RandomGenerator
      Specified by:
      nextLong in class EnhancedRandom
      Returns:
      the next pseudorandom, uniformly distributed long value from this random number generator's sequence

    • next

      public int next(int bits)
      Description copied from class: EnhancedRandom
      Generates the next pseudorandom number with a specific maximum size in bits (not a max number). If you want to get a random number in a range, you should usually use EnhancedRandom.nextInt(int) instead. For some specific cases, this method is more efficient and less biased than EnhancedRandom.nextInt(int). For bits values between 1 and 30, this should be similar in effect to nextInt(1 << bits); though it won't typically produce the same values, they will have the correct range. If bits is 31, this can return any non-negative int; note that nextInt(1 << 31) won't behave this way because 1 << 31 is negative. If bits is 32 (or 0), this can return any int.

      The general contract of next is that it returns an int value and if the argument bits is between 1 and 32 (inclusive), then that many low-order bits of the returned value will be (approximately) independently chosen bit values, each of which is (approximately) equally likely to be 0 or 1.

      Note that you can give this values for bits that are outside its expected range of 1 to 32, but the value used, as long as bits is positive, will effectively be bits % 32. As stated before, a value of 0 for bits is the same as a value of 32.

      Overrides:
      next in class EnhancedRandom
      Parameters:
      bits - the amount of random bits to request, from 1 to 32
      Returns:
      the next pseudorandom value from this random number generator's sequence

    • nextInt

      public int nextInt()
      Description copied from class: EnhancedRandom
      Returns the next pseudorandom, uniformly distributed int value from this random number generator's sequence. The general contract of nextInt is that one int value is pseudorandomly generated and returned. All 232 possible int values are produced with (approximately) equal probability.
      Specified by:
      nextInt in interface RandomGenerator
      Overrides:
      nextInt in class EnhancedRandom
      Returns:
      the next pseudorandom, uniformly distributed int value from this random number generator's sequence

    • nextInt

      public int nextInt(int bound)
      Description copied from class: EnhancedRandom
      Returns a pseudorandom, uniformly distributed int value between 0 (inclusive) and the specified value (exclusive), drawn from this random number generator's sequence. The general contract of nextInt is that one int value in the specified range is pseudorandomly generated and returned. All bound possible int values are produced with (approximately) equal probability.
      This method clamps bound to be at least 0; it never returns a negative int.
      It should be mentioned that the technique this uses has some bias, depending on bound, but it typically isn't measurable without specifically looking for it. Using the method this does allows this method to always advance the state by one step, instead of a varying and unpredictable amount with the more typical ways of rejection-sampling random numbers and only using numbers that can produce an int within the bound without bias. See M.E. O'Neill's blog about random numbers for discussion of alternative, unbiased methods.
      Specified by:
      nextInt in interface RandomGenerator
      Overrides:
      nextInt in class EnhancedRandom
      Parameters:
      bound - the upper bound (exclusive). If negative or 0, this always returns 0.
      Returns:
      the next pseudorandom, uniformly distributed int value between zero (inclusive) and bound (exclusive) from this random number generator's sequence

    • nextSignedInt

      public int nextSignedInt(int outerBound)
      Description copied from class: EnhancedRandom
      Returns a pseudorandom, uniformly distributed int value between an inner bound of 0 (inclusive) and the specified outerBound (exclusive). This is meant for cases where the outer bound may be negative, especially if the bound is unknown or may be user-specified. A negative outer bound is used as the lower bound; a positive outer bound is used as the upper bound. An outer bound of -1, 0, or 1 will always return 0, keeping the bound exclusive (except for outer bound 0). This method is slightly slower than EnhancedRandom.nextInt(int).
      Overrides:
      nextSignedInt in class EnhancedRandom
      Parameters:
      outerBound - the outer exclusive bound; may be any int value, allowing negative
      Returns:
      a pseudorandom int between 0 (inclusive) and outerBound (exclusive)
      See Also:

    • nextBytes

      public void nextBytes(byte[] bytes)
      Description copied from class: EnhancedRandom
      Generates random bytes and places them into a user-supplied byte array. The number of random bytes produced is equal to the length of the byte array.
      Specified by:
      nextBytes in interface RandomGenerator
      Overrides:
      nextBytes in class EnhancedRandom
      Parameters:
      bytes - the byte array to fill with random bytes

    • nextUnsignedInt

      public int nextUnsignedInt(int bound)
      Description copied from class: EnhancedRandom
      Returns a pseudorandom, uniformly distributed int value between 0 (inclusive) and the specified value (exclusive), drawn from this random number generator's sequence. The general contract of nextInt is that one int value in the specified range is pseudorandomly generated and returned. All bound possible int values are produced with (approximately) equal probability.
      This method treats the outer bound as unsigned, so if a negative int is passed as bound, it will be treated as positive and larger than Integer.MAX_VALUE. That means this can produce results that are positive or negative, but when you mask the result and the bound with 0xFFFFFFFFL (to treat them as unsigned), the result will always be between 0L (inclusive) and the masked bound (exclusive).
      This is primarily useful as a building block for other methods in this class.
      Overrides:
      nextUnsignedInt in class EnhancedRandom
      Parameters:
      bound - the upper bound (exclusive); treated as unsigned
      Returns:
      the next pseudorandom, uniformly distributed int value between zero (inclusive) and bound (exclusive), treated as unsigned, from this random number generator's sequence

    • nextInclusiveFloat

      public float nextInclusiveFloat()
      Description copied from class: EnhancedRandom
      This is just like EnhancedRandom.nextFloat(), returning a float between 0 and 1, except that it is inclusive on both 0.0 and 1.0. It returns 1.0 rarely, 0.000000000000000005421010862427522% of the time if there is no bias in the generator, but it can happen.
      This method does not return purely-equidistant floats, because there the resolution of possible floats it can generate is higher as it approaches 0.0 . The smallest non-zero float this can return is 2.7105064E-20 (0x1.000006p-65 in hex), and the largest non-one float this can return is 0.99999994f (0x1.fffffep-1 in hex). This uses nearly identical code to EnhancedRandom.nextExclusiveFloat(), but does some really unusual operations on both the bits and the float value to be able to produce 0.0f and 1.0f . This retains the exclusive version's quality of having approximately uniform distributions for every mantissa bit, unlike most ways of generating random floating-point numbers.
      Overrides:
      nextInclusiveFloat in class EnhancedRandom
      Returns:
      a float between 0.0, inclusive, and 1.0, inclusive

    • nextExclusiveFloat

      public float nextExclusiveFloat()
      Description copied from class: EnhancedRandom
      Gets a random float between 0.0 and 1.0, exclusive at both ends. This method is also more uniform than EnhancedRandom.nextFloat() if you use the bit-patterns of the returned floats. This is a simplified version of this algorithm by Allen Downey. This version can return float values between 2.7105054E-20 to 0.99999994, or 0x1.0p-65 to 0x1.fffffep-1 in hex notation. It cannot return 0 or 1. To compare, nextFloat() is less likely to produce a "1" bit for its lowest 5 bits of mantissa/significand (the least significant bits numerically, but potentially important for some uses), with the least significant bit produced half as often as the most significant bit in the mantissa. As for this method, it has approximately the same likelihood of producing a "1" bit for any position in the mantissa.
      The implementation may have different performance characteristics than EnhancedRandom.nextFloat(), because this doesn't perform any floating-point multiplication or division, and instead assembles bits obtained by one call to EnhancedRandom.nextLong(). This uses BitConversion.intBitsToFloat(int) and BitConversion.countLeadingZeros(long), both of which typically have optimized intrinsics on HotSpot, and this is branchless and loopless, unlike the original algorithm by Allen Downey. When compared with EnhancedRandom.nextExclusiveFloatEquidistant(), this method performs better on at least HotSpot JVMs. On GraalVM 17, this is over twice as fast as nextExclusiveFloatEquidistant().
      Overrides:
      nextExclusiveFloat in class EnhancedRandom
      Returns:
      a random uniform float between 0 and 1 (both exclusive)

    • nextInclusiveDouble

      public double nextInclusiveDouble()
      Description copied from class: EnhancedRandom
      This is just like EnhancedRandom.nextDouble(), returning a double between 0 and 1, except that it is inclusive on both 0.0 and 1.0. It returns 1.0 rarely, 0.000000000000000005421010862427522% of the time if there is no bias in the generator, but it can happen.
      This method does not return purely-equidistant doubles, because there the resolution of possible doubles it can generate is higher as it approaches 0.0 . The smallest non-zero double this can return is 2.710505431213763e-20 (0x1.0000000000003p-65 in hex), and the largest non-one double this can return is 0.9999999999999999 (0x1.fffffffffffffp-1 in hex). This uses nearly identical code to EnhancedRandom.nextExclusiveDouble(), but does some really unusual operations on both the bits and the double value to be able to produce 0.0 and 1.0 . This retains the exclusive version's quality of having approximately uniform distributions for every mantissa bit, unlike most ways of generating random floating-point numbers.
      Overrides:
      nextInclusiveDouble in class EnhancedRandom
      Returns:
      a double between 0.0, inclusive, and 1.0, inclusive

    • nextExclusiveDouble

      public double nextExclusiveDouble()
      Description copied from class: EnhancedRandom
      Gets a random double between 0.0 and 1.0, exclusive at both ends; this method is also more uniform than EnhancedRandom.nextDouble() if you use the bit-patterns of the returned doubles. This is a simplified version of this algorithm by Allen Downey. This can return double values between 2.710505431213761E-20 and 0.9999999999999999, or 0x1.0p-65 and 0x1.fffffffffffffp-1 in hex notation. It cannot return 0 or 1. Some cases can prefer EnhancedRandom.nextExclusiveDoubleEquidistant(), which is implemented more traditionally but may have slower performance. This method can also return doubles that are extremely close to 0, but can't return doubles that are as close to 1, due to how floating-point numbers work. However, nextExclusiveDoubleEquidistant() can return only a minimum value that is as distant from 0 as its maximum value is distant from 1.
      To compare, nextDouble() and nextExclusiveDoubleEquidistant() are less likely to produce a "1" bit for their lowest 5 bits of mantissa/significand (the least significant bits numerically, but potentially important for some uses), with the least significant bit produced half as often as the most significant bit in the mantissa. As for this method, it has approximately the same likelihood of producing a "1" bit for any position in the mantissa.
      The implementation may have different performance characteristics than EnhancedRandom.nextDouble(), because this doesn't perform any floating-point multiplication or division, and instead assembles bits obtained by one call to EnhancedRandom.nextLong(). This uses BitConversion.longBitsToDouble(long) and BitConversion.countLeadingZeros(long), both of which typically have optimized intrinsics on HotSpot, and this is branchless and loopless, unlike the original algorithm by Allen Downey. When compared with EnhancedRandom.nextExclusiveDoubleEquidistant(), this method performs better on at least HotSpot JVMs. On GraalVM 17, this is over twice as fast as nextExclusiveDoubleEquidistant().
      Overrides:
      nextExclusiveDouble in class EnhancedRandom
      Returns:
      a random uniform double between 2.710505431213761E-20 and 0.9999999999999999 (both inclusive)

    • nextExclusiveSignedDouble

      public double nextExclusiveSignedDouble()
      Description copied from class: EnhancedRandom
      Gets a random double that may be positive or negative, but cannot be 0, and always has a magnitude less than 1.
      This is a modified version of this algorithm by Allen Downey. This version can return double values between -0.9999999999999999 and -5.421010862427522E-20, as well as between 5.421010862427522E-20 and 0.9999999999999999, or -0x1.fffffffffffffp-1 to -0x1.0p-64 as well as between 0x1.0p-64 and 0x1.fffffffffffffp-1 in hex notation. It cannot return -1, 0 or 1. It has much more uniform bit distribution across its mantissa/significand bits than Random.nextDouble(), especially when the result of nextDouble() is expanded to the -1.0 to 1.0 range (such as with 2.0 * (nextDouble() - 0.5)). Where that code using EnhancedRandom.nextDouble() is unable to produce a "1" bit for its lowest bit of mantissa (the least significant bits numerically, but potentially important for some uses), this has approximately the same likelihood of producing a "1" bit for any positions in the mantissa, and also equal odds for the sign bit.
      Some useful properties here are that this produces a negative result exactly as often as the underlying generator produces a negative result with EnhancedRandom.nextLong(), and the least-significant bits that the underlying generator produces with EnhancedRandom.nextLong() are also the least-significant in magnitude here. This could be used with lower-quality randomness, like a linear congruential generator, and the flaws those have with their low-order bits would barely affect floating-point results here. This generator also produces results that are symmetrical around 0.0, with every possible positive number having a possible negative number of equal magnitude, if the underlying generator is at least 1-dimensionally equidistributed. Note that generators such as Xoroshiro128StarStarRandom and Xoshiro256StarStarRandom cannot return 0L from EnhancedRandom.nextLong() as frequently as other results, so this is not (technically) true of those. Those generators (and other LFSR-type generators) will produce 5.421010862427522E-20 less frequently than -5.421010862427522E-20 .
      Overrides:
      nextExclusiveSignedDouble in class EnhancedRandom
      Returns:
      a random uniform double between -1 and 1 with a tiny hole around 0 (all exclusive)

    • nextExclusiveSignedFloat

      public float nextExclusiveSignedFloat()
      Description copied from class: EnhancedRandom
      Gets a random float that may be positive or negative, but cannot be 0, and always has a magnitude less than 1.
      This is a modified version of this algorithm by Allen Downey. This version can return float values between -0.99999994 and -5.421011E-20, as well as between 5.421011E-20 and 0.99999994, or -0x1.fffffep-1 to -0x1.0p-64 as well as between 0x1.0p-64 and 0x1.fffffep-1 in hex notation. It cannot return -1, 0 or 1. It has much more uniform bit distribution across its mantissa/significand bits than Random.nextFloat(), especially when the result of nextFloat() is expanded to the -1.0 to 1.0 range (such as with 2.0 * (nextFloat() - 0.5)). Where the given example code is unable to produce a "1" bit for its lowest bit of mantissa (the least significant bits numerically, but potentially important for some uses), this has approximately the same likelihood of producing a "1" bit for any positions in the mantissa, and also equal odds for the sign bit.
      Some useful properties here are that this produces a negative result exactly as often as the underlying generator produces a negative result with EnhancedRandom.nextLong(), and the least-significant bits that the underlying generator produces with EnhancedRandom.nextLong() are also the least-significant in magnitude here. This could be used with lower-quality randomness, like a linear congruential generator, and the flaws those have with their low-order bits would barely affect floating-point results here. This generator also produces results that are symmetrical around 0.0, with every possible positive number having a possible negative number of equal magnitude, if the underlying generator is at least 1-dimensionally equidistributed. Note that generators such as Xoroshiro128StarStarRandom and Xoshiro256StarStarRandom cannot return 0L from EnhancedRandom.nextLong() as frequently as other results, so this is not (technically) true of those. Those generators (and other LFSR-type generators) will produce 5.421011E-20 less frequently than -5.421011E-20 .
      Overrides:
      nextExclusiveSignedFloat in class EnhancedRandom
      Returns:
      a random uniform float between -1 and 1 with a tiny hole around 0 (all exclusive)

    • nextGaussian

      public double nextGaussian()
      Description copied from class: EnhancedRandom
      Returns the next pseudorandom, Gaussian ("normally") distributed double value with mean 0.0 and standard deviation 1.0 from this random number generator's sequence.

      The general contract of nextGaussian is that one double value, chosen from (approximately) the usual normal distribution with mean 0.0 and standard deviation 1.0, is pseudorandomly generated and returned.

      This does not use a rough approximation, which is a departure from earlier versions; instead, it uses the Ziggurat method, which produces high-quality variables very quickly. Like earlier versions that used probit() or a bit-counting approximation, this requests exactly one long from the generator's sequence (using EnhancedRandom.nextLong()). This makes it different from code like java.util.Random's nextGaussian() method, which can (rarely) fetch a higher number of random doubles.

      The implementation here was ported from code by Olaf Berstein, based on a paper by Jorgen A. Doornik and some steps from a paper by George Marsaglia. Distributor has more information, for the curious.

      Specified by:
      nextGaussian in interface RandomGenerator
      Overrides:
      nextGaussian in class EnhancedRandom
      Returns:
      the next pseudorandom, Gaussian ("normally") distributed double value with mean 0.0 and standard deviation 1.0 from this random number generator's sequence

    • nextGaussianFloat

      public float nextGaussianFloat()
      Description copied from class: EnhancedRandom
      Returns the next pseudorandom, Gaussian ("normally") distributed float value with mean 0.0 and standard deviation 1.0 from this random number generator's sequence.

      The general contract of nextGaussianFloat is that one float value, chosen from (approximately) the usual normal distribution with mean 0.0 and standard deviation 1.0, is pseudorandomly generated and returned.

      This uses RoughMath.normalRough(long), which actually appears to approximate the normal distribution better than Distributor.normalF(long), though not quite as well as Distributor.normal(long) (which is used by EnhancedRandom.nextGaussian()). Like nextGaussian(), this requests exactly one long from the generator's sequence (using EnhancedRandom.nextLong()). This makes it different from code like java.util.Random's nextGaussian() method, which can (rarely) fetch an arbitrarily higher number of random doubles.

      The implementation here was ported from code by Marc B. Reynolds and modified to only require one call to EnhancedRandom.nextLong().

      Overrides:
      nextGaussianFloat in class EnhancedRandom
      Returns:
      the next pseudorandom, Gaussian ("normally") distributed float value with mean 0.0 and standard deviation 1.0 from this random number generator's sequence

    • copy

      public DeckWrapper copy()
      Description copied from class: EnhancedRandom
      Creates a new EnhancedRandom with identical states to this one, so if the same EnhancedRandom methods are called on this object and its copy (in the same order), the same outputs will be produced. This is not guaranteed to copy the inherited state of any parent class, so if you call methods that are only implemented by a superclass (like Random) and not this one, the results may differ.
      Specified by:
      copy in class EnhancedRandom
      Returns:
      a deep copy of this EnhancedRandom.

    • mainlyGeneratesInt

      public boolean mainlyGeneratesInt()
      Description copied from class: EnhancedRandom
      Returns true if this generator mainly operates via its EnhancedRandom.nextInt() method internally, which means its EnhancedRandom.nextLong() must generate two int values instead of naturally producing one long. This affects how the minimum period is measured for EnhancedRandom.getMinimumPeriod(). Most generators not intentionally targeting Google Web Toolkit mainly operate via EnhancedRandom.nextLong() here, and return false. A generator that returns true here does not necessarily use 32-bit math; a generator can use 64-bit math internally but only produce 32 bits at a time by truncating its results.
      Overrides:
      mainlyGeneratesInt in class EnhancedRandom
      Returns:
      true if measurements of the period measure calls to EnhancedRandom.nextInt() instead of EnhancedRandom.nextLong()
      See Also:

    • getMinimumPeriod

      public BigInteger getMinimumPeriod()
      Description copied from class: EnhancedRandom
      Gets the guaranteed lowest number of different results this can return from its main generating method, which is normally EnhancedRandom.nextLong() unless EnhancedRandom.mainlyGeneratesInt() returns true (then it is EnhancedRandom.nextInt()). The maximum period is not known for many generators, but the minimum is, even if it is only 1 for a generator that can be initialized badly and return the same value every time on that cycle. If the minimum period is not known, this should not be overridden; its default result is the constant BigInteger.ONE. If this is the only JavaDoc for this method, the minimum period is not known, and is possibly 1 in the worst case.
      This is relevant when determining if, when two different generators are combined, their period will change. The minimum period of two generators run simultaneously and both used fully in the result is the least common multiple of their minimum periods. This can be computed conveniently with EnhancedRandom.lcm(BigInteger, BigInteger) given the minimum period of two different EnhancedRandom generators.
      Implementations are strongly encouraged to compute this value once, if it needs computation at all, and store it in a private static final BigInteger MINIMUM_PERIOD;, which this method simply returns. Classes are not required to have a MINIMUM_PERIOD field or to make it accessible. Calling this method should generally not create a new BigInteger.
      Overrides:
      getMinimumPeriod in class EnhancedRandom
      Returns:
      the minimum guaranteed period, or the shortest cycle length possible for the main generating method

    • getStateCount

      public int getStateCount()
      Description copied from class: EnhancedRandom
      Gets the number of possible state variables that can be selected with EnhancedRandom.getSelectedState(int) or EnhancedRandom.setSelectedState(int, long). This defaults to returning 0, making no state variable available for reading or writing. An implementation that has only one long state, like DistinctRandom generator, should return 1. A generator that permits setting two different long values, like LaserRandom, should return 2. Much larger values are possible for types like the Mersenne Twister or some CMWC generators.
      Overrides:
      getStateCount in class EnhancedRandom
      Returns:
      the non-negative number of selections possible for state variables

    • getSelectedState

      public long getSelectedState(int selection)
      Description copied from class: EnhancedRandom
      Gets a selected state value from this EnhancedRandom. The number of possible selections is up to the implementing class, and is accessible via EnhancedRandom.getStateCount(), but negative values for selection are typically not tolerated. This should return the exact value of the selected state, assuming it is implemented. The default implementation throws an UnsupportedOperationException, and implementors only have to allow reading the state if they choose to implement this differently. If this method is intended to be used, EnhancedRandom.getStateCount() must also be implemented.
      Overrides:
      getSelectedState in class EnhancedRandom
      Parameters:
      selection - used to select which state variable to get; generally non-negative
      Returns:
      the exact value of the selected state

    • setSelectedState

      public void setSelectedState(int selection, long value)
      Sets one of the wrapped generator's states. This does not update the current "deck" of 16 generated longs this uses, so you may want to call refill() after you're done setting states.
      Overrides:
      setSelectedState in class EnhancedRandom
      Parameters:
      selection - used to select which state variable to set; generally non-negative
      value - the exact value to use for the selected state, if valid

    • setState

      public void setState(long state)
      Sets each state variable to the given state. If getStateCount() is 1, then this should set the whole state to the given value using setSelectedState(int, long). If getStateCount() is more than 1, then all states will be set in the same way (using setSelectedState(), all to state). This calls refill() after setting all states, and sets index to 0.
      Overrides:
      setState in class EnhancedRandom
      Parameters:
      state - the long value to use for each state variable

    • setState

      public void setState(long stateA, long stateB)
      Sets each state variable to either stateA or stateB, alternating. This uses setSelectedState(int, long) to set the values. If there is one state variable (getStateCount() is 1), then this only sets that state variable to stateA. If there are two state variables, the first is set to stateA, and the second to stateB. If there are more, it reuses stateA, then stateB, then stateA, and so on until all variables are set. This calls refill() after setting all states, and sets index to 0.
      Overrides:
      setState in class EnhancedRandom
      Parameters:
      stateA - the long value to use for states at index 0, 2, 4, 6...
      stateB - the long value to use for states at index 1, 3, 5, 7...

    • setState

      public void setState(long stateA, long stateB, long stateC)
      Sets each state variable to stateA, stateB, or stateC, alternating. This uses setSelectedState(int, long) to set the values. If there is one state variable (getStateCount() is 1), then this only sets that state variable to stateA. If there are two state variables, the first is set to stateA, and the second to stateB. With three state variables, the first is set to stateA, the second to stateB, and the third to stateC. If there are more, it reuses stateA, then stateB, then stateC, then stateA, and so on until all variables are set. This calls refill() after setting all states, and sets index to 0.
      Overrides:
      setState in class EnhancedRandom
      Parameters:
      stateA - the long value to use for states at index 0, 3, 6, 9...
      stateB - the long value to use for states at index 1, 4, 7, 10...
      stateC - the long value to use for states at index 2, 5, 8, 11...

    • setState

      public void setState(long stateA, long stateB, long stateC, long stateD)
      Sets each state variable to stateA, stateB, stateC, or stateD, alternating. This uses setSelectedState(int, long) to set the values. If there is one state variable (getStateCount() is 1), then this only sets that state variable to stateA. If there are two state variables, the first is set to stateA, and the second to stateB. With three state variables, the first is set to stateA, the second to stateB, and the third to stateC. With four state variables, the first is set to stateA, the second to stateB, the third to stateC, and the fourth to stateD. If there are more, it reuses stateA, then stateB, then stateC, then stateD, then stateA, and so on until all variables are set. This calls refill() after setting all states, and sets index to 0.
      Overrides:
      setState in class EnhancedRandom
      Parameters:
      stateA - the long value to use for states at index 0, 4, 8, 12...
      stateB - the long value to use for states at index 1, 5, 9, 13...
      stateC - the long value to use for states at index 2, 6, 10, 14...
      stateD - the long value to use for states at index 3, 7, 11, 15...

    • setState

      public void setState(long stateA, long stateB, long stateC, long stateD, long stateE)
      Sets each state variable to stateA, stateB, stateC, stateD, or stateE, alternating. This uses setSelectedState(int, long) to set the values. If there is one state variable (getStateCount() is 1), then this only sets that state variable to stateA. If there are two state variables, the first is set to stateA, and the second to stateB. With three state variables, the first is set to stateA, the second to stateB, and the third to stateC. With four state variables, the first is set to stateA, the second to stateB, the third to stateC, and the fourth to stateD. If there are more, it reuses stateA, then stateB, then stateC, then stateD, then stateE, then stateA, and so on until all variables are set. This calls refill() after setting all states, and sets index to 0.
      Overrides:
      setState in class EnhancedRandom
      Parameters:
      stateA - the long value to use for states at index 0, 5, 10, 15...
      stateB - the long value to use for states at index 1, 6, 11, 16...
      stateC - the long value to use for states at index 2, 7, 12, 17...
      stateD - the long value to use for states at index 3, 8, 13, 18...
      stateE - the long value to use for states at index 4, 9, 14, 19...

    • setState

      public void setState(long stateA, long stateB, long stateC, long stateD, long stateE, long stateF)
      Sets each state variable to stateA, stateB, stateC, stateD, stateE, or stateF, alternating. This uses setSelectedState(int, long) to set the values. If there is one state variable (getStateCount() is 1), then this only sets that state variable to stateA. If there are two state variables, the first is set to stateA, and the second to stateB. With three state variables, the first is set to stateA, the second to stateB, and the third to stateC. With four state variables, the first is set to stateA, the second to stateB, the third to stateC, and the fourth to stateD. If there are more, it reuses stateA, then stateB, then stateC, then stateD, then stateE, then stateF, then stateA, and so on until all variables are set. This calls refill() after setting all states, and sets index to 0.
      Overrides:
      setState in class EnhancedRandom
      Parameters:
      stateA - the long value to use for states at index 0, 6, 12, 18...
      stateB - the long value to use for states at index 1, 7, 13, 19...
      stateC - the long value to use for states at index 2, 8, 14, 20...
      stateD - the long value to use for states at index 3, 9, 15, 21...
      stateE - the long value to use for states at index 4, 10, 16, 22...
      stateF - the long value to use for states at index 5, 11, 17, 23...

    • setState

      public void setState(long stateA, long stateB, long stateC, long stateD, long stateE, long stateF, long stateG)
      Sets each state variable to stateA, stateB, stateC, stateD, stateE, stateF, or stateG, alternating. This uses setSelectedState(int, long) to set the values. If there is one state variable (getStateCount() is 1), then this only sets that state variable to stateA. If there are two state variables, the first is set to stateA, and the second to stateB. With three state variables, the first is set to stateA, the second to stateB, and the third to stateC. With four state variables, the first is set to stateA, the second to stateB, the third to stateC, and the fourth to stateD. If there are more, it reuses stateA, then stateB, then stateC, then stateD, then stateE, then stateF, then stateG, then stateA, and so on until all variables are set.
      Overrides:
      setState in class EnhancedRandom
      Parameters:
      stateA - the long value to use for states at index 0, 7, 14, 21...
      stateB - the long value to use for states at index 1, 8, 15, 22...
      stateC - the long value to use for states at index 2, 9, 16, 23...
      stateD - the long value to use for states at index 3, 10, 17, 24...
      stateE - the long value to use for states at index 4, 11, 18, 25...
      stateF - the long value to use for states at index 5, 12, 19, 26...
      stateG - the long value to use for states at index 6, 13, 20, 27...

    • setState

      public void setState(long stateA, long stateB, long stateC, long stateD, long stateE, long stateF, long stateG, long stateH)
      Sets each state variable to stateA, stateB, stateC, stateD, stateE, stateF, stateG, or stateH, alternating. This uses setSelectedState(int, long) to set the values. If there is one state variable (getStateCount() is 1), then this only sets that state variable to stateA. If there are two state variables, the first is set to stateA, and the second to stateB. With three state variables, the first is set to stateA, the second to stateB, and the third to stateC. With four state variables, the first is set to stateA, the second to stateB, the third to stateC, and the fourth to stateD. If there are more, it reuses stateA, then stateB, then stateC, then stateD, then stateE, then stateF, then stateG, then stateH, then stateA, and so on until all variables are set.
      Overrides:
      setState in class EnhancedRandom
      Parameters:
      stateA - the long value to use for states at index 0, 8, 16, 24...
      stateB - the long value to use for states at index 1, 9, 17, 25...
      stateC - the long value to use for states at index 2, 10, 18, 26...
      stateD - the long value to use for states at index 3, 11, 19, 27...
      stateE - the long value to use for states at index 4, 12, 20, 28...
      stateF - the long value to use for states at index 5, 13, 21, 29...
      stateG - the long value to use for states at index 6, 14, 22, 30...
      stateH - the long value to use for states at index 7, 15, 23, 31...

    • setState

      public void setState(long stateA, long stateB, long stateC, long stateD, long stateE, long stateF, long stateG, long stateH, long stateI)
      Sets each state variable to stateA, stateB, stateC, stateD, stateE, stateF, stateG, stateH, or stateI, alternating. This uses setSelectedState(int, long) to set the values. If there is one state variable (getStateCount() is 1), then this only sets that state variable to stateA. If there are two state variables, the first is set to stateA, and the second to stateB. With three state variables, the first is set to stateA, the second to stateB, and the third to stateC. With four state variables, the first is set to stateA, the second to stateB, the third to stateC, and the fourth to stateD. If there are more, it reuses stateA, then stateB, then stateC, then stateD, then stateE, then stateF, then stateG, then stateH, then stateI, then stateA, and so on until all variables are set.
      Overrides:
      setState in class EnhancedRandom
      Parameters:
      stateA - the long value to use for states at index 0, 9, 18, 27...
      stateB - the long value to use for states at index 1, 10, 19, 28...
      stateC - the long value to use for states at index 2, 11, 20, 29...
      stateD - the long value to use for states at index 3, 12, 21, 30...
      stateE - the long value to use for states at index 4, 13, 22, 31...
      stateF - the long value to use for states at index 5, 14, 23, 32...
      stateG - the long value to use for states at index 6, 15, 24, 33...
      stateH - the long value to use for states at index 7, 16, 25, 34...
      stateI - the long value to use for states at index 8, 17, 26, 35...

    • setState

      public void setState(long stateA, long stateB, long stateC, long stateD, long stateE, long stateF, long stateG, long stateH, long stateI, long stateJ)
      Sets each state variable to stateA, stateB, stateC, stateD, stateE, stateF, stateG, stateH, stateI, or stateJ, alternating. This uses setSelectedState(int, long) to set the values. If there is one state variable (getStateCount() is 1), then this only sets that state variable to stateA. If there are two state variables, the first is set to stateA, and the second to stateB. With three state variables, the first is set to stateA, the second to stateB, and the third to stateC. With four state variables, the first is set to stateA, the second to stateB, the third to stateC, and the fourth to stateD. If there are more, it reuses stateA, then stateB, then stateC, then stateD, then stateE, then stateF, then stateG, then stateH, then stateI, then stateJ, then stateA, and so on until all variables are set.
      Overrides:
      setState in class EnhancedRandom
      Parameters:
      stateA - the long value to use for states at index 0, 10, 20, 30...
      stateB - the long value to use for states at index 1, 11, 21, 31...
      stateC - the long value to use for states at index 2, 12, 22, 32...
      stateD - the long value to use for states at index 3, 13, 23, 33...
      stateE - the long value to use for states at index 4, 14, 24, 34...
      stateF - the long value to use for states at index 5, 15, 25, 35...
      stateG - the long value to use for states at index 6, 16, 26, 36...
      stateH - the long value to use for states at index 7, 17, 27, 37...
      stateI - the long value to use for states at index 8, 18, 28, 38...
      stateJ - the long value to use for states at index 9, 19, 29, 39...

    • setState

      public void setState(long... states)
      Sets all state variables to alternating values chosen from states. If states is empty, then this does nothing, and leaves the current generator unchanged. This works for generators with any getStateCount(), but may allocate an array if states is used as a varargs (you can pass an existing array without needing to allocate). This uses setSelectedState(int, long) to change the states. This calls refill() after setting all states, and sets index to 0.
      Overrides:
      setState in class EnhancedRandom
      Parameters:
      states - an array or varargs of long values to use as states

    • getIndex

      public int getIndex()
      Gets the current index into the "deck" of 16 long results this shuffles.
      Returns:
      technically any int, but only the low 4 bits are used

    • setIndex

      public void setIndex(int index)
      Sets the current index into the "deck" of 16 long results this shuffles. Only the low 4 bits are used, so this is typically an int from 0 to 15, inclusive.
      Parameters:
      index - any int; only the low 4 bits are used, so this is typically an int from 0 to 15

    • getWrapped

      public EnhancedRandom getWrapped()

    • setWrapped

      public void setWrapped(EnhancedRandom wrapped)

    • previewAt

      public long previewAt(int index)
      Gets a long result by index from the "deck" of 16 long results this shuffles. This does not modify the deck or the index this normally uses. This can also be used, in limited cases, to get a previously-returned long even if it was consumed by another method, but that won't work if the "deck" was already shuffled after it was returned.
      Parameters:
      index - technically any int, but only the low 4 bits are used, so usually between 0 and 15, inclusive
      Returns:
      the long in the "deck" of future results at the given index.

    • preview

      public long preview()
      Previews the next result this will return, without changing the current index or the "deck" of long results.
      Returns:
      the next long result this will return via nextLong()

    • setResultAt

      public void setResultAt(int index, long value)
      Sets a result in the "deck" of 16 long results this shuffles. If index is less than getIndex(), both using only the bottom 4 bits (so index is usually 0 to 15 inclusive), the result will effectively be ignored because it will be setting a previous result. That can be read back using previewAt(int), but that's all it can do. Otherwise, it will set the next or later result in the deck.
      Parameters:
      index - technically any int, but only the low 4 bits are used, so usually between 0 and 15, inclusive
      value - the long to return in the deck at the given position

    • setNextResult

      public void setNextResult(long value)
      Sets the next result this will return from nextLong().
      Parameters:
      value - the next result this should return from nextLong()

    • refill

      public void refill()

    • equals

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

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • stringSerialize

      public String stringSerialize(com.github.tommyettinger.digital.Base base)
      Serializes the current state of this EnhancedRandom to a String that can be used by EnhancedRandom.stringDeserialize(String) to load this state at another time.
      Overrides:
      stringSerialize in class EnhancedRandom
      Parameters:
      base - which Base to use, from the "digital" library, such as Base.BASE10
      Returns:
      a String storing all data from the EnhancedRandom part of this generator

    • appendSerialized

      public <T extends CharSequence & Appendable> T appendSerialized(T sb, com.github.tommyettinger.digital.Base base)
      Description copied from class: EnhancedRandom
      Serializes the current state of this EnhancedRandom and appends it to an Appendable CharSequence (such as a StringBuilder), which may be used by EnhancedRandom.stringDeserialize(String) to load this state at another time. May use any Base; Base.BASE10 and Base.BASE16 are the most intuitive, but Base.SIMPLE64 and especially Base.BASE90 will be more compact.
      Overrides:
      appendSerialized in class EnhancedRandom
      Type Parameters:
      T - any type that is both a CharSequence and an Appendable, such as StringBuilder, StringBuffer, or CharBuffer
      Parameters:
      sb - an Appendable CharSequence that will be modified
      base - which Base to use, from the "digital" library, such as Base.BASE10
      Returns:
      sb, for chaining

    • stringDeserialize

      public DeckWrapper stringDeserialize(String data, com.github.tommyettinger.digital.Base base)
      Given a String in the format produced by stringSerialize(Base), and the same Base used by the serialization, this will attempt to set this EnhancedRandom object to match the state in the serialized data. This only works if this EnhancedRandom is the same implementation that was serialized, and also needs the Bases to be identical. Returns this EnhancedRandom, after possibly changing its state.
      Overrides:
      stringDeserialize in class EnhancedRandom
      Parameters:
      data - a String probably produced by stringSerialize(Base)
      base - which Base to use, from the "digital" library, such as Base.BASE10
      Returns:
      this, after setting its state
      See Also:

    • readExternal

      public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException
      Needs the type of wrapped registered with Deserializer.
      Specified by:
      readExternal in interface Externalizable
      Overrides:
      readExternal in class EnhancedRandom
      Parameters:
      in - the stream to read data from in order to restore the object
      Throws:
      IOException - if I/O errors occur
      ClassNotFoundException

    • writeExternal

      public void writeExternal(ObjectOutput out) throws IOException
      Needs the type of wrapped registered with Deserializer.
      Specified by:
      writeExternal in interface Externalizable
      Overrides:
      writeExternal in class EnhancedRandom
      Parameters:
      out - the stream to write the object to
      Throws:
      IOException - Includes any I/O exceptions that may occur