UUID

Generates an empty UUID.

UUID.empty # => UUID(00000000-0000-4000-0000-000000000000)

Generates UUID from bytes, applying version and variant to the UUID if present.

Creates UUID from 16-bytes slice. Raises if slice isn't 16 bytes long. See #initialize for variant and version.

Creates another UUID which is a copy of uuid, but allows overriding variant or version.

Creates new UUID by decoding value string from hyphenated (ie ba714f86-cac6-42c7-8956-bcf5105e1b81), hexstring (ie 89370a4ab66440c8add39e06f2bb6af6) or URN (ie urn:uuid:3f9eaf9e-cdb0-45cc-8ecb-0e5b2bfb0c20) format, raising an ArgumentError if the string does not match any of these formats.

Creates UUID from YAML using YAML::ParseContext.

NOTE: require "uuid/yaml" is required to opt-in to this feature.

require "yaml"
require "uuid"
require "uuid/yaml"

class Example
  include YAML::Serializable

  property id : UUID
end

example = Example.from_yaml("id: 50a11da6-377b-4bdf-b9f0-076f9db61c93")
example.id # => UUID(50a11da6-377b-4bdf-b9f0-076f9db61c93)

Creates UUID from JSON using JSON::PullParser.

NOTE: require "uuid/json" is required to opt-in to this feature.

require "json"
require "uuid"
require "uuid/json"

class Example
  include JSON::Serializable

  property id : UUID
end

example = Example.from_json(%({"id": "ba714f86-cac6-42c7-8956-bcf5105e1b81"}))
example.id # => UUID(ba714f86-cac6-42c7-8956-bcf5105e1b81)

Generates RFC 4122 v4 UUID.

It is strongly recommended to use a cryptographically random source for random, such as Random::Secure.

Generates RFC 4122 v1 UUID.

The traditional method for generating a node_id involves using the machine’s MAC address. However, this approach is only effective if there is only one process running on the machine and if privacy is not a concern. In modern languages, the default is to prioritize security and privacy. Therefore, a pseudo-random node_id is generated as described in section 4.5 of the RFC.

The sequence number clock_seq is used to generate the UUID. This number should be monotonically increasing, with only 14 bits of the clock sequence being used effectively. The clock sequence should be stored in a stable location, such as a file. If it is not stored, a random value is used by default. If not provided the current time milliseconds are used. In case the traditional MAC address based approach should be taken the node_id can be provided. Otherwise secure random is used.

Generates RFC 4122 v2 UUID.

Version 2 UUIDs are generated using the current time, the local machine’s MAC address, and the local user or group ID. However, they are not widely used due to their limitations. For a given domain/id pair, the same token may be returned for a duration of up to 7 minutes and 10 seconds.

The id depends on the domain, for the Domain::Person usually the local user id (uid) is used, for Domain::Group usually the local group id (gid) is used. In case the traditional MAC address based approach should be taken the node_id can be provided. Otherwise secure random is used.

Generates RFC 4122 v3 UUID using the name to generate the UUID, it can be a string of any size. The namespace specifies the type of the name, usually one of Namespace.

Generates RFC 4122 v4 UUID.

It is strongly recommended to use a cryptographically random source for random, such as Random::Secure.

Generates RFC 4122 v5 UUID using the name to generate the UUID, it can be a string of any size. The namespace specifies the type of the name, usually one of Namespace.

Generates an RFC 9562 v6 UUID.

UUIDv6 is a field-compatible version of UUIDv1 with the timestamp bits reordered to be most-significant-first, making the UUID lexicographically sortable by creation time.

The sequence number clock_seq should be monotonically increasing across invocations; only 14 bits are used. If not provided, the current millisecond sub-second value is used. If node_id is not provided, a pseudo-random node ID is generated with the multicast bit set as recommended by RFC 4122 section 4.5.

Generates an RFC 9562 v8 UUID from custom_bytes.

UUIDv8 is an RFC-compatible format for experimental or vendor-specific use cases where the caller defines the meaning of all 128 bits. Exactly 6 bits of custom_bytes are unconditionally overwritten:

• Bits 48–51 (high nibble of byte 6) get set to 0x8 (version 8)
• Bits 64–65 (two high bits of byte 8) get set to 0b10 (RFC 9562 variant)

All remaining 122 bits are preserved exactly as supplied. Callers must account for this when designing their custom layout; avoid placing meaningful data in those 6 bit positions.

Example: embedding a 16-bit shard ID and a 32-bit sequence number.

require "uuid"

buf = StaticArray(UInt8, 16).new(0_u8)
IO::ByteFormat::BigEndian.encode(shard_id, buf.to_slice[0, 2])
IO::ByteFormat::BigEndian.encode(seq, buf.to_slice[2, 4])
# bytes 6 and 8 will have 6 bits overwritten; leave them as padding
uuid = UUID.v8(buf)

Generates an RFC 9562 v8 UUID from custom_bytes.

UUIDv8 is an RFC-compatible format for experimental or vendor-specific use cases where the caller defines the meaning of all 128 bits. Exactly 6 bits of custom_bytes are unconditionally overwritten:

• Bits 48–51 (high nibble of byte 6) get set to 0x8 (version 8)
• Bits 64–65 (two high bits of byte 8) get set to 0b10 (RFC 9562 variant)

All remaining 122 bits are preserved exactly as supplied. Callers must account for this when designing their custom layout; avoid placing meaningful data in those 6 bit positions.

Example: embedding a 16-bit shard ID and a 32-bit sequence number.

require "uuid"

