struct UUID

Overview

Represents a UUID (Universally Unique IDentifier).

NOTE To useUUID, you must explicitly import it withrequire "uuid"

Included Modules

Defined in:

uuid.cr
uuid/json.cr
uuid/yaml.cr

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from module Comparable(UUID)

<(other : T) : Bool <, <=(other : T) <=, <=>(other : T) <=>, ==(other : T) ==, >(other : T) : Bool >, >=(other : T) >=, clamp(min, max)
clamp(range : Range) clamp

Instance methods inherited from struct Struct

==(other : YAML::Any)
==(other) : Bool ==, hash(hasher) hash, inspect(io : IO) : Nil inspect, pretty_print(pp) : Nil pretty_print, to_s(io : IO) : Nil to_s

Class methods inherited from struct Struct

pre_initialize(address : Pointer) : Nil pre_initialize

Instance methods inherited from struct Value

==(other : Log::Metadata::Value)
==(other : JSON::Any)
==(other : YAML::Any)
==(other) ==, dup dup

Instance methods inherited from class Object

! : Bool !, !=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other) ===, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash(hasher)
hash hash, in?(collection : Object) : Bool
in?(*values : Object) : Bool in?, inspect(io : IO) : Nil
inspect : String inspect, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil!(message)
not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO) : Nil
to_json : String to_json, to_pretty_json(indent : String = " ") : String
to_pretty_json(io : IO, indent : String = " ") : Nil to_pretty_json, to_s(io : IO) : Nil
to_s : String to_s, to_yaml(io : IO) : Nil
to_yaml : String to_yaml, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

Class methods inherited from class Object

from_json(string_or_io : String | IO, root : String)
from_json(string_or_io : String | IO) from_json, from_yaml(string_or_io : String | IO) from_yaml

Macros inherited from class Object

class_getter(*names, &block) class_getter, class_getter!(*names) class_getter!, class_getter?(*names, &block) class_getter?, class_property(*names, &block) class_property, class_property!(*names) class_property!, class_property?(*names, &block) class_property?, class_setter(*names) class_setter, def_clone def_clone, def_equals(*fields) def_equals, def_equals_and_hash(*fields) def_equals_and_hash, def_hash(*fields) def_hash, delegate(*methods, to object) delegate, forward_missing_to(delegate) forward_missing_to, getter(*names, &block) getter, getter!(*names) getter!, getter?(*names, &block) getter?, property(*names, &block) property, property!(*names) property!, property?(*names, &block) property?, setter(*names) setter

Constructor Detail

def self.empty : self #

Generates an empty UUID.

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

def self.new(bytes : StaticArray(UInt8, 16), variant : UUID::Variant | Nil = nil, version : UUID::Version | Nil = nil) #

Generates UUID frombytes, applyingversion andvariant to the UUID if present.


def self.new(slice : Slice(UInt8), variant : Variant | Nil = nil, version : Version | Nil = nil) #

Creates UUID from 16-bytes slice. Raises ifslice isn't 16 bytes long. See #initialize forvariant andversion.


def self.new(uuid : UUID, variant : Variant | Nil = nil, version : Version | Nil = nil) #

Creates anotherUUID which is a copy ofuuid, but allows overriding variant orversion.


def self.new(value : String, variant : Variant | Nil = nil, version : Version | Nil = nil) #

Creates new UUID by decodingvalue string from hyphenated (ieba714f86-cac6-42c7-8956-bcf5105e1b81), hexstring (ie89370a4ab66440c8add39e06f2bb6af6) or URN (ieurn:uuid:3f9eaf9e-cdb0-45cc-8ecb-0e5b2bfb0c20) format, raising anArgumentError if the string does not match any of these formats.


def self.new(ctx : YAML::ParseContext, node : YAML::Nodes::Node) #

CreatesUUID from YAML usingYAML::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)

def self.new(pull : JSON::PullParser) #

Creates UUID from JSON usingJSON::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)

def self.random(random : Random = Random::Secure, variant : Variant = :rfc4122, version : Version = :v4) : self #

Generates RFC 4122 v4 UUID.

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


def self.v1(*, clock_seq : UInt16 | Nil = nil, node_id : MAC | Nil = nil) : self #

Generates RFC 4122 v1 UUID.

