Standard library · Encoding and data

encoding.uuid

UUIDs as RFC 9562 defines them: versions 1 to 8, nil and max, strict parsing, and generation that is safe from many threads.

import encoding.uuid

A UUID is a 128 bit identifier that can be made on any machine without asking a server. This package follows RFC 9562, which replaced RFC 4122, and checks its output against the test vectors of that RFC. A UUID is a small value of two 64 bit halves, so it is cheap to copy, compare and use as a key.

Which version to use:

VersionMade byUse it for
4NewV4, NewPlain random ids. The default choice.
7NewV7Database keys and anything you sort or index: the time comes first, so new ids land at the end of an index.
5NewV5The same name must always give the same id, for example an id for a URL.
3NewV3Like 5 with MD5, only to match ids that already exist.
1 and 6NewV1, NewV6Time based ids that other systems expect. Version 6 is version 1 reordered so it sorts by time; prefer it for new code.
8NewV8Your own layout in the 122 free bits.

The random versions read only the operating system secure random source. The package never uses std/rand, which is not meant for identifiers. If the secure source cannot be read the process stops, because an id built from anything weaker would be a security hole; there is no half working mode to handle.

Making an id

New makes a random version 4 id and String writes it as the usual 36 characters. Nil and Max are the all zero and all one ids. Printing a UUID with println writes the same text.

encoding-uuid-guide-basics.salam
import encoding.uuid

func main:
    id := uuid.New()
    println uuid.String(id).Len(), uuid.Version(id), uuid.Variant(id) == uuid.VARIANT_RFC
    text := uuid.NewString()
    println uuid.IsValid(text), text.Len()
    println uuid.Nil()
    println uuid.Max()
    println uuid.IsNil(uuid.Nil()), uuid.IsNil(id)
end
Output36 4 true true 36 00000000-0000-0000-0000-000000000000 ffffffff-ffff-ffff-ffff-ffffffffffff true false

Reading and writing text

Parse accepts the canonical form, the form in braces, the urn:uuid: form and the form with no hyphens, in capitals or not. It is strict: no spaces around the text, every hyphen where it belongs, nothing but hex digits. It returns a ParseResult with ok, id and error. Use MustParse for literals in your own code and ParseOr when you have a fallback. String, Upper, Compact, Braced and URN write the other direction.

encoding-uuid-guide-parse.salam
import encoding.uuid

func main:
    forms := [
        "f81d4fae-7dec-11d0-a765-00a0c91e6bf6", "F81D4FAE-7DEC-11D0-A765-00A0C91E6BF6",
        "f81d4fae7dec11d0a76500a0c91e6bf6", "{f81d4fae-7dec-11d0-a765-00a0c91e6bf6}",
        "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6", "f81d4fae-7dec-11d0-a765",
        "f81d4fae-7dec-11d0-a765-00a0c91e6bfz"
    ]
    each text in forms:
        r := uuid.Parse(text)
        if r.ok:
            println "ok   ", uuid.String(r.id)
        else:
            println "error", r.error
        end
    end
    id := uuid.MustParse("f81d4fae-7dec-11d0-a765-00a0c91e6bf6")
    println uuid.Upper(id)
    println uuid.Compact(id)
    println uuid.Braced(id)
    println uuid.URN(id)
end
Outputok f81d4fae-7dec-11d0-a765-00a0c91e6bf6 ok f81d4fae-7dec-11d0-a765-00a0c91e6bf6 ok f81d4fae-7dec-11d0-a765-00a0c91e6bf6 ok f81d4fae-7dec-11d0-a765-00a0c91e6bf6 ok f81d4fae-7dec-11d0-a765-00a0c91e6bf6 error uuid: invalid length 23 error uuid: invalid character at position 35 F81D4FAE-7DEC-11D0-A765-00A0C91E6BF6 f81d4fae7dec11d0a76500a0c91e6bf6 {f81d4fae-7dec-11d0-a765-00a0c91e6bf6} urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Ids made from names

Version 5 (and 3) hashes a namespace id and a name, so the same pair always gives the same id. The four namespaces of the RFC are NamespaceDNS, NamespaceURL, NamespaceOID and NamespaceX500; you can also use any UUID of your own as a namespace. The values below are the ones printed in RFC 9562.

encoding-uuid-guide-names.salam
import encoding.uuid

