Package com.github.tommyettinger.random

Class KnownSequenceRandom

java.lang.Object
java.util.Random
com.github.tommyettinger.random.EnhancedRandom
com.github.tommyettinger.random.KnownSequenceRandom
All Implemented Interfaces:
Externalizable, Serializable, RandomGenerator
public class KnownSequenceRandom extends EnhancedRandom
A non-random number generator that simply repeats the next of a sequence of long values every time nextLong() is called. Because other methods rely on nextLong()'s exact output, even if they don't use all of it, storing long values is usually enough to repeat any sequence of calls made to a generator. This is meant to be useful for things like unit tests or procedural generation, where a particular group of outputs should be exactly replicable.
See Also:

  • Field Details

    • known

      public LongSequence known
      The sequence of long values this draws results from. This is public for ease of serialization, but it should typically not be modified in a way that changes its length unless you call setState(long) after.

    • index

      public int index
      The index into the sequence of values this draws results from. This is public for ease of serialization. To change this, using setState(long) is recommended.

  • Constructor Details

    • KnownSequenceRandom

      public KnownSequenceRandom()

    • KnownSequenceRandom

      public KnownSequenceRandom(LongSequence seq)

    • KnownSequenceRandom

      public KnownSequenceRandom(LongSequence seq, int position)

  • Method Details

    • getTag

      public String getTag()
      Gets the tag used to identify this type of EnhancedRandom, which is "KnSR".
      Specified by:
      getTag in class EnhancedRandom
      Returns:
      the constant String "KnSR"

    • setSeed

      public void setSeed(long position)
      Sets the position of the iteration this makes through its known sequence.
      Specified by:
      setSeed in class EnhancedRandom
      Parameters:
      position - usually a positive int less than known.size, but this technically can be any long

    • nextLong

      public long nextLong()
      Returns the next long value from this generator's sequence. This "generator" only cycles through a known sequence of values; it does not actually do any math to generate random numbers.
      All other "random" number generation methods in this class call this method, so if another class also relies on nextLong() for all randomness, then recording each of those nextLong() outputs in a LongSequence will allow a section of a generator to be played back more or less exactly.
      Specified by:
      nextLong in interface RandomGenerator
      Specified by:
      nextLong in class EnhancedRandom
      Returns:
      the next long from the known sequence

    • copy

      public KnownSequenceRandom copy()
      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.

    • getStateCount

      public int getStateCount()
      Returns 1, referring to the one state this changes on its own (index). This does not include the potentially many values in the known sequence.
      Overrides:
      getStateCount in class EnhancedRandom
      Returns:
      one (1)

    • getSelectedState

      public long getSelectedState(int selection)
      Gets the current index/position in the known sequence.
      Overrides:
      getSelectedState in class EnhancedRandom
      Parameters:
      selection - ignored
      Returns:
      the exact value of index

    • setSelectedState

      public void setSelectedState(int selection, long value)
      Sets the index/position in the known sequence, if value is at least equal to 0 and less than known.size. If value is outside that range, this can assign any value inside the range to the index. If known.size is 0 or less, this always assigns 0 to index (anticipating some change to the known sequence before it is used, hopefully).
      Overrides:
      setSelectedState in class EnhancedRandom
      Parameters:
      selection - ignored
      value - the value to use for index, if at least equal to 0 and less than known.size

    • setState

      public void setState(long state)
      Sets the index/position in the known sequence, if state is at least equal to 0 and less than known.size. If state is outside that range, this can assign any value inside the range to the index. If known.size is 0 or less, this always assigns 0 to index (anticipating some change to the known sequence before it is used, hopefully).
      Overrides:
      setState in class EnhancedRandom
      Parameters:
      state - the value to use for index, if at least equal to 0 and less than known.size

    • previousLong

      public long previousLong()
      Optional; moves the state to its previous value and returns the previous long that would have been produced by nextLong(). This is often equivalent to calling EnhancedRandom.skip(long) with -1L, but not always; some generators can't efficiently skip long distances, but can step back by one value.

      The public implementation calls EnhancedRandom.skip(long) with -1L, and if skip() has not been implemented differently, then it will throw an UnsupportedOperationException.

      Overrides:
      previousLong in class EnhancedRandom
      Returns:
      the previous number this would have produced with nextLong()

    • getKnown

      public LongSequence getKnown()
      Returns the current known sequence this draws its results from. While this can be modified, changing the length of the returned sequence is strongly discouraged, since it can cause indices to go out-of-bounds. If you do change the length of the returned sequence, you should call setState(long) before obtaining any values from this generator.
      Returns:
      the current known sequence of long results

    • setKnown

      public void setKnown(LongSequence known)
      Changes the known sequence this draws its results from. If the previous known sequence has a different length from the new known sequence, this resets the index in the sequence to 0.
      Parameters:
      known - a LongSequence that cannot be null and should generally not be empty

    • appendSerialized

      public StringBuilder appendSerialized(StringBuilder sb, com.github.tommyettinger.digital.Base base)

    • appendSerialized

      public StringBuilder appendSerialized(StringBuilder sb)

    • 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

    • stringDeserialize

      public KnownSequenceRandom 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

    • writeExternal

      public void writeExternal(ObjectOutput out) throws IOException
      The object implements the writeExternal method to save its contents by calling the methods of DataOutput for its primitive values or calling the writeObject method of ObjectOutput for objects, strings, and arrays.
      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

    • readExternal

      public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException
      The object implements the readExternal method to restore its contents by calling the methods of DataInput for primitive types and readObject for objects, strings and arrays. The readExternal method must read the values in the same sequence and with the same types as were written by writeExternal.
      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

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

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

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object