gleam_uuid

Spec conformant UUID v1, v3, v4, and v5 generation.

Spec conformant UUID decoding for all versions and variants.

Spec: https://www.ietf.org/rfc/rfc4122.txt

Wikipedia: https://en.wikipedia.org/wiki/uuid

Unless you have a specific reason otherwise, you probably either want the random v4 or the time-based v1 version.

Quick Usage:

import gleam_uuid

// Generation
> gleam_uuid.v4_string()
"f7e321c7-4a4b-4287-a8b8-1ae35b5538ce"

// Decoding
> "f7e321c7-4a4b-4287-a8b8-1ae35b5538ce"
    |> gleam_uuid.from_string()
    |> result.map(gleam_uuid.version)
Ok(gleam_uuid.V4)

Types

Format

Supported string formats

pub type Format {
  String
  Hex
  Urn
}

Constructors

String
Standad hex string with dashes
Hex
Hex string with no dashes
Urn
Standard hex string with dashes prepended with "urn:uuid:"

UUID

Opaque type for holding onto a UUID. Opaque so you know that if you have a UUID it is valid.

pub opaque type UUID

V1ClockSeq

How to generate the clock sequence for a V1 UUID

pub type V1ClockSeq {
  RandomClockSeq
  CustomClockSeq(BitString)
}

Constructors

RandomClockSeq
Will be generated randomly.
CustomClockSeq(BitString)
Will be the provided bit string, must be exactly 14 bits.

V1Node

How to generate the node for a V1 UUID.

pub type V1Node {
  DefaultNode
  RandomNode
  CustomNode(String)
}

Constructors

DefaultNode
Will first attempt to use the network cards MAC address, then fall back to random
RandomNode
Will be random
CustomNode(String)
Will be the provided sting, must be 12 characters long and valid hex

Variant

Possible UUID variants. This library only produces Rfc4122 variant UUIDs but can decode all variants

pub type Variant {
  ReservedFuture
  ReservedMicrosoft
  ReservedNcs
  Rfc4122
}

Constructors

ReservedFuture
ReservedMicrosoft
ReservedNcs
Rfc4122

Functions

clock_sequence

pub fn clock_sequence(uuid: UUID) -> Int

Determine the clock sequence of a UUID This is only relevant to a V1 UUID

dns_uuid

pub fn dns_uuid() -> UUID

dns namespace UUID provided by the spec, only useful for v3 and v5

format

pub fn format(uuid: UUID, format: Format) -> String

Convert a UUID to one of the supported string formats

from_string

pub fn from_string(in: String) -> Result(UUID, Nil)

Attempt to decode a UUID from a string. Supports strings formatted in the same ways this library will output them. Hex with dashes, hex without dashes and hex with or without dashes prepended with "urn:uuid:"

node

pub fn node(uuid: UUID) -> String

Determine the node of a UUID This is only relevant to a V1 UUID

oid_uuid

pub fn oid_uuid() -> UUID

oid namespace UUID provided by the spec, only useful for v3 and v5

time

pub fn time(uuid: UUID) -> Int

Determine the time a UUID was created with Gregorian Epoch This is only relevant to a V1 UUID UUID's use 15 Oct 1582 as Epoch and time is measured in 100ns intervals. This value is useful for comparing V1 UUIDs but not so much for telling what time a UUID was created. See time_posix_microsec and clock_sequence

time_posix_microsec

pub fn time_posix_microsec(uuid: UUID) -> Int

Determine the time a UUID was created with Unix Epoch This is only relevant to a V1 UUID Value is the number of micro seconds since Unix Epoch

to_string

pub fn to_string(uuid: UUID) -> String

Convert a UUID to a standard string

url_uuid

pub fn url_uuid() -> UUID

url namespace UUID provided by the spec, only useful for v3 and v5

v1

pub fn v1() -> UUID

Create a V1 (time-based) UUID with default node and random clock sequence.

v1_custom

pub fn v1_custom(
  node: V1Node,
  clock_seq: V1ClockSeq,
) -> Result(UUID, Nil)

Create a V1 (time-based) UUID with custom node and clock sequence.

v1_string

pub fn v1_string() -> String

Convenience for quickly creating a time-based UUID String with default settings.

v3

pub fn v3(namespace: UUID, name: BitString) -> Result(UUID, Nil)

Generates a version 3 (name-based, md5 hashed) UUID. Name must be a valid sequence of bytes

v4

pub fn v4() -> UUID

Generates a version 4 (random) UUID.

v4_string

pub fn v4_string() -> String

Convenience for quickly creating a random UUID String

v5

pub fn v5(namespace: UUID, name: BitString) -> Result(UUID, Nil)

Generates a version 5 (name-based, sha1 hashed) UUID. name must be a valid sequence of bytes

variant

pub fn variant(uuid: UUID) -> Variant

Determine the Variant of a UUID

version

pub fn version(uuid: UUID) -> Version

Determine the Version of a UUID

x500_uuid

pub fn x500_uuid() -> UUID

x500 namespace UUID provided by the spec, only useful for v3 and v5