Package com.github.tommyettinger.random

Class ArchivalWrapper

java.lang.Object
java.util.Random
com.github.tommyettinger.random.EnhancedRandom
com.github.tommyettinger.random.ArchivalWrapper
All Implemented Interfaces:
Externalizable, Serializable, RandomGenerator
public class ArchivalWrapper extends EnhancedRandom
Wraps another EnhancedRandom and stores every long it returns from nextLong() in a LongSequence archive. If you don't want to store anymore, but still want the same state and other behavior of an ArchivalWrapper, you can assign LongSequence.NO_OP to the archive field. This can be critical, because just generating numbers non-stop and storing all of them would exhaust most computers' available memory in minutes, if not seconds.
See Also:

  • Field Details

  • Constructor Details

  • Method Details

    • getTag

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

    • setSeed

      public void setSeed(long seed)
      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 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()
      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 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

    • copy

      public ArchivalWrapper 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.

    • getSnapshot

      public LongSequence getSnapshot()
      Creates a copy of the current LongSequence archive and returns it.
      Returns:
      a copy of the current archive

    • getRepeatableRandom

      public KnownSequenceRandom getRepeatableRandom()
      Creates a KnownSequenceRandom that will repeat from a copy of the current archive.
      Returns:
      a new KnownSequenceRandom that will use a copy of the current archive

    • pauseStorage

      public LongSequence pauseStorage()
      Makes this ArchivalWrapper stop storing generated random numbers, and returns the current LongSequence this had before pausing. To resume where you started, call setArchive(LongSequence) with what this returned.
      Returns:
      the LongSequence this used before pausing; this can be used to resume later from this point

    • getArchive

      public LongSequence getArchive()

    • setArchive

      public void setArchive(LongSequence archive)

    • getStateCount

      public int getStateCount()
      Gets the number of possible state variables that can be selected with getSelectedState(int) or 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)
      Gets a selected state value from this EnhancedRandom. The number of possible selections is up to the implementing class, and is accessible via 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, 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 a selected state value to the given long value. The number of possible selections is up to the implementing class, but negative values for selection are typically not tolerated. Implementors are permitted to change value if it is not valid, but they should not alter it if it is valid. The public implementation calls setSeed(long) with value, which doesn't need changing if the generator has one state that is set verbatim by setSeed(). Otherwise, this method should be implemented when getSelectedState(int) is and the state is allowed to be set by users. Having accurate ways to get and set the full state of a random number generator makes it much easier to serialize and deserialize that class.
      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).
      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.
      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.
      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.
      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, 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.
      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... 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.
      Overrides:
      setState in class EnhancedRandom
      Parameters:
      states - an array or varargs of long values to use as states

    • 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 ArchivalWrapper 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

    • equals

      public 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

    • writeExternal

      public void writeExternal(ObjectOutput out) throws IOException
      Needs LongSequence registered, as well as the type of wrapped registered.
      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