struct CSUUID

• CSUUID
• Struct
• Value
• Object

Overview

This struct wraps up a UUID that encodes a timestamp measured as seconds from the epoch (0001-01-01 00:00:00.0 UTC) observed at the location where the timestamp was generated, plus nanoseconds in the current second, plus 6 bytes for unique identification of the source -- this could be an IPV4 address with two null bytes, a MAC address, or some other sequence that will fit in 6 bytes.

Nanoseconds will fit in an Int32 (4 bytes), but seconds since the epoch will not. The current number of seconds leaks a short distance into a 5th byte, meaning that in this class, it has to be represented by an Int64. This is problematic because a UID allows for 16 bytes, so the use of 8 for seconds and 4 for nanoseconds leaves only 4 bytes for system identification. It also leaves three bytes in the UUID as zeros because 8 bytes for seconds is a lot of seconds.

One solution is to combine the seconds and the nanoseconds into a single Int64 number. This requires math operations to do efficiently: (seconds * 1000000000) + nanoseconds and then more math to extract the original numbers in order to reconstruct the original timestamp. This leaves 8 bytes for identification or other uniqueness information, which is lovely, but the math requirement is less lovely.

The other options is to truncate 2 bytes off of the seconds, storing 6 bytes of seconds data. This leaves 6 bytes for identification.

The current implementation chose option #2, as it is less work to generate a UUID if math is not involved.

Thus, the byte structure of a CSUUID is as follows:

An argument could be made for decreasing the nanosecond resolution to something more granular, and adding those bytes to the identifier/entropy portion of the ID, but as designed this structure allows for very precise sorting of the IDs.

+-------------+-----------------+------------+
| nanoseconds |     seconds     | identifier |
|    0..3     |      4..10      |   11..15   |
+-------------+-----------------+------------+

The representational structure of the CSUUID, however, is itself sortable, as are the objects themselves.

.00.0e.d9.eb.-.7e.05.-.08.ae.-.f2.9c.-.df.18.10.1c.4a.dc.
^      seconds       ^  nanoseconds  ^identifier/entropy^

Defined in:

csuuid.cr
version.cr

Constant Summary

VERSION = "1.0.1"

Constructors

• .new(seconds : Int64, nanoseconds : Int32, identifier : Slice(UInt8) | String | Nil = nil)

  Create a new CSUUID from the given seconds, nanoseconds, and optional identifier/entropy.

• .new(uuid : String)

  Create a new CSUUID from the string representation of a UUID, with or without dashes.

• .new(uuid : UUID | CSUUID)

  Create a new CSUUID from a given UUID or CSUUID object.

• .new(timestamp : Time, identifier : Slice(UInt8) | String | Nil = nil)

  Create a new CSUUID from the given Time object and optional identifier/entropy.

• .new(identifier : Slice(UInt8) | Nil = nil)

  Create a new CSUUID from the given identifier/entropy value alone.

Class Method Summary

• .generate(count)

  Generate a sequence of CSUUIDS of the requested count length.

• .prng : Random

  CSUUID will work with any source of entropy that inherits from Random.

• .prng=(prng : Random)

  CSUUID will work with any source of entropy that inherits from Random.

• .unique

  Generate a guaranteed unique (for this process) CSUUID.

Instance Method Summary

• #<(other : CSUUID) : Bool

  Returns true if self is less than other.

• #<=(other : CSUUID) : Bool

  Returns true if self is less than or equal to other.

• #<=>(other : CSUUID)

  Compare two CSUUID objects, returning -1 if the first is less than the second, 0 if they are equal, and 1 if the first is greater than the second.

• #>(other : CSUUID) : Bool

  Returns true if self is greater than other.

• #>=(other : CSUUID) : Bool

  Returns true if self is greater than or equal to other.

• #bytes : Slice(UInt8)

  A getter to allow access to the raw byte buffer for the CSUUID.

• #seconds_and_nanoseconds : Tuple(Int64, Int32)

  This returns a tuple containing the seconds since the epoch as well as the nanoseconds in the current second for the UUID.

• #timestamp : Time

  Return a Time object representing the timestamp encoded into the UUID as local time.

• #to_s(io : IO) : Nil

  Return the String representation of the UUID.

• #utc : Time

  Return a Time object representing the timestamp encoded into the UUID as UTC time.

Constructor Detail

Class Method Detail

Instance Method Detail