buf = StaticArray(UInt8, 16).new(0_u8)
IO::ByteFormat::BigEndian.encode(shard_id, buf.to_slice[0, 2])
IO::ByteFormat::BigEndian.encode(seq, buf.to_slice[2, 4])
# bytes 6 and 8 will have 6 bits overwritten; leave them as padding
uuid = UUID.v8(buf)

Deserializes the given JSON key into a UUID.

NOTE: require "uuid/json" is required to opt-in to this feature.

Creates new UUID by decoding value string from hyphenated (ie ba714f86-cac6-42c7-8956-bcf5105e1b81), hexstring (ie 89370a4ab66440c8add39e06f2bb6af6) or URN (ie urn:uuid:3f9eaf9e-cdb0-45cc-8ecb-0e5b2bfb0c20) format, returning nil if the string does not match any of these formats.

Generates RFC 4122 v3 UUID with the Namespace::DNS.

• name: The name used to generate the UUID, it can be a string of any size.

Generates RFC 4122 v3 UUID with the Namespace::OID.

• name: The name used to generate the UUID, it can be a string of any size.

Generates RFC 4122 v3 UUID with the Namespace::URL.

• name: The name used to generate the UUID, it can be a string of any size.

Generates RFC 4122 v3 UUID with the Namespace::X500.

• name: The name used to generate the UUID, it can be a string of any size.

Generates RFC 4122 v5 UUID with the Namespace::DNS.

• name: The name used to generate the UUID, it can be a string of any size.

Generates RFC 4122 v5 UUID with the Namespace::OID.

• name: The name used to generate the UUID, it can be a string of any size.

Generates RFC 4122 v5 UUID with the Namespace::URL.

• name: The name used to generate the UUID, it can be a string of any size.

Generates RFC 4122 v5 UUID with the Namespace::X500.

• name: The name used to generate the UUID, it can be a string of any size.

Generates an RFC9562-compatible v7 UUID, allowing the values to be sorted chronologically (with 1ms precision) by their raw or hexstring representation.

The comparison operator. Returns 0 if the two objects are equal, a negative number if this object is considered less than other, a positive number if this object is considered greater than other, or nil if the two objects are not comparable.

Subclasses define this method to provide class-specific ordering.

The comparison operator is usually used to sort values:

# Sort in a descending way:
[3, 1, 2].sort { |x, y| y <=> x } # => [3, 2, 1]

# Sort in an ascending way:
[3, 1, 2].sort { |x, y| x <=> y } # => [1, 2, 3]

Returns the binary representation of the UUID.

See Object#hash(hasher)

Convert to String in literal format.

Returns UUID as JSON value.

NOTE: require "uuid/json" is required to opt-in to this feature.

uuid = UUID.new("87b3042b-9b9a-41b7-8b15-a93d3f17025e")
uuid.to_json # => "\"87b3042b-9b9a-41b7-8b15-a93d3f17025e\""

Same as #inspect(io).

Returns unsafe pointer to 16-bytes.

Returns UUID as YAML value.

NOTE: require "uuid/yaml" is required to opt-in to this feature.

uuid = UUID.new("50a11da6-377b-4bdf-b9f0-076f9db61c93")
uuid.to_yaml # => "--- 50a11da6-377b-4bdf-b9f0-076f9db61c93\n"

Returns a String that is a valid urn of self

require "uuid"

uuid = UUID.empty
uuid.urn # => "urn:uuid:00000000-0000-4000-0000-000000000000"
uuid2 = UUID.new("c49fc136-9362-4414-81a5-9a7e0fcca0f1")
uuid2.urn # => "urn:uuid:c49fc136-9362-4414-81a5-9a7e0fcca0f1"

Returns true if UUID is a V1, raises Error otherwise.

Returns true if UUID is a V1, false otherwise.

Returns true if UUID is a V2, raises Error otherwise.

Returns true if UUID is a V2, false otherwise.

Returns true if UUID is a V3, raises Error otherwise.

Returns true if UUID is a V3, false otherwise.

Returns true if UUID is a V4, raises Error otherwise.

Returns true if UUID is a V4, false otherwise.

Returns true if UUID is a V5, raises Error otherwise.

Returns true if UUID is a V5, false otherwise.

Returns true if UUID is a V6, raises Error otherwise.

Returns true if UUID is a V6, false otherwise.

Returns true if UUID is a V7, raises Error otherwise.

Returns true if UUID is a V7, false otherwise.

Returns true if UUID is a V8, raises Error otherwise.

Returns true if UUID is a V8, false otherwise.

Returns UUID variant based on the RFC4122 format. See also #version

require "uuid"

UUID.new(Slice.new(16, 0_u8), variant: UUID::Variant::NCS).variant       # => UUID::Variant::NCS
UUID.new(Slice.new(16, 0_u8), variant: UUID::Variant::RFC4122).variant   # => UUID::Variant::RFC4122
UUID.new(Slice.new(16, 0_u8), variant: UUID::Variant::Microsoft).variant # => UUID::Variant::Microsoft
UUID.new(Slice.new(16, 0_u8), variant: UUID::Variant::Future).variant    # => UUID::Variant::Future

Returns version based on RFC4122 format. See also #variant.

require "uuid"

UUID.new(Slice.new(16, 0_u8), version: UUID::Version::V1).version # => UUID::Version::V1
UUID.new(Slice.new(16, 0_u8), version: UUID::Version::V2).version # => UUID::Version::V2
UUID.new(Slice.new(16, 0_u8), version: UUID::Version::V3).version # => UUID::Version::V3
UUID.new(Slice.new(16, 0_u8), version: UUID::Version::V4).version # => UUID::Version::V4
UUID.new(Slice.new(16, 0_u8), version: UUID::Version::V5).version # => UUID::Version::V5