func main:
    dns := uuid.NamespaceDNS()
    println uuid.NewV5(dns, "www.example.com")
    println uuid.NewV3(dns, "www.example.com")
    println uuid.NewV5(dns, "www.example.com") == uuid.NewV5(dns, "www.example.com")
    println uuid.Equal(uuid.NewV5(dns, "python.org"), uuid.NewV5(uuid.NamespaceURL(), "python.org"))
end
Output2ed6657d-e927-568b-95e1-2665a8aea6a2 5df41881-3aed-3515-88a7-2f4a814cf09e true false

Time based ids

Versions 1, 6 and 7 carry a time. UnixMillis and UnixNanos read it back, Timestamp gives the raw 60 bit count of version 1 and 6. The From...Parts functions build an id from exact parts, which is how the tests pin the RFC test vectors. NewV7 returns a larger id on every call, even in the same millisecond, even from other threads, and even when the clock is set back. NewV1 and NewV6 never repeat either: ids in the same 100 nanosecond tick move the time forward by one tick, and a clock that jumps far back changes the clock sequence as RFC 9562 asks. Their node is random per process with the multicast bit set, never a real network address.

encoding-uuid-guide-time.salam
import encoding.uuid

func main:
    v1 := uuid.FromV1Parts(0x1EC9414C232AB00, 0x33C8, 0x9F6BDECED846)
    v6 := uuid.FromV6Parts(0x1EC9414C232AB00, 0x33C8, 0x9F6BDECED846)
    v7 := uuid.FromV7Parts(1645557742000, 0xCC3, 0x18C4DC0C0C07398F)
    println v1
    println v6
    println v7
    println uuid.UnixMillis(v1), uuid.UnixMillis(v6), uuid.UnixMillis(v7)
    println uuid.ClockSequence(v1), uuid.Node(v1) == 0x9F6BDECED846

    first := uuid.NewV7()
    second := uuid.NewV7()
    println uuid.Less(first, second), uuid.String(first) < uuid.String(second)
    println uuid.UnixMillis(second) - uuid.UnixMillis(first) < 1000
end
Outputc232ab00-9414-11ec-b3c8-9f6bdeced846 1ec9414c-232a-6b00-b3c8-9f6bdeced846 017f22e2-79b0-7cc3-98c4-dc0c0c07398f 1645557742000 1645557742000 1645557742000 13256 true true true true

Many threads at once

All the generators can be called from any number of threads, with go, spawn or a pool. The clock state, the version 7 counter and the buffer of random bytes sit behind locks of their own, so there are no duplicates and no id goes backwards in a thread. The example makes 8000 ids from 8 tasks and counts the different ones.

encoding-uuid-guide-threads.salam
import encoding.uuid
import mem
import pool

const WORKERS := 8
const PER := 1000

mut slots := null as u64*

func produce(worker: int):
    repeat PER in i:
        id := uuid.NewV7()
        slot := (worker * PER + i) * 2
        slots[slot] = id.hi
        slots[slot + 1] = id.lo
    end
end

func main:
    slots = mem.Allocate((WORKERS * PER * 16) as u64) as u64*
    repeat WORKERS in worker:
        go produce(worker)
    end
    pool.GoWait()
    mut seen := HashMap {} as HashMap<str, int>
    defer seen.free()
    repeat WORKERS * PER in i:
        seen.put(uuid.Compact(uuid.UUID { hi = slots[i * 2], lo = slots[i * 2 + 1] }), 1)
    end
    println "generated", WORKERS * PER, "unique", seen.size()
    mem.Free(slots as void*)
end
Outputgenerated 8000 unique 8000

Short forms

Base64URL writes an id in 22 characters that are safe in a URL and Base32 in 26 lowercase characters that are safe in a file name or a host name. Reading them back is as strict as Parse: the unused bits must be zero, so one id has one text.

encoding-uuid-guide-short.salam
import encoding.uuid

func main:
    id := uuid.MustParse("f81d4fae-7dec-11d0-a765-00a0c91e6bf6")
    short := uuid.Base64URL(id)
    println short, short.Len()
    println uuid.Base32(id)
    back := uuid.FromBase64URL(short)
    println back.ok, uuid.Equal(back.id, id)
    println uuid.FromBase64URL("too short").error
end
Output-B1Prn3sEdCnZQCgyR5r9g 22 7aou7lt55qi5bj3facqmshtl6y true true uuid: base64url text must have 22 characters