The traditional method for generating anode_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-randomnode_id is generated as described in section 4.5 of the RFC.

The sequence numberclock_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.


def self.v2(domain : Domain, id : UInt32, node_id : MAC | Nil = nil) : self #

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.

Theid depends on thedomain, for theDomain::Person usually the local user id (uid) is used, forDomain::Group usually the local group id (gid) is used. In case the traditional MAC address based approach should be taken thenode_id can be provided. Otherwise secure random is used.


def self.v3(name : String, namespace : UUID) : self #

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


def self.v4(random r : Random = Random::Secure) : self #

Generates RFC 4122 v4 UUID.

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


def self.v5(name : String, namespace : UUID) : self #

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


Class Method Detail

def self.from_json_object_key?(key : String) #

Deserializes the given JSONkey into aUUID.

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


def self.parse?(value : String, variant : Variant | Nil = nil, version : Version | Nil = nil) : UUID | Nil #

Creates new UUID by decodingvalue string from hyphenated (ieba714f86-cac6-42c7-8956-bcf5105e1b81), hexstring (ie89370a4ab66440c8add39e06f2bb6af6) or URN (ieurn:uuid:3f9eaf9e-cdb0-45cc-8ecb-0e5b2bfb0c20) format, returningnil if the string does not match any of these formats.


def self.v3_dns(name : String) #

Generates RFC 4122 v3 UUID with theNamespace::DNS.

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

def self.v3_oid(name : String) #

Generates RFC 4122 v3 UUID with theNamespace::OID.

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

def self.v3_url(name : String) #

Generates RFC 4122 v3 UUID with theNamespace::URL.

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

def self.v3_x500(name : String) #

Generates RFC 4122 v3 UUID with theNamespace::X500.

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

def self.v5_dns(name : String) #

Generates RFC 4122 v5 UUID with theNamespace::DNS.

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

def self.v5_oid(name : String) #

Generates RFC 4122 v5 UUID with theNamespace::OID.

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

def self.v5_url(name : String) #

Generates RFC 4122 v5 UUID with theNamespace::URL.

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

def self.v5_x500(name : String) #

Generates RFC 4122 v5 UUID with theNamespace::X500.

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

def self.v7(random r : Random = Random::Secure) #

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


Instance Method Detail

def <=>(other : UUID) : Int32 #
Description copied from module Comparable(UUID)

The comparison operator. Returns0 if the two objects are equal, a negative number if this object is considered less thanother, a positive number if this object is considered greater thanother, ornil 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]

def ==(other : self) #

def bytes : StaticArray(UInt8, 16) #

Returns the binary representation of the UUID.


def hash(hasher) #
Description copied from struct Struct

SeeObject#hash(hasher)


def hexstring : String #

def inspect(io : IO) : Nil #

Convert toString in literal format.


def to_json(json : JSON::Builder) : Nil #

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\""

def to_s(io : IO) : Nil #
Description copied from struct Struct

Same as#inspect(io).


def to_unsafe #

Returns unsafe pointer to 16-bytes.


def to_yaml(yaml : YAML::Nodes::Builder) #

ReturnsUUID 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"

def urn : String #

Returns aString that is a valid urn ofself

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"

def v1! #

Returnstrue if UUID is a V1, raisesError otherwise.


def v1? #

Returnstrue if UUID is a V1,false otherwise.


def v2! #

Returnstrue if UUID is a V2, raisesError otherwise.


def v2? #

Returnstrue if UUID is a V2,false otherwise.


def v3! #

Returnstrue if UUID is a V3, raisesError otherwise.


def v3? #

Returnstrue if UUID is a V3,false otherwise.


def v4! #

Returnstrue if UUID is a V4, raisesError otherwise.


def v4? #

Returnstrue if UUID is a V4,false otherwise.


def v5! #

Returnstrue if UUID is a V5, raisesError otherwise.


def v5? #

Returnstrue if UUID is a V5,false otherwise.


def v7! #

Returnstrue if UUID is a V7, raisesError otherwise.


def v7? #

Returnstrue if UUID is a V7,false otherwise.


def variant : UUID::Variant #

Returns UUID variant based on theRFC4122 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

def version : UUID::Version #

Returns version based onRFC4122 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