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
uuid/yaml.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 UUIDwhich 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 valuestring from hyphenated (ieba714f86-cac6-42c7-8956-bcf5105e1b81), hexstring (ie89370a4ab66440c8add39e06f2bb6af6) or URN (ieurn:uuid:3f9eaf9e-cdb0-45cc-8ecb-0e5b2bfb0c20) format, raising anArgumentErrorif the string does not match any of these formats.
- 
        .new(ctx : YAML::ParseContext, node : YAML::Nodes::Node)
        
          Creates UUIDfrom YAML usingYAML::ParseContext.
- 
        .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 nameto 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 nameto 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 valuestring from hyphenated (ieba714f86-cac6-42c7-8956-bcf5105e1b81), hexstring (ie89370a4ab66440c8add39e06f2bb6af6) or URN (ieurn:uuid:3f9eaf9e-cdb0-45cc-8ecb-0e5b2bfb0c20) format, returningnilif 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.
- 
        .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 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 Stringin 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. 
- 
        #to_yaml(yaml : YAML::Nodes::Builder)
        
          Returns UUIDas YAML value.
- 
        #urn : String
        
          Returns a Stringthat is a valid urn of self
- 
        #v1!
        
          Returns trueif UUID is a V1, raisesErrorotherwise.
- 
        #v1?
        
          Returns trueif UUID is a V1,falseotherwise.
- 
        #v2!
        
          Returns trueif UUID is a V2, raisesErrorotherwise.
- 
        #v2?
        
          Returns trueif UUID is a V2,falseotherwise.
- 
        #v3!
        
          Returns trueif UUID is a V3, raisesErrorotherwise.
- 
        #v3?
        
          Returns trueif UUID is a V3,falseotherwise.
- 
        #v4!
        
          Returns trueif UUID is a V4, raisesErrorotherwise.
- 
        #v4?
        
          Returns trueif UUID is a V4,falseotherwise.
- 
        #v5!
        
          Returns trueif UUID is a V5, raisesErrorotherwise.
- 
        #v5?
        
          Returns trueif UUID is a V5,falseotherwise.
- 
        #v7!
        
          Returns trueif UUID is a V7, raisesErrorotherwise.
- 
        #v7?
        
          Returns trueif UUID is a V7,falseotherwise.
- 
        #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
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
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 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.
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.
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
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 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 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::FutureReturns 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