Custom ids and bytes

Version 8 keeps the version and variant bits and leaves the rest to you: FromV8Parts takes the three fields of the RFC and NewV8 takes two 64 bit halves. Bytes and FromBytes convert to the 16 bytes in network order, and ToBuffer and FromBuffer do the same for raw memory.

encoding-uuid-guide-custom.salam
import encoding.uuid

func main:
    custom := uuid.FromV8Parts(0x2489E9AD2EE2, 0xE00, 0xEC932D5F69181C0)
    println custom, uuid.Version(custom), uuid.Variant(custom) == uuid.VARIANT_RFC
    other := uuid.NewV8(0x0123456789ABCDEF as u64, 0xFEDCBA9876543210 as u64)
    println other
    mut bytes := uuid.Bytes(other)
    println bytes.Len(), bytes.get(0), bytes.get(15)
    println uuid.Equal(uuid.FromBytes(bytes), other)
    bytes.free()
    batch := uuid.Batch(3)
    println batch.Len()
    batch.free()
end
Output2489e9ad-2ee2-8e00-8ec9-32d5f69181c0 8 true 01234567-89ab-8def-bedc-ba9876543210 16 1 16 true 3

What people get wrong:

  • Using version 4 as a primary key in a big table. Random keys scatter writes over the whole index; version 7 keeps them together.
  • Hiding secrets in the time of a version 1, 6 or 7 id. The time can be read back by anyone who has the id.
  • Expecting version 5 to be secret. It is a hash of public values, anyone who knows the name can compute it.
  • Comparing the text of ids made in different cases. Compare with Equal, or write both with String.
  • Forgetting to free the vectors from Bytes, Batch and BatchV7.

For random bytes and tokens see crypto; for hex and base64 of arbitrary data see encoding.

Types

ParseResult

struct ParseResult
What Parse returns: ok says whether the text was a UUID, id is the value and error says what was wrong.
NameTypeDescription
okbool = falseTrue when the text was a valid UUID.
idUUIDThe parsed value, the nil UUID when ok is false.
errorstr = ""A short description of the problem, empty when ok is true.
encoding-uuid-Parse.salam
import encoding.uuid

func main:
    r := uuid.Parse("{F81D4FAE-7DEC-11D0-A765-00A0C91E6BF6}")
    println r.ok, uuid.String(r.id)
    bad := uuid.Parse("not a uuid")
    println bad.ok, bad.error
    println uuid.ParseOr("nope", uuid.Nil())
end
Outputtrue f81d4fae-7dec-11d0-a765-00a0c91e6bf6 false uuid: invalid length 10 00000000-0000-0000-0000-000000000000

UUID

struct UUID
A 128 bit identifier kept as two unsigned 64 bit halves, hi (the first eight bytes) and lo (the last eight). It is a plain value: copy it, compare it with Equal and Compare, print it with println.
NameTypeDescription
hiu64 = 0The first eight bytes, most significant first.
lou64 = 0The last eight bytes, most significant first.
encoding-uuid-Bytes.salam
import encoding.uuid

func main:
    id := uuid.MustParse("f81d4fae-7dec-11d0-a765-00a0c91e6bf6")
    mut bytes := uuid.Bytes(id)
    defer bytes.free()
    println bytes.Len(), bytes.get(0), bytes.get(15)
    println uuid.Equal(uuid.FromBytes(bytes), id)
end
Output16 248 246 true

to_str

func to_str(): str
The canonical text of the value, the same as String: 36 lowercase characters.
encoding-uuid-Buffer.salam
import encoding.uuid
import mem

func main:
    id := uuid.MustParse("f81d4fae-7dec-11d0-a765-00a0c91e6bf6")
    buf := mem.Allocate(16 as u64)
    defer mem.Free(buf)
    uuid.ToBuffer(id, buf)
    p := buf as u8*
    println p[0], p[15]
    back := uuid.FromBuffer(buf)
    println back.to_str()
    println back.hi == id.hi, back.lo == id.lo
    println uuid.Equal(back, id)
end
Output248 246 f81d4fae-7dec-11d0-a765-00a0c91e6bf6 true true true

Constants and variables

VARIANT_NCS

const VARIANT_NCS: i32 = 0
Variant of old NCS identifiers, the top bit of the variant field is 0.
encoding-uuid-NewV4.salam
import encoding.uuid

