Package squidpony.squidmath

Class SquidID

java.lang.Object
squidpony.squidmath.SquidID
All Implemented Interfaces:
Serializable, Comparable<SquidID>
public class SquidID
extends Object
implements Serializable, Comparable<SquidID>
A UUID-like identifier; not compatible with Java's standard UUID but will work on GWT.
Meant to be used as an identity type for things like SpatialMap, especially when no special game-specific logic is needed for identities.
Changed on April 27, 2018 so it isn't possible to generate two identical SquidIDs until 2 to the 128 minus 1 SquidIDs have been generated, which will take a while. Before, there was a small possibility that even two sequential SquidIDs could be the same, and the new way gives a better guarantee of how many can be produced without duplicates. Changed again on December 7, 2018 so the class can be automatically serialized by libGDX's Json class and other ways of reflection on GWT. Now this uses 4 ints instead of 2 longs, since libGDX reflection couldn't be used to serialize the long fields this used before. The random number generator has the same guarantee of 2 to the 128 minus 1 IDs, but uses a different algorithm, and it can be restarted now using store() and load(CharSequence).
Created by Tommy Ettinger on 4/30/2016.
See Also:
Serialized Form

  • Field Summary

    Fields 
    Modifier and Type Field Description
    int a  
    int b  
    int c  
    int d  

  • Constructor Summary

    Constructors 
    Constructor Description
    SquidID()
    Constructs a new random SquidID.
    SquidID​(int a, int b, int c, int d)
    Constructs a fixed SquidID with the given four 32-bit ints, which will be used exactly.
    SquidID​(long low, long high)
    Constructs a fixed SquidID with the given low and high 64-bit longs.

  • Method Summary

    Modifier and Type Method Description
    int compareTo​(SquidID o)  
    boolean equals​(Object o)  
    int getA()
    Gets the 32 least-significant bits as an int.
    int getB()
    Gets the 32 second-to-least-significant bits as an int.
    int getC()
    Gets the 32 second-to-most-significant bits as an int.
    int getD()
    Gets the 32 most-significant bits as an int.
    long getLeastSignificantBits()
    Gets the least-significant bits, also accessible by the field low.
    long getMostSignificantBits()
    Gets the most-significant bits, also accessible by the field high.
    int hashCode()  
    static void load​(CharSequence data)
    Makes the IDs generated after calling this repeatable, with the same IDs generated in order after this is called.
    static void randomize()
    Makes the IDs generated after calling this non-repeatable, with a random 128-bit seed.
    static SquidID randomUUID()
    Gets a new random SquidID, the same as calling the no-argument constructor.
    static void stabilize()
    Makes the IDs generated after calling this repeatable, with the same IDs generated in order after this is called.
    static StringBuilder store()  
    String toString()  

    Methods inherited from class java.lang.Object

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

  • Field Details

    • a

      public final int a

    • b

      public final int b

    • c

      public final int c

    • d

      public final int d

  • Constructor Details

    • SquidID

      public SquidID()
      Constructs a new random SquidID. If you want different random IDs with every run, the defaults should be fine. If you want stable IDs to be generated, use SquidID.stabilize(), but be careful about collisions!

    • SquidID

      public SquidID​(int a, int b, int c, int d)
      Constructs a fixed SquidID with the given four 32-bit ints, which will be used exactly.
      Parameters:
      a - the least-significant bits of the ID
      b - the second-to-least-significant bits of the ID
      c - the second-to-most-significant bits of the ID
      d - the most-significant bits of the ID

    • SquidID

      public SquidID​(long low, long high)
      Constructs a fixed SquidID with the given low and high 64-bit longs.
      Parameters:
      low - the least-significant bits of the ID
      high - the most-significant bits of the ID

  • Method Details

    • randomUUID

      public static SquidID randomUUID()
      Gets a new random SquidID, the same as calling the no-argument constructor. The name is for compatibility with Java's standard UUID class.
      Returns:
      a newly-constructed random SquidID.

    • stabilize

      public static void stabilize()
      Makes the IDs generated after calling this repeatable, with the same IDs generated in order after this is called. This class uses a random number generator with a random seed by default to produce IDs, and properties of the XoshiroStarPhi32RNG this uses make it incredibly unlikely that IDs will repeat even if the game was run for years without stopping. For the purposes of tests, you may want stable SquidID values to be generated, the same for every startup of the program, generating the same IDs in order. This will change the seed used internally to a constant (large) seed the first time it is called, and it should only be called at or near the start of your program, no more than once. If an ID is requested immediately after calling this method, and then this method is called again, the next ID to be generated will be identical to the previous one generated (a collision). There may be reasons you want this during testing, so there isn't any check for multiple calls to this method. If IDs can persist between runs of the game (i.e. saved in a file), using this is generally a bad idea, and you should instead use either random IDs or save the state with.
      You can "undo" the effects of this method with randomize(), changing the seed to a new random value.
      Because IDs aren't likely to have gameplay significance, this uses one seed, and is equivalent to calling SquidID.load("C13FA9A902A6328F91E10DA5C79E7B1D"), which are values based on the Plastic Constant (2 to the 64 divided by the plastic constant, upper 32 bits and then lower 32 bits, then the upper and lower bits of that number divided again by the plastic constant). Irrational numbers like the plastic constant generally have a good distribution of bits, which should help delay the point when the generator hits "zeroland" and produces multiple small numbers for a short while.

    • store

      public static StringBuilder store()

    • load

      public static void load​(CharSequence data)
      Makes the IDs generated after calling this repeatable, with the same IDs generated in order after this is called. This class uses a random number generator with a random seed by default to produce IDs, and properties of the XoshiroStarPhi32RNG this uses make it incredibly unlikely that IDs will repeat even if the game was run for years without stopping. For the purposes of tests, you may want stable SquidID values to be generated, the same for every startup of the program, generating the same IDs in order; you may also want this when loading a saved game. This will change the seed used internally to match a value that should have been produced by store() but can be any 32 hex digits, and it should only be called at or near the start of your program, no more than once per load of a save. If an ID is requested immediately after calling this method, and then this method is called again with the same data parameter, the next ID to be generated will be identical to the previous one generated (a collision). There may be reasons you want this during testing, so there isn't any check for multiple calls to this method. If IDs can persist between runs of the game (i.e. saved in a file), you can be fine with random IDs in almost all cases, or you can have more certainty by saving the last state of the generator using store() when saving and loading that state with this method later.
      You can "undo" the effects of this method with randomize(), changing the seed to a new random value.

    • randomize

      public static void randomize()
      Makes the IDs generated after calling this non-repeatable, with a random 128-bit seed. This class uses a random number generator with a random seed by default to produce IDs, and properties of the XoshiroStarPhi32RNG this uses make it incredibly unlikely that IDs will repeat even if the game was run for years without stopping. However, if you call stabilize(), generate some IDs, call stabilize() again, and generate some more IDs, the first, second, third, etc. IDs generated after each call will be identical -- hardly the unique ID you usually want. You can "undo" the effects of stabilize by calling this method, making the seed a new random value. This does not affect the constructor that takes two longs to produce an exact ID, nor will it change any existing IDs.

    • getLeastSignificantBits

      public long getLeastSignificantBits()
      Gets the least-significant bits, also accessible by the field low. The name is for compatibility with Java's standard UUID class.
      Returns:
      the least-significant bits as a long

    • getMostSignificantBits

      public long getMostSignificantBits()
      Gets the most-significant bits, also accessible by the field high. The name is for compatibility with Java's standard UUID class.
      Returns:
      the most-significant bits as a long

    • getA

      public int getA()
      Gets the 32 least-significant bits as an int.
      Returns:
      an int with the 32 least-significant bits of this ID

    • getB

      public int getB()
      Gets the 32 second-to-least-significant bits as an int.
      Returns:
      an int with the 32 second-to-least-significant bits of this ID

    • getC

      public int getC()
      Gets the 32 second-to-most-significant bits as an int.
      Returns:
      an int with the 32 second-to-most-significant bits of this ID

    • getD

      public int getD()
      Gets the 32 most-significant bits as an int.
      Returns:
      an int with the 32 most-significant bits of this ID

    • 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

    • compareTo

      public int compareTo​(SquidID o)
      Specified by:
      compareTo in interface Comparable<SquidID>