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.

The byte structure of the CSUUID is:

+-------------+-----------------+------------+
| 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^

1. Add the dependency to your shard.yml:

   dependencies:
     csuuid:
       github: wyhaines/csuuid.cr

2. Run shards install

require "csuuid"

uuid = CSUUID.new

uuid = CSUUID.new(seconds: 9223372036, nanoseconds: 729262400)

uuid = CSUUID.new(identifier: Random.new.random_bytes(6))

dt = ParseDate.parse("2020/07/29 09:15:37")
uuid = CSUUID.new(dt)

https://wyhaines.github.io/csuuid.cr/

1. Fork it (https://github.com/wyhaines/csuuid.cr/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

• Kirk Haines - creator and maintainer