Skip to content

std::uuid

UUIDs (RFC 9562): 128-bit identifiers that cross JSON, URLs and databases. Uuid is an opaque type: its values come from parsing, from bytes, or from generation, and it is Equatable, Hashable and Comparable. The functions are owner functions of Uuid (Uuid.parse(text)). A Uuid is written as 32 hexadecimal digits in five groups, 0190a0b2-7f3c-7c3e-8a1b-1f2e3d4c5b6a. Read text with Uuid.parse, write a fixed one as the raw typed literal Uuid"0190a0b2-7f3c-7c3e-8a1b-1f2e3d4c5b6a", which is checked when the program is checked, and make new ones with Uuid.v4 (random) or Uuid.v7 (time-ordered, the better database key). Display gives the lowercase hyphenated form. Two UUIDs compare by their 128 bits, as their text and their bytes do, so v7 identifiers sort by creation time.

Import with import std::uuid.

Types

struct Uuid

opaque — construction surface is private to its defining module

A UUID: 128 bits, held as two 64-bit halves.

Equal UUIDs are ==, hash alike, and compare by their bits as unsigned numbers, so a list of v7 UUIDs sorts by creation time.

id = Uuid"0190A0B2-7F3C-7C3E-8A1B-1F2E3D4C5B6A"
assert Display.to_string(id) == "0190a0b2-7f3c-7c3e-8a1b-1f2e3d4c5b6a"
assert Uuid.version(id) == 7
fn nil() -> Uuid

type function on Uuid

The nil UUID, all 128 bits zero.

assert Display.to_string(Uuid.nil()) == "00000000-0000-0000-0000-000000000000"
fn from_bytes(data: Bytes) -> Result<Uuid, Error>

type function on Uuid

The UUID whose 16 bytes, most significant first, are data, as bytea and BLOB columns hold it.

id = Uuid"6ba7b810-9dad-11d1-80b4-00c04fd430c8"
assert Uuid.from_bytes(Uuid.to_bytes(id)) == Ok(id)
assert Uuid.from_bytes(Bytes.from_list([])) == Err(Error.Length{length: 0})
fn to_bytes(id: Uuid) -> Bytes

type function on Uuid

The 16 bytes of id, most significant first.

assert Bytes.length(Uuid.to_bytes(Uuid.nil())) == 16
fn version(id: Uuid) -> Int

type function on Uuid

The version field: 4 for a random UUID, 7 for a time-ordered one, 1 to 8 for the others RFC 9562 defines, 0 for the nil UUID.

assert Uuid.version(Uuid"6ba7b810-9dad-11d1-80b4-00c04fd430c8") == 1
fn v4() -> Result<Uuid, random.Error>

type function on Uuid

A version 4 UUID: 122 random bits from the operating system’s entropy source, with the version and the variant set. It is Err(.OsEntropy{reason:}) when the entropy source is unavailable, as Seed.from_os is.

id = Uuid.v4()?
assert Uuid.version(id) == 4
fn v7() -> Result<Uuid, random.Error>

type function on Uuid

A version 7 UUID: the Unix time in milliseconds from Instant.now in the first 48 bits, then the 74 bits that are not the version or the variant from the operating system’s entropy source. UUIDs made in later milliseconds compare greater, so v7 keys keep a database index in insertion order; two made in the same millisecond are in random order. Under a test group’s virtual clock the time is the virtual one. It is Err(.OsEntropy{reason:}) when the entropy source is unavailable, as Seed.from_os is.

id = Uuid.v7()?
assert Uuid.version(id) == 7

impl Parse<Error> for Uuid

fn parse(text: String) -> Result<Uuid, Error>

impl Parse.parse

Read the 36-character hyphenated form, in either case. Braces, a urn:uuid: prefix and the 32-digit form without hyphens are not accepted.

assert Display.to_string(Uuid.parse("6BA7B810-9DAD-11D1-80B4-00C04FD430C8")?)
    == "6ba7b810-9dad-11d1-80b4-00c04fd430c8"

assert Uuid.parse("6ba7b810") == Err(Error.Length{length: 8})

assert Uuid.parse("6ba7b810+9dad-11d1-80b4-00c04fd430c8")
    == Err(Error.Separator{index: 8, found: "+"})

assert Uuid.parse("6ba7b81g-9dad-11d1-80b4-00c04fd430c8") == Err(Error.Digit{index: 7, found: "g"})

impl Comparable for Uuid

fn compare(a: Uuid, b: Uuid) -> Ordering

impl Comparable.compare

By the 128 bits as an unsigned number, which is the order of the text and of the bytes.

assert Uuid"00000000-0000-0000-0000-000000000001" < Uuid"ffffffff-0000-0000-0000-000000000000"

impl Literal for Uuid

fn from_fragments(fragments: List<Fragment<String>>) -> Result<Uuid, Error>

impl Literal.from_fragments

Uuid"6ba7b810-9dad-11d1-80b4-00c04fd430c8" is the UUID Uuid.parse reads from its text. A literal without slots is checked when the program is checked, so a malformed one is a compile error at the literal.

impl ToJson for Uuid

fn to_json(value: Uuid) -> Json

impl ToJson.to_json

Writes the canonical lowercase text, 8-4-4-4-12 hex digits.

id = Uuid"6BA7B810-9DAD-11D1-80B4-00C04FD430C8"
assert ToJson.to_json(id) == Json.String("6ba7b810-9dad-11d1-80b4-00c04fd430c8")

impl FromJson for Uuid

fn from_json(json: Json) -> Result<Uuid, Json.ShapeError>

impl FromJson.from_json

Reads UUID text in either case.

id = Uuid"6ba7b810-9dad-11d1-80b4-00c04fd430c8"
assert Uuid.from_json(ToJson.to_json(id)) == Ok(id)
assert Uuid.from_json(Json.String("6BA7B810-9DAD-11D1-80B4-00C04FD430C8")) == Ok(id)

assert Uuid.from_json(Json.String("6ba7b810")) |> Result.map_err(&Display.to_string(&1)) == Err(
    "expected UUID as 8-4-4-4-12 hex digits, got string \"6ba7b810\""
)

impl Display for Uuid

fn to_string(id: Uuid) -> String

impl Display.to_string

The lowercase hyphenated form.

impl Debug for Uuid

fn inspect(id: Uuid) -> String

impl Debug.inspect

The typed literal that builds the UUID.

impl Equatable for Uuid

fn equal(a: Uuid, b: Uuid) -> Bool

impl Equatable.equal

impl Hashable for Uuid

fn hash(value: Uuid) -> Int

impl Hashable.hash

enum Error
    Length { length: Int }
    Separator { index: Int, found: String }
    Digit { index: Int, found: String }
end

Why text or bytes are not a UUID. index counts characters from 0.

Variants

  • Length

    The text is not 36 characters, or the bytes are not 16.

  • Separator

    The character at index should be the hyphen between two groups.

  • Digit

    The character at index should be a hexadecimal digit.

impl Display for Error

fn to_string(e: Error) -> String

impl Display.to_string

impl Debug for Error

fn inspect(value: Error) -> String

impl Debug.inspect

impl Equatable for Error

fn equal(a: Error, b: Error) -> Bool

impl Equatable.equal