Uuidm
Universally unique identifiers (UUIDs).
Uuidm
implements 128 bits universally unique identifiers version 3, 5 (name based with MD5, SHA-1 hashing), 4 (random based), 7 (random and timestamp based) and 8 (custom) according to RFC 9562.
See the quick start.
The type for 4 bits stored in the 4 lower bits of an int
value. The higher bits are either set to zero or ignored on use.
The type for 12 bits stored in the 12 lower bits of an int
value. The higher bits are either set to zero or ignored on use.
The type for 62 bits stored in the 62 lower bits of an int64
value. The higher bits are either set to zero or ignored on use.
v3 ns n
is a V3 UUID (name based with MD5 hashing) named by n
and namespaced by ns
.
val v4 : bytes -> t
v5 ns n
is a V5 UUID (name based with SHA-1 hashing) named by n
and namespaced by ns
. See this example.
v7 ~time_ms ~rand_a ~rand_b
is a V7 UUID (time and random based) using the 64-bit millisecond POSIX timestamp time_ms
and random bits rand_a
and rand_b
. See also v7_ns
, v7_non_monotonic_gen
and v7_monotonic_gen
.
Warning. The timestamp and the randomness are seen literally in the result.
v7_ns ~time_ns ~rand_b
is a V7 UUID (time and random based) using the unsigned 64-bit nanosecond POSIX timestamp time_ns
and random bits rand_b
. The rand_a
field is used with the timestamp's submillisecond precision with about 244 nanoseconds resolution. See also v7
.
Warning. The timestamp and the randomness are seen literally in the result.
val v8 : string -> t
Warning. If you use the generators take into account the following points:
Random
. This is suitably random but predictable by an observer. Use the base constuctors with random bytes generated by a cryptographically secure pseudorandom number generator (CSPRNG) if that is an issue.Random.State.t
value are not guaranteed to be stable across OCaml or Uuidm versions. Use the base constructors with your own pseudorandom number generator if that is an issue.posix_ms_clock
assume the clock is monotonic in order to generate monotonic UUIDs. If you derive it from Unix.gettimeofday
this may not be the case.val v4_gen : Stdlib.Random.State.t -> unit -> t
v4_gen state
is a function generating v4
UUIDs using random state
. See this example.
val v7_non_monotonic_gen :
now_ms:posix_ms_clock ->
Stdlib.Random.State.t ->
unit ->
t
v7_non_monotonic_gen ~now_ms state
is a function generating v7
UUIDs using now_ms
for the timestamp time_ms
and random state
for rand_a
and rand_b
. UUIDs generated in the same millisecond may not be be monotonic. Use v7_monotonic_gen
for that.
val v7_monotonic_gen :
now_ms:posix_ms_clock ->
Stdlib.Random.State.t ->
unit ->
t option
v7_monotonic_gen ~posix_now_ms state
is a function that generates monotonic v7
UUIDs using now_ms
for the timestamp time_ms
, rand_a
as a counter if the clock did not move between two UUID generations and random
state for rand_b
. This allows to generate up to 4096 monotonic UUIDs per millisecond. None
is returned if the counter rolls over before the millisecond increments. See this example.
val ns_dns : t
ns_dns
is the DNS namespace UUID.
val ns_url : t
ns_url
is the URL namespace UUID.
val ns_oid : t
ns_oid
is the ISO OID namespace UUID.
val ns_X500 : t
ns_dn
is the X.500 DN namespace UUID.
variant u
is the variant field of u
, including the "don't-care" values.
version u
is the version field of u
.
val time_ms : t -> int64 option
time_ms u
is the unit_ts_ms
millisecond POSIX timestamp of u
as a 64-bit integer. This is None
if u
is not a V7 UUID.
This is the binary format mandated by RFC 9562.
val of_binary_string : ?pos:int -> string -> t option
of_binary_string pos s
is the UUID represented by the 16 bytes starting at pos
(defaults to 0
) in s
. No particular checks are performed on the bytes. The result is None
if the string is not long enough.
val to_binary_string : t -> string
to_binary_string u
is u
as a 16 bytes long string.
This is the binary format in which the three first fields of UUIDs (which are oblivious to this module) are read and written in little-endian. This corresponds to how UEFI or Microsoft formats UUIDs.
val of_mixed_endian_binary_string : ?pos:int -> string -> t option
of_mixed_endian_binary_string
is like of_bytes
but decodes the mixed endian serialization.
val to_mixed_endian_binary_string : t -> string
to_mixed_endian_binary_string
is like to_bytes
but encodes the mixed endian serialization.
val of_string : ?pos:int -> string -> t option
of_string pos s
converts the substring of s
starting at pos
(defaults to 0
) of the form "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
where X is a lower or upper case hexadecimal number to an UUID. The result is None
if a parse error occurs. Any extra characters after are ignored.
val to_string : ?upper:bool -> t -> string
to_string u
is u
as a string of the form "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
where X is a lower (or upper if upper
is true
) case hexadecimal number.
val pp' : upper:bool -> Stdlib.Format.formatter -> t -> unit
pp' ~upper ppf u
formats u
with to_string
~upper
on ppf
.
val pp_string : ?upper:bool -> Stdlib.Format.formatter -> t -> unit
val of_bytes : ?pos:int -> string -> t option
val to_bytes : t -> string
val of_mixed_endian_bytes : ?pos:int -> string -> t option
val to_mixed_endian_bytes : t -> string