func main:
    a := uuid.NewV4()
    b := uuid.NewV4()
    println uuid.Version(a), uuid.Variant(a) == uuid.VARIANT_RFC
    println uuid.Equal(a, b), uuid.Compare(a, a)
end
Output4 true false 0

VARIANT_RFC

const VARIANT_RFC: i32 = 1
The variant of RFC 9562 and RFC 4122, bits 10. Every version 1 to 8 UUID made here has it.

The example for this item is shown with the ones above: encoding-uuid-NewV4.salam

VARIANT_MICROSOFT

const VARIANT_MICROSOFT: i32 = 2
Variant reserved for old Microsoft GUIDs, bits 110.

The example for this item is shown with the ones above: encoding-uuid-NewV4.salam

VARIANT_FUTURE

const VARIANT_FUTURE: i32 = 3
Variant reserved for the future, bits 111.

The example for this item is shown with the ones above: encoding-uuid-NewV4.salam

Functions

Parse

func Parse(s: str): ParseResult
Reads a UUID from text. It accepts the canonical form, the form in braces, the urn:uuid: form and the form with no hyphens, in any case. Everything else is an error: spaces, a missing or misplaced hyphen, a character that is not a hex digit, a wrong length.

The example for this item is shown with the ones above: encoding-uuid-Parse.salam

ParseOr

func ParseOr(s: str, fallback: UUID): UUID
Parses text and returns the fallback when it is not a UUID.

The example for this item is shown with the ones above: encoding-uuid-Parse.salam

IsValid

func IsValid(s: str): bool
True when Parse would accept the text.

The example for this item is shown with the ones above: encoding-uuid-Parse.salam

MustParse

func MustParse(s: str): UUID
Parses text and stops the program with a message on standard error and exit code 2 when it is not a UUID. For literals in your own code.
encoding-uuid-Formats.salam
import encoding.uuid

func main:
    id := uuid.MustParse("f81d4fae-7dec-11d0-a765-00a0c91e6bf6")
    println uuid.String(id)
    println uuid.Upper(id)
    println uuid.Compact(id)
    println uuid.Braced(id)
    println uuid.URN(id)
end
Outputf81d4fae-7dec-11d0-a765-00a0c91e6bf6 F81D4FAE-7DEC-11D0-A765-00A0C91E6BF6 f81d4fae7dec11d0a76500a0c91e6bf6 {f81d4fae-7dec-11d0-a765-00a0c91e6bf6} urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6

FromV4Parts

func FromV4Parts(hi: u64, lo: u64): UUID
Builds a version 4 UUID from two given random halves, for tests that need a fixed value.

The example for this item is shown with the ones above: encoding-uuid-NewV4.salam

FromV7Parts

func FromV7Parts(unix_ms: i64, rand_a: i64, rand_b: i64): UUID
Builds a version 7 UUID from a Unix time in milliseconds, 12 bits rand_a and 62 bits rand_b. This is the deterministic builder behind NewV7.
encoding-uuid-FromV7Parts.salam
import encoding.uuid

func main:
    id := uuid.FromV7Parts(1645557742000, 0xCC3, 0x18C4DC0C0C07398F)
    println id
    println uuid.UnixMillis(id)
end
Output017f22e2-79b0-7cc3-98c4-dc0c0c07398f 1645557742000

FromV8Parts

func FromV8Parts(custom_a: i64, custom_b: i64, custom_c: i64): UUID
Builds a version 8 UUID from 48 bits custom_a, 12 bits custom_b and 62 bits custom_c, the layout of RFC 9562.
encoding-uuid-Custom.salam
import encoding.uuid

func main:
    custom := uuid.FromV8Parts(0x2489E9AD2EE2, 0xE00, 0xEC932D5F69181C0)
    println custom, uuid.Version(custom), uuid.Variant(custom) == uuid.VARIANT_RFC
    other := uuid.NewV8(0x0123456789ABCDEF as u64, 0xFEDCBA9876543210 as u64)
    println other
    println uuid.Stamp(0 as u64, 0 as u64, 9)
end
Output2489e9ad-2ee2-8e00-8ec9-32d5f69181c0 8 true 01234567-89ab-8def-bedc-ba9876543210 00000000-0000-9000-8000-000000000000

NewV4

