(std uuid)

Overview

Uuids as RFC 9562 specifies them: random, time-ordered and name-based.

(import (std uuid))

(uuid-v4)                                  ; random
(uuid-v7)                                  ; starts with the time, so it sorts by time
(uuid-v5 uuid-ns-dns "www.example.com")    ; the same input, the same uuid
(uuid->string (uuid-v4))                   ; "3f2c9b1e-..."
(string->uuid "6ba7b810-9dad-11d1-80b4-00c04fd430c8")   ; (Some ...)

A Uuid is 16 bytes. Two uuids compare as their bytes compare. That is also the order of their text in lower case, and the order of the uuid type in Postgres.

Which version. Use uuid-v4 for an identifier that must tell nothing. Use uuid-v7 for a database key: it starts with the time, so new keys go at the end of an index, and keys sort by the time they were made. A version 7 uuid tells when it was made. Use uuid-v5 when the same input must give the same uuid.

Version 7 uuids from one process always increase. When two are made in the same millisecond, or the clock steps back, the second is the first plus one, as RFC 9562 section 6.2 allows.

The random bits come from current-random, and the time from current-clock. In a with-random-seed, the same uuids are made again in each run, which is correct for a test and wrong for a real key.

The text has one form: 36 characters, 8-4-4-4-12 hex digits. string->uuid reads it in either case, and nothing else: no braces, no urn:uuid: and no form without hyphens.

Reference

Types

`Uuid`

record ↑ Types

A uuid: 16 bytes, compared as bytes.

Opaque. Make one with uuid-v4, uuid-v7, uuid-v5, uuid-v3, string->uuid or bytes->uuid. =, compare, written and displayed work on it.

Functions

`uuid-v4`

function ↑ Functions

(: uuid-v4 (-> (#:rng RandomSource) Uuid))
(uuid-v4 #:rng (parameter-ref current-random))

A random uuid: 122 random bits.

#:rng: The source of the random bits. The default is current-random.
returns: A version 4 uuid.

`uuid-v7`

function ↑ Functions

(: uuid-v7 (-> (#:clock Clock) (#:rng RandomSource) Uuid))
(uuid-v7 #:clock (parameter-ref current-clock) #:rng (parameter-ref current-random))

A uuid that starts with the time, so it sorts by the time it was made.

#:clock: The clock to read the time from. The default is current-clock.
#:rng: The source of the 74 random bits. The default is current-random.
returns: A version 7 uuid, greater than every other version 7 uuid this process made.

`uuid-v5`

function ↑ Functions

(: uuid-v5 (-> Uuid string Uuid))
(uuid-v5 namespace name)

A uuid from a namespace and a name, with SHA-1.

namespace: A uuid that names the kind of name, such as uuid-ns-dns.
name: The name. Its UTF-8 bytes are hashed.
returns: A version 5 uuid. The same namespace and name always give the same uuid.

(uuid->string (uuid-v5 uuid-ns-dns "www.example.com"))
;; "2ed6657d-e927-568b-95e1-2665a8aea6a2"

`uuid-v3`

function ↑ Functions

(: uuid-v3 (-> Uuid string Uuid))
(uuid-v3 namespace name)

As uuid-v5, with MD5 in place of SHA-1.

namespace: A uuid that names the kind of name.
name: The name. Its UTF-8 bytes are hashed.
returns: A version 3 uuid. Use uuid-v5 unless a system already uses version 3.

`uuid->string`

function ↑ Functions

(: uuid->string (-> Uuid (#:upper bool) string))
(uuid->string u #:upper #f)

The 36-character text: 8-4-4-4-12 hex digits.

u: The uuid.
#:upper: Upper case when #t. The default is lower case.
returns: A string such as "6ba7b810-9dad-11d1-80b4-00c04fd430c8".

`string->uuid`

function ↑ Functions

(: string->uuid (-> string (Option Uuid)))
(string->uuid text)

The uuid that a 36-character text gives.

text: 8-4-4-4-12 hex digits, in either case.
returns: None for any other text.

`uuid-string?`

function ↑ Functions

(: uuid-string? (-> string bool))
(uuid-string? text)

True when string->uuid reads the text.

text: The text.
returns: True or false.

`uuid->bytes`

function ↑ Functions

(: uuid->bytes (-> Uuid (Array byte)))
(uuid->bytes u)

The 16 bytes, in network byte order.

u: The uuid.
returns: A new array of 16 bytes.

`bytes->uuid`

function ↑ Functions

(: bytes->uuid (-> (Array byte) (Option Uuid)))
(bytes->uuid bytes)

The uuid that 16 bytes give.

bytes: The bytes, in network byte order.
returns: None unless there are exactly 16 bytes.

`uuid-version`

function ↑ Functions

(: uuid-version (-> Uuid int))
(uuid-version u)

The 4 version bits.

u: The uuid.
returns: 4 for uuid-v4, 7 for uuid-v7, 5 and 3 for the name-based ones, 0 for uuid-nil.

`uuid-v7-time`

function ↑ Functions

(: uuid-v7-time (-> Uuid (Option Instant)))
(uuid-v7-time u)

When a version 7 uuid was made, to the millisecond.

u: The uuid.
returns: None when the uuid is not version 7.

`uuid->guid`

function ↑ Functions

(: uuid->guid (-> Uuid Guid))
(uuid->guid u)

A System.Guid with the same 16 bytes, for a .NET library.

u: The uuid.
returns: The Guid.

A Guid keeps its first three fields in the byte order of the machine, and its CompareTo does not compare the bytes in order. Compare the Uuid, not the Guid.

`guid->uuid`

function ↑ Functions

(: guid->uuid (-> Guid Uuid))
(guid->uuid g)

The uuid with the same 16 bytes as a System.Guid.

g: The Guid.
returns: The uuid.

Values

`uuid-nil`

value ↑ Values

(: uuid-nil Uuid)

The uuid with all 128 bits zero.

`uuid-max`

value ↑ Values

(: uuid-max Uuid)

The uuid with all 128 bits one. No uuid is greater.

`uuid-ns-dns`

value ↑ Values

(: uuid-ns-dns Uuid)

The namespace for a DNS name, for uuid-v5.

`uuid-ns-url`

value ↑ Values

(: uuid-ns-url Uuid)

The namespace for a URL, for uuid-v5.

`uuid-ns-oid`

value ↑ Values

(: uuid-ns-oid Uuid)

The namespace for an ISO OID, for uuid-v5.

`uuid-ns-x500`

value ↑ Values

(: uuid-ns-x500 Uuid)

The namespace for an X.500 DN, for uuid-v5.