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.
Exports
Section titled “Exports”struct Uuid
Section titled “struct Uuid”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
Uuid.nil
Section titled “Uuid.nil”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"
Uuid.from_bytes
Section titled “Uuid.from_bytes”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})
Uuid.to_bytes
Section titled “Uuid.to_bytes”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
Uuid.version
Section titled “Uuid.version”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
Uuid.v4
Section titled “Uuid.v4”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
Uuid.v7
Section titled “Uuid.v7”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
Uuid.parse
Section titled “Uuid.parse”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"})
Uuid.compare
Section titled “Uuid.compare”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"
Uuid.from_fragments
Section titled “Uuid.from_fragments”impl Literal for Uuid
fn from_fragments(fragments: List<Fragment<String>>) -> Result<Uuid, Error>
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.
Uuid.to_json
Section titled “Uuid.to_json”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")
Uuid.from_json
Section titled “Uuid.from_json”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\""
)
Uuid.to_string
Section titled “Uuid.to_string”impl Display for Uuid
fn to_string(id: Uuid) -> String
impl Display.to_string
The lowercase hyphenated form.
Uuid.inspect
Section titled “Uuid.inspect”impl Debug for Uuid
fn inspect(id: Uuid) -> String
impl Debug.inspect
The typed literal that builds the UUID.
Uuid.equal
Section titled “Uuid.equal”impl Equatable for Uuid
fn equal(a: Uuid, b: Uuid) -> Bool
impl Equatable.equal
Uuid.hash
Section titled “Uuid.hash”impl Hashable for Uuid
fn hash(value: Uuid) -> Int
impl Hashable.hash
enum Error
Section titled “enum Error”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
-
LengthThe text is not 36 characters, or the bytes are not 16.
-
SeparatorThe character at
indexshould be the hyphen between two groups. -
DigitThe character at
indexshould be a hexadecimal digit.
Error.to_string
Section titled “Error.to_string”impl Display for Error
fn to_string(e: Error) -> String
impl Display.to_string
Error.inspect
Section titled “Error.inspect”impl Debug for Error
fn inspect(value: Error) -> String
impl Debug.inspect
Error.equal
Section titled “Error.equal”impl Equatable for Error
fn equal(a: Error, b: Error) -> Bool
impl Equatable.equal