func NewV4(): UUID
A random UUID, version 4. It has 122 random bits from the operating system secure random source and nothing else. The source is read in large blocks under a lock, so it is safe from many threads.

The example for this item is shown with the ones above: encoding-uuid-NewV4.salam

NewV7

func NewV7(): UUID
A UUID made of the Unix time in milliseconds followed by a counter and random bits, version 7. Every call returns a larger UUID than the one before, in the whole process and across threads, even when the clock stands still or goes back.
encoding-uuid-NewV7.salam
import encoding.uuid

func main:
    ids := uuid.BatchV7(5)
    defer ids.free()
    mut ordered := true
    repeat ids.Len() - 1 in i:
        if not uuid.Less(ids.get(i), ids.get(i + 1)): ordered = false end
    end
    println "version", uuid.Version(ids.get(0)), "ordered", ordered
    println uuid.HasTime(ids.get(0))
end
Outputversion 7 ordered true true

NewV8

func NewV8(hi: u64, lo: u64): UUID
A custom UUID: your 128 bits with the version 8 and RFC variant bits written over them.

The example for this item is shown with the ones above: encoding-uuid-Custom.salam

Nil

func Nil(): UUID
The nil UUID, all 128 bits zero.
encoding-uuid-New.salam
import encoding.uuid

func main:
    id := uuid.New()
    println uuid.String(id).Len(), uuid.Version(id), uuid.Variant(id) == uuid.VARIANT_RFC
    println uuid.IsValid(uuid.NewString())
    println uuid.Nil(), uuid.IsNil(uuid.Nil()), uuid.IsNil(id)
    println uuid.Max(), uuid.IsMax(uuid.Max())
    ids := uuid.Batch(3)
    println ids.Len()
    ids.free()
end
Output36 4 true true 00000000-0000-0000-0000-000000000000 true false ffffffff-ffff-ffff-ffff-ffffffffffff true 3

Max

func Max(): UUID
The max UUID, all 128 bits one.

The example for this item is shown with the ones above: encoding-uuid-New.salam

IsNil

func IsNil(u: UUID): bool
True when every bit is zero.

The example for this item is shown with the ones above: encoding-uuid-New.salam

IsMax

func IsMax(u: UUID): bool
True when every bit is one.

The example for this item is shown with the ones above: encoding-uuid-New.salam

Equal

func Equal(a: UUID, b: UUID): bool
True when two UUIDs have the same 128 bits.

The example for this item is shown with the ones above: encoding-uuid-NewV4.salam

Compare

func Compare(a: UUID, b: UUID): int
Returns -1, 0 or 1. The order is the order of the bytes, so it is also the order of the canonical text, and version 6 and 7 UUIDs sort by time.

The example for this item is shown with the ones above: encoding-uuid-NewV4.salam

Less

func Less(a: UUID, b: UUID): bool
True when a sorts before b.

The example for this item is shown with the ones above: encoding-uuid-NewV7.salam

Version

func Version(u: UUID): int
The version number from the four version bits, 0 to 15.

The example for this item is shown with the ones above: encoding-uuid-NewV4.salam

Variant

func Variant(u: UUID): int
The layout of the identifier: one of the VARIANT_ constants.

The example for this item is shown with the ones above: encoding-uuid-NewV4.salam

Byte

func Byte(u: UUID, i: int): int
The byte at position 0 to 15, or 0 when the position is out of range.

The example for this item is shown with the ones above: encoding-uuid-Bytes.salam

Bytes

func Bytes(u: UUID): Vector<u8>
The 16 bytes in network order as a vector. Free it when done.

The example for this item is shown with the ones above: encoding-uuid-Bytes.salam

FromBytes

func FromBytes(b: Vector<u8>): UUID
Builds a UUID from a vector of exactly 16 bytes. Any other length gives the nil UUID.

The example for this item is shown with the ones above: encoding-uuid-Bytes.salam

ToBuffer

func ToBuffer(u: UUID, out: void*)
Writes the 16 bytes to the memory out points at. The buffer must hold at least 16 bytes.

The example for this item is shown with the ones above: encoding-uuid-Buffer.salam

FromBuffer

func FromBuffer(src: void*): UUID
Reads 16 bytes from the memory src points at.

The example for this item is shown with the ones above: encoding-uuid-Buffer.salam

NamespaceDNS

