12.56 rfc.uuid - UUID ¶

Module: rfc.uuid ¶

This module implements UUID defined in RFC9562.

It provides generators of UUID version 1, 4, 6 and 7, and writer/parser of the string represenation of UUIDs.

Class: <uuid> ¶

{rfc.uuid} Class of UUID instances. UUID instances are immutable.

Common uuid operations ¶

Function: uuid-value uuid ¶

{rfc.uuid} Returns the raw value of uuid as 16-element u8vector. You shouldn’t mutate the returned u8vector.

Function: uuid-version uuid ¶

{rfc.uuid} Returns the version number of uuid.

Variable: uuid-comparator ¶

{rfc.uuid} A comparator to compare and hash uuids. See Basic comparators.

Note: Equality of uuids can be tested with equal?.

Read/write UUIDs ¶

Function: parse-uuid string :key if-invalid ¶

{rfc.uuid} Takes a string representation of UUID, parses it and returns an uuid instance. If the string isn’t a valid UUID representation, an error is thrown if the if-invalid keyword argument is omitted or :error, and #f is returned if if-invalid is #f.

Other than XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX format, it recognizes the one with urn:uuid: prefix, the one enclosed by curly braces, and the one without hyphens.

Function: write-uuid uuid :optional port ¶

{rfc.uuid} Writes out a string representation of uuid, in XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX format, to the given port. If the port is omitted, current output port is used.

Function: uuid->string uuid ¶

{rfc.uuid} Returns a string representation of uuid, in XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX format.

UUID generator makers ¶

Parameter: uuid-random-source ¶

{rfc.uuid} We use PRNG to generate UUIDs. By default, we internally creates a random source and randomize it. You can alter the random source using parameterize. The value must be a SRFI-27 random source (see srfi.27 - Sources of Random Bits).

The value of this parameter is taken when a uuid generator is created by one of make-uuid*-generator. Once a generator is created, the random source is kept in the generator and won’t be affected by changing the value of this parameter.

Function: make-uuid1-generator :optional node-id ¶

Function: make-uuid6-generator :optional node-id ¶

{rfc.uuid} Returns new generators of uuid v1 and uuis v6 (timestamp and node id based), respectively.

The difference between version 1 and version 6 is the order of timestamp field; version 1 stores lower bits of timestamp first, while version 6 stores higher bits first. That makes v6 uuids created around the same time cluster together when sorted, making it favorable choice over v1 for database index. (However, if you need chronologically orderable uuids, you should use v7 uuids.)

The optional node-id argument must be 48bit exact integer specifing the node ID (IEEE802 MAC address of the machine). If it is omitted, we generate a process-global random node ID (with the multicast bit set to 1, so that it won’t conflict with existing MAC address).

The generators created by these procedures are thread-safe.

Function: make-uuid4-generator ¶

{rfc.uuid} Returns a new generator that yields uuids with version 4 algorithm (random numbers).

The generators created by this procedures are thread-safe.

Function: make-uuid7-generator :optional increment-bits ¶

{rfc.uuid} Returns a new generator that yields uuids with version 7 algorithm (time-ordered). The uuid consists of timestamp part, and monotonically increasing random bits. Overall, it is ordered chronologically.

The random bit part is splitted to 12bit rand_a field and 62bit rand_b field in UUID RFC. The RFC doesn’t precisely specify how to fill them. In our implementation, we treat it as 74bit unsigned integer, and use the following strategy:

• It is initialized with random integer per process.
• When a v7 uuid is asked, we increment the field with a random unsigned integer up to 2^increment-bits. If it does not overflow, we use it as is.
• If it does overflow, if the timestamp is already incremented from the previous generation, we use the wraparound value.
• Otherwise, we wait until the timestamp field is incremented, and then use the wraparound value.

The optional increment-bits argument must be an positive exact integer. The default value is 64. You may want to pass a smaller number if you need to create a lots of UUIDs in very short span of time.

The generators created by this procedures are thread-safe.

Function: uuid-random-source-set! random-source ¶

{rfc.uuid} Deprecated. Use uuid-random-source parameter to customize random source to be used in uuid generation.

Pre-created UUID generators ¶

Function: uuid1 :optional node-id ¶

Function: uuid4 ¶

Function: uuid6 :optional node-id ¶

Function: uuid7 ¶

{rfc.uuid} Pre-created uuid generators for convenience. Those generators are created with the corresponding make-uuid*-generator when the library is loaded, so they use the default random source.

These generators are thread-safe.

Function: nil-uuid ¶

{rfc.uuid} Returns a nil-UUID (all bits zero).