Module com.github.f4b6a3.ulid
Package com.github.f4b6a3.ulid

Class Ulid

  • All Implemented Interfaces:
    Serializable, Comparable<Ulid>
    public final class Ulid
extends Object
implements Serializable, Comparable<Ulid>
    This class represents a ULID. The ULID has two components: - Time component: a part of 48 bits that represent the amount of milliseconds since Unix Epoch, 1970-01-01. - Random component: a byte array of 80 bits that has a random value generated a secure random generator. Instances of this class are immutable.
    See Also:
    Serialized Form

    • Constructor Detail

      • Ulid

        public Ulid​(Ulid ulid)
        Create a new ULID. Useful to make copies of ULIDs.
        Parameters:
        ulid - a ULID

      • Ulid

        public Ulid​(long mostSignificantBits,
            long leastSignificantBits)
        Create a new ULID.
        Parameters:
        mostSignificantBits - the first 8 bytes as a long value
        leastSignificantBits - the last 8 bytes as a long value

      • Ulid

        public Ulid​(long time,
            byte[] random)
        Create a new ULID.
        Parameters:
        time - the time component in milliseconds since 1970-01-01
        random - the random component in byte array

    • Method Detail

      • from

        public static Ulid from​(UUID uuid)
        Converts a UUID into a ULID.
        Parameters:
        uuid - a UUID
        Returns:
        a ULID

      • from

        public static Ulid from​(byte[] bytes)
        Converts a byte array into a ULID.
        Parameters:
        bytes - a byte array
        Returns:
        a ULID

      • from

        public static Ulid from​(String string)
        Converts a canonical string into a ULID. The input string must be 26 characters long and must contain only characters from Crockford's base 32 alphabet. The first character of the input string must be between 0 and 7.
        Parameters:
        string - a canonical string
        Returns:
        a ULID

      • toUuid

        public UUID toUuid()
        Convert the ULID into a UUID. If you need a RFC-4122 UUID v4 do this: Ulid.toRfc4122().toUuid().
        Returns:
        a UUID.

      • toBytes

        public byte[] toBytes()
        Convert the ULID into a byte array.
        Returns:
        an byte array.

      • toString

        public String toString()
        Converts the ULID into a canonical string in upper case. The output string is 26 characters long and contains only characters from Crockford's base 32 alphabet. For lower case string, use the shorthand Ulid#toLowerCase(), instead of Ulid#toString()#toLowerCase(). See: https://www.crockford.com/base32.html
        Overrides:
        toString in class Object
        Returns:
        a ULID string

      • toLowerCase

        public String toLowerCase()
        Converts the ULID into a canonical string in lower case. The output string is 26 characters long and contains only characters from Crockford's base 32 alphabet. It is a shorthand at least twice as fast as Ulid.toString().toLowerCase(). See: https://www.crockford.com/base32.html
        Returns:
        a string

      • toRfc4122

        public Ulid toRfc4122()
        Converts the ULID into into another ULID that is compatible with UUID v4. The bytes of the returned ULID are compliant with the RFC-4122 version 4. If you need a RFC-4122 UUID v4 do this: Ulid.toRfc4122().toUuid(). Read: https://tools.ietf.org/html/rfc4122 ### RFC-4122 - 4.4. Algorithms for Creating a UUID from Truly Random or Pseudo-Random Numbers The version 4 UUID is meant for generating UUIDs from truly-random or pseudo-random numbers. The algorithm is as follows: - Set the two most significant bits (bits 6 and 7) of the clock_seq_hi_and_reserved to zero and one, respectively. - Set the four most significant bits (bits 12 through 15) of the time_hi_and_version field to the 4-bit version number from Section 4.1.3. - Set all the other bits to randomly (or pseudo-randomly) chosen values.
        Returns:
        a ULID

      • getInstant

        public Instant getInstant()
        Returns the instant of creation. The instant of creation is extracted from the time component.
        Returns:
        Instant

      • getInstant

        public static Instant getInstant​(String string)
        Returns the instant of creation. The instant of creation is extracted from the time component.
        Parameters:
        string - a canonical string
        Returns:
        Instant

      • getTime

        public long getTime()
        Returns the time component as a number. The time component is a number between 0 and 2^48-1. It is equivalent to the count of milliseconds since 1970-01-01 (Unix epoch).
        Returns:
        a number of milliseconds.

      • getTime

        public static long getTime​(String string)
        Returns the time component as a number. The time component is a number between 0 and 2^48-1. It is equivalent to the count of milliseconds since 1970-01-01 (Unix epoch).
        Parameters:
        string - a canonical string
        Returns:
        a number of milliseconds.

      • getRandom

        public byte[] getRandom()
        Returns the random component as a byte array. The random component is an array of 10 bytes (80 bits).
        Returns:
        a byte array

      • getRandom

        public static byte[] getRandom​(String string)
        Returns the random component as a byte array. The random component is an array of 10 bytes (80 bits).
        Parameters:
        string - a canonical string
        Returns:
        a byte array

      • getMostSignificantBits

        public long getMostSignificantBits()
        Returns the most significant bits as a number.
        Returns:
        a number.

      • getLeastSignificantBits

        public long getLeastSignificantBits()
        Returns the least significant bits as a number.
        Returns:
        a number.

      • increment

        public Ulid increment()
        Returns a new ULID by incrementing the random component of the current ULID. Since the random component contains 80 bits: (1) This method can generate up to 1208925819614629174706176 (2^80) ULIDs per millisecond; (2) This method can generate monotonic increasing ULIDs 99.999999999999992% ((2^80 - 10^9) / (2^80)) of the time, considering an unrealistic rate of 1,000,000,000 ULIDs per millisecond. Due to (1) and (2), it does not throw the error message recommended by the specification. When an overflow occurs in the last 80 bits, the random component simply wraps around.
        Returns:
        a ULID

      • isValid

        public static boolean isValid​(String string)
        Checks if the input string is valid. The input string must be 26 characters long and must contain only characters from Crockford's base 32 alphabet. The first character of the input string must be between 0 and 7.
        Parameters:
        string - a string
        Returns:
        true if valid

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object

      • toString

        protected String toString​(char[] alphabet)

      • toCharArray

        protected static char[] toCharArray​(String string)

      • isValidCharArray

        protected static boolean isValidCharArray​(char[] chars)
        Checks if the string is a valid ULID. A valid ULID string is a sequence of 26 characters from Crockford's base 32 alphabet. The first character of the input string must be between 0 and 7.
        Parameters:
        chars - a char array
        Returns:
        boolean true if valid