func NamespaceDNS(): UUID
The namespace UUID for fully qualified domain names, 6ba7b810-9dad-11d1-80b4-00c04fd430c8.
encoding-uuid-NewV5.salam
import encoding.uuid

func main:
    id := uuid.NewV5(uuid.NamespaceDNS(), "www.example.com")
    println id
    println uuid.Version(id)
    println uuid.NewV3(uuid.NamespaceDNS(), "www.example.com")
end
Output2ed6657d-e927-568b-95e1-2665a8aea6a2 5 5df41881-3aed-3515-88a7-2f4a814cf09e

NamespaceURL

func NamespaceURL(): UUID
The namespace UUID for URLs, 6ba7b811-9dad-11d1-80b4-00c04fd430c8.

The example for this item is shown with the ones above: encoding-uuid-NewV5.salam

NamespaceOID

func NamespaceOID(): UUID
The namespace UUID for ISO object identifiers, 6ba7b812-9dad-11d1-80b4-00c04fd430c8.

The example for this item is shown with the ones above: encoding-uuid-NewV5.salam

NamespaceX500

func NamespaceX500(): UUID
The namespace UUID for X.500 distinguished names, 6ba7b814-9dad-11d1-80b4-00c04fd430c8.

The example for this item is shown with the ones above: encoding-uuid-NewV5.salam

FromV1Parts

func FromV1Parts(ts: i64, clock_seq: int, node: i64): UUID
Builds a version 1 UUID from a 60 bit timestamp (100 nanosecond steps since 1582-10-15), a 14 bit clock sequence and a 48 bit node. The deterministic builder behind NewV1.
encoding-uuid-Time.salam
import encoding.uuid

func main:
    v1 := uuid.FromV1Parts(0x1EC9414C232AB00, 0x33C8, 0x9F6BDECED846)
    v6 := uuid.FromV6Parts(0x1EC9414C232AB00, 0x33C8, 0x9F6BDECED846)
    println v1
    println v6
    println uuid.UnixMillis(v1), uuid.ClockSequence(v6), uuid.Node(v1) == 0x9F6BDECED846
    println uuid.Timestamp(v1) == uuid.Timestamp(v6)
    a := uuid.NewV1()
    b := uuid.NewV1()
    println uuid.Timestamp(a) < uuid.Timestamp(b), uuid.Node(a) == uuid.NodeID()
    own := uuid.NewV1WithNode(0x0123456789AB)
    println uuid.Node(own) == 0x0123456789AB, uuid.Version(uuid.NewV6())
end
Outputc232ab00-9414-11ec-b3c8-9f6bdeced846 1ec9414c-232a-6b00-b3c8-9f6bdeced846 1645557742000 13256 true true true true true 6

FromV6Parts

func FromV6Parts(ts: i64, clock_seq: int, node: i64): UUID
Builds a version 6 UUID from the same parts as FromV1Parts. Version 6 is version 1 with the time bits reordered so the text sorts by time.

The example for this item is shown with the ones above: encoding-uuid-Time.salam

NewV1

func NewV1(): UUID
A time based UUID, version 1: the current time, a clock sequence and the process node. It never repeats: when two calls land in the same tick the time is moved forward by one tick, and when the clock jumps far back the clock sequence is changed.

The example for this item is shown with the ones above: encoding-uuid-Time.salam

NewV1WithNode

func NewV1WithNode(node: i64): UUID
Like NewV1 with the 48 bit node you give instead of the random one.

The example for this item is shown with the ones above: encoding-uuid-Time.salam

NewV6

func NewV6(): UUID
A time ordered UUID, version 6. It carries the same information as version 1 but sorts by time.

The example for this item is shown with the ones above: encoding-uuid-Time.salam

HasTime

func HasTime(u: UUID): bool
True for a version 1, 6 or 7 UUID of the RFC variant.

The example for this item is shown with the ones above: encoding-uuid-NewV7.salam

Timestamp

func Timestamp(u: UUID): i64
The raw 60 bit timestamp of a version 1 or 6 UUID, or 0 for other versions.

The example for this item is shown with the ones above: encoding-uuid-Time.salam

UnixNanos

func UnixNanos(u: UUID): i64
The time inside a version 1, 6 or 7 UUID as nanoseconds since 1970, or 0 for other versions.

The example for this item is shown with the ones above: encoding-uuid-FromV7Parts.salam

