Class: KSUID::Type

Inherits:
Object
  • Object
show all
Includes:
Comparable
Defined in:
lib/ksuid/type.rb

Overview

Encapsulates the data type for a KSUID

This is the main class that you will interact with in this gem. You will not typically generate these directly, but this is the resulting data type for all of the main generation methods on the KSUID module.

A KSUID type has two pieces of information contained within its byte-encoded data:

  1. The timestamp associated with the KSUID (stored as the first 4 bytes)

  2. The payload, or random data, for the KSUID (stored as the last 16 bytes)

The type gives you access to several handles into these data.

Direct Known Subclasses

Prefixed

Instance Method Summary collapse

Constructor Details

#initialize(payload: nil, time: Time.now) ⇒ KSUID::Type

Instantiates a new KSUID type

Examples:

Generate a new KSUID for the current second

KSUID::Type.new

Generate a new KSUID for a given timestamp

KSUID::Type.new(time: Time.parse('2017-11-05 15:00:04 UTC'))



33
34
35
36
37
38
 
# File 'lib/ksuid/type.rb', line 33

def initialize(payload: nil, time: Time.now)
  payload ||= KSUID.config.random_generator.call
  byte_encoding = Utils.int_to_bytes(time.to_i - EPOCH_TIME)

  @uid = byte_encoding.bytes + payload.bytes
end

Instance Method Details

#<=>(other) ⇒ Integer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Implements the Comparable interface for sorting KSUIDs



46
47
48
 
# File 'lib/ksuid/type.rb', line 46

def <=>(other)
  to_time <=> other.to_time
end

#==(other) ⇒ Boolean

Checks whether this KSUID is equal to another

Examples:

Checks whether two KSUIDs are equal

KSUID.new == KSUID.new



59
60
61
 
# File 'lib/ksuid/type.rb', line 59

def ==(other)
  other.to_s == to_s
end

#eql?(other) ⇒ Boolean

Checks whether this KSUID hashes to the same hash key as another

Examples:

Checks whether two KSUIDs hash to the same key

KSUID.new.eql? KSUID.new



72
73
74
 
# File 'lib/ksuid/type.rb', line 72

def eql?(other)
  hash == other.hash
end

#hash ⇒ Integer

Generates the key to use when using a KSUID as a hash key

Examples:

Using a KSUID as a Hash key

ksuid1 = KSUID.new
ksuid2 = KSUID.from_base62(ksuid1.to_s)
values_by_ksuid = {}

values_by_ksuid[ksuid1] = "example"
values_by_ksuid[ksuid2] #=> "example"



89
90
91
 
# File 'lib/ksuid/type.rb', line 89

def hash
  @uid.hash
end

#inspect ⇒ String

Prints the KSUID for debugging within a console

Examples:

Show the maximum KSUID

KSUID.max.inspect  #=> "<KSUID(aWgEPTl1tmebfsQzFP4bxwgy80V)>"



101
102
103
 
# File 'lib/ksuid/type.rb', line 101

def inspect
  "<KSUID(#{self})>"
end

#payload ⇒ String

The payload for the KSUID, as a hex-encoded string

This is generally useful for comparing against the Go tool

Examples:

ksuid = KSUID.from_base62('0vdbMgWkU6slGpLVCqEFwkkZvuW')

ksuid.payload #=> "049CC215C099D42B784DBE99341BD79C"



117
118
119
 
# File 'lib/ksuid/type.rb', line 117

def payload
  Utils.bytes_to_hex_string(uid.last(BYTES[:payload]))
end

#raw ⇒ String

The KSUID as a hex-encoded string

This is generally useful for comparing against the Go tool.

Examples:

ksuid = KSUID.from_base62('0vdbMgWkU6slGpLVCqEFwkkZvuW')

ksuid.raw #=> "0683F789049CC215C099D42B784DBE99341BD79C"



133
134
135
 
# File 'lib/ksuid/type.rb', line 133

def raw
  Utils.bytes_to_hex_string(uid)
end

#to_bytes ⇒ String

The KSUID as a byte string

Examples:

ksuid = KSUID.from_base62('0vdbMgWkU6slGpLVCqEFwkkZvuW')

ksuid.to_bytes



147
148
149
 
# File 'lib/ksuid/type.rb', line 147

def to_bytes
  Utils.byte_string_from_array(uid)
end

#to_i ⇒ Integer

The KSUID as a Unix timestamp

Examples:

ksuid = KSUID.from_base62('0vdbMgWkU6slGpLVCqEFwkkZvuW')

ksuid.to_i #=> 109311881



161
162
163
 
# File 'lib/ksuid/type.rb', line 161

def to_i
  Utils.int_from_bytes(uid.first(BYTES[:timestamp]))
end

#to_s ⇒ String

The KSUID as a base 62-encoded string

Examples:

ksuid = KSUID.from_base62('0vdbMgWkU6slGpLVCqEFwkkZvuW')

ksuid.to_s #=> "0vdbMgWkU6slGpLVCqEFwkkZvuW"



175
176
177
 
# File 'lib/ksuid/type.rb', line 175

def to_s
  Base62.encode_bytes(uid)
end

#to_time ⇒ String

The time the KSUID was generated

Examples:

ksuid = KSUID.from_base62('0vdbMgWkU6slGpLVCqEFwkkZvuW')

ksuid.to_time.utc.to_s #=> "2017-10-29 21:18:01 UTC"



189
190
191
 
# File 'lib/ksuid/type.rb', line 189

def to_time
  Time.at(to_i + EPOCH_TIME)
end