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.cruuid/json.cr
Constructors
-
.empty : self
Generates an empty UUID.
-
.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.
-
.new(slice : Slice(UInt8), variant : Variant | Nil = nil, version : Version | Nil = nil)
Creates UUID from 16-bytes slice.
-
.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. -
.new(value : String, variant : Variant | Nil = nil, version : Version | Nil = nil)
Creates new UUID by decoding
value
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. -
.new(pull : JSON::PullParser)
Creates UUID from JSON using
JSON::PullParser
. -
.random(random : Random = Random::Secure, variant : Variant = :rfc4122, version : Version = :v4) : self
Generates RFC 4122 v4 UUID.
-
.v1(*, clock_seq : UInt16 | Nil = nil, node_id : MAC | Nil = nil) : self
Generates RFC 4122 v1 UUID.
-
.v2(domain : Domain, id : UInt32, node_id : MAC | Nil = nil) : self
Generates RFC 4122 v2 UUID.
-
.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. -
.v4(random r : Random = Random::Secure) : self
Generates RFC 4122 v4 UUID.
-
.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.
Class Method Summary
-
.from_json_object_key?(key : String)
Deserializes the given JSON key into a
UUID
. -
.parse?(value : String, variant : Variant | Nil = nil, version : Version | Nil = nil) : UUID | Nil
Creates new UUID by decoding
value
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. -
.v3_dns(name : String)
Generates RFC 4122 v3 UUID with the
Namespace::DNS
. -
.v3_oid(name : String)
Generates RFC 4122 v3 UUID with the
Namespace::OID
. -
.v3_url(name : String)
Generates RFC 4122 v3 UUID with the
Namespace::URL
. -
.v3_x500(name : String)
Generates RFC 4122 v3 UUID with the
Namespace::X500
. -
.v5_dns(name : String)
Generates RFC 4122 v5 UUID with the
Namespace::DNS
. -
.v5_oid(name : String)
Generates RFC 4122 v5 UUID with the
Namespace::OID
. -
.v5_url(name : String)
Generates RFC 4122 v5 UUID with the
Namespace::URL
. -
.v5_x500(name : String)
Generates RFC 4122 v5 UUID with the
Namespace::X500
.
Instance Method Summary
-
#<=>(other : UUID) : Int32
The comparison operator.
- #==(other : self)
-
#bytes : StaticArray(UInt8, 16)
Returns the binary representation of the UUID.
- #hash(hasher)
- #hexstring : String
-
#inspect(io : IO) : Nil
Convert to
String
in literal format. -
#to_json(json : JSON::Builder) : Nil
Returns UUID as JSON value.
-
#to_s(io : IO) : Nil
Same as
#inspect(io)
. -
#to_unsafe
Returns unsafe pointer to 16-bytes.
-
#urn : String
Returns a
String
that is a valid urn of self -
#v1!
Returns
true
if UUID is a V1, raisesError
otherwise. -
#v1?
Returns
true
if UUID is a V1,false
otherwise. -
#v2!
Returns
true
if UUID is a V2, raisesError
otherwise. -
#v2?
Returns
true
if UUID is a V2,false
otherwise. -
#v3!
Returns
true
if UUID is a V3, raisesError
otherwise. -
#v3?
Returns
true
if UUID is a V3,false
otherwise. -
#v4!
Returns
true
if UUID is a V4, raisesError
otherwise. -
#v4?
Returns
true
if UUID is a V4,false
otherwise. -
#v5!
Returns
true
if UUID is a V5, raisesError
otherwise. -
#v5?
Returns
true
if UUID is a V5,false
otherwise. -
#variant : UUID::Variant
Returns UUID variant based on the RFC4122 format.
-
#version : UUID::Version
Returns version based on RFC4122 format.
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
Constructor Detail
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 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
.
Class Method Detail
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.
Instance Method Detail
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 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\""
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 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