UnixMillis

func UnixMillis(u: UUID): i64
The same time in milliseconds.

The example for this item is shown with the ones above: encoding-uuid-FromV7Parts.salam

ClockSequence

func ClockSequence(u: UUID): int
The 14 bit clock sequence of a version 1 or 6 UUID, or 0.

The example for this item is shown with the ones above: encoding-uuid-Time.salam

Node

func Node(u: UUID): i64
The 48 bit node of a version 1 or 6 UUID, or 0.

The example for this item is shown with the ones above: encoding-uuid-Time.salam

Base64URL

func Base64URL(u: UUID): str
The UUID as 22 characters of URL safe base64 without padding.
encoding-uuid-Base64URL.salam
import encoding.uuid

func main:
    id := uuid.MustParse("f81d4fae-7dec-11d0-a765-00a0c91e6bf6")
    println uuid.Base64URL(id)
    println uuid.Base32(id)
    println uuid.FromBase32(uuid.Base32(id)).ok
end
Output-B1Prn3sEdCnZQCgyR5r9g 7aou7lt55qi5bj3facqmshtl6y true

FromBase64URL

func FromBase64URL(s: str): ParseResult
Reads the 22 character form back. The extra bits must be zero, so every UUID has exactly one text.

The example for this item is shown with the ones above: encoding-uuid-Base64URL.salam

Base32

func Base32(u: UUID): str
The UUID as 26 lowercase characters of RFC 4648 base32 without padding.

The example for this item is shown with the ones above: encoding-uuid-Base64URL.salam

FromBase32

func FromBase32(s: str): ParseResult
Reads the 26 character form back, in either case.

The example for this item is shown with the ones above: encoding-uuid-Base64URL.salam

Stamp

func Stamp(hi: u64, lo: u64, version: int): UUID
Writes a version and the RFC variant over any 128 bits (hi and lo) and returns the result.

The example for this item is shown with the ones above: encoding-uuid-Custom.salam

NewV3

func NewV3(ns: UUID, name: str): UUID
A name based UUID using MD5, version 3. The same namespace and name always give the same UUID. Prefer NewV5 unless you must match existing version 3 ids.

The example for this item is shown with the ones above: encoding-uuid-NewV5.salam

NewV5

func NewV5(ns: UUID, name: str): UUID
A name based UUID using SHA-1, version 5. The same namespace and name always give the same UUID, on every machine and in every language that follows RFC 9562.

The example for this item is shown with the ones above: encoding-uuid-NewV5.salam

String

func String(u: UUID): str
The canonical lowercase text, 36 characters: 8-4-4-4-12 hexadecimal digits.

The example for this item is shown with the ones above: encoding-uuid-Parse.salam

Upper

func Upper(u: UUID): str
The canonical text in capitals.

The example for this item is shown with the ones above: encoding-uuid-Formats.salam

Compact

func Compact(u: UUID): str
Lowercase without hyphens, 32 characters.

The example for this item is shown with the ones above: encoding-uuid-Formats.salam

Braced

func Braced(u: UUID): str
The canonical text in curly braces, the form Microsoft tools write.

The example for this item is shown with the ones above: encoding-uuid-Formats.salam

URN

func URN(u: UUID): str
The canonical text with the urn:uuid: prefix.

The example for this item is shown with the ones above: encoding-uuid-Formats.salam

NodeID

func NodeID(): i64
The 48 bit node this process puts in version 1 and 6 UUIDs: random, with the multicast bit set as RFC 9562 asks, so it never equals a real network card address.

The example for this item is shown with the ones above: encoding-uuid-Time.salam

New

func New(): UUID
Makes a random version 4 UUID from the secure random source. The same as NewV4.

The example for this item is shown with the ones above: encoding-uuid-New.salam

NewString

func NewString(): str
Makes a random version 4 UUID and returns it as lowercase text.

The example for this item is shown with the ones above: encoding-uuid-New.salam

Batch

func Batch(n: int): Vector<UUID>
Makes n random version 4 UUIDs. Free the vector when done.

The example for this item is shown with the ones above: encoding-uuid-Custom.salam

BatchV7

func BatchV7(n: int): Vector<UUID>
Makes n version 7 UUIDs in order. Each one is larger than the one before. Free the vector when done.

The example for this item is shown with the ones above: encoding-uuid-NewV7.salam