struct UUID

Overview

Represents a UUID (Universally Unique IDentifier).

NOTE To use UUID, you must explicitly import it with require "uuid"

Included Modules

Defined in:

uuid.cr
uuid/json.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) : Bool ==, hash(hasher) hash, inspect(io : IO) : Nil inspect, pretty_print(pp) : Nil pretty_print, to_s(io : IO) : Nil to_s

Instance methods inherited from struct 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, root : String)
from_json(string_or_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)

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

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


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

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


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

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


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

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.


[View source]
def self.new(pull : JSON::PullParser) #

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)

[View source]
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 as Random::Secure.


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

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.


[View source]
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.

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.


[View source]
def self.v3(name : String, namespace : UUID) : self #

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.


[View source]
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 as Random::Secure.


[View source]
def self.v5(name : String, namespace : UUID) : self #

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.


[View source]

Class Method Detail

def self.from_json_object_key?(key : String) #

Deserializes the given JSON key into a UUID.

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


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

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.


[View source]
def self.v3_dns(name : String) #

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.

[View source]
def self.v3_oid(name : String) #

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.

[View source]
def self.v3_url(name : String) #

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.

[View source]
def self.v3_x500(name : String) #

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.

[View source]
def self.v5_dns(name : String) #

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.

[View source]
def self.v5_oid(name : String) #

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.

[View source]
def self.v5_url(name : String) #

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.

[View source]
def self.v5_x500(name : String) #

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.

[View source]
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.


[View source]

Instance Method Detail

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

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]

[View source]
def ==(other : self) #

def bytes : StaticArray(UInt8, 16) #

Returns the binary representation of the UUID.


[View source]
def hash(hasher) #
Description copied from struct Struct

See Object#hash(hasher)


def hexstring : String #

[View source]
def inspect(io : IO) : Nil #

Convert to String in literal format.


[View source]
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\""

[View source]
def to_s(io : IO) : Nil #
Description copied from struct Struct

Same as #inspect(io).


[View source]
def to_unsafe #

Returns unsafe pointer to 16-bytes.


[View source]
def urn : String #

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"

[View source]
def v1! #

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


[View source]
def v1? #

Returns true if UUID is a V1, false otherwise.


[View source]
def v2! #

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


[View source]
def v2? #

Returns true if UUID is a V2, false otherwise.


[View source]
def v3! #

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


[View source]
def v3? #

Returns true if UUID is a V3, false otherwise.


[View source]
def v4! #

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


[View source]
def v4? #

Returns true if UUID is a V4, false otherwise.


[View source]
def v5! #

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


[View source]
def v5? #

Returns true if UUID is a V5, false otherwise.


[View source]
def v7! #

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


[View source]
def v7? #

Returns true if UUID is a V7, false otherwise.


[View source]
def variant : UUID::Variant #

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

[View source]
def version : UUID::Version #

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

[View source]