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.

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'))

Parameters:

  • payload (String|Array<Integer>|nil) (defaults to: nil) —

    the payload for the KSUID

  • time (Time) (defaults to: Time.now) —

    the timestamp to use for the KSUID



37
38
39
40
41
42
 
# File 'lib/ksuid/type.rb', line 37

def initialize(payload: nil, time: Time.now)
  payload ||= SecureRandom.random_bytes(BYTES[:payload])
  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

Parameters:

  • other (KSUID::Type) —

    the other object to compare against

Returns:

  • (Integer) —

    -1 for less than other, 0 for equal to, 1 for greater than other



50
51
52
 
# File 'lib/ksuid/type.rb', line 50

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

Parameters:

  • other (KSUID::Type) —

    the other KSUID to check against

Returns:

  • (Boolean) 


63
64
65
 
# File 'lib/ksuid/type.rb', line 63

def ==(other)
  other.to_s == to_s
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"

Returns:

  • (String) —

    a hex-encoded string



79
80
81
 
# File 'lib/ksuid/type.rb', line 79

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"

Returns:

  • (String) —

    a hex-encoded string



95
96
97
 
# File 'lib/ksuid/type.rb', line 95

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

Returns:

  • (String) —

    a byte string



109
110
111
 
# File 'lib/ksuid/type.rb', line 109

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

Returns:

  • (Integer) —

    the Unix timestamp for the event (without the epoch shift)



123
124
125
126
127
 
# File 'lib/ksuid/type.rb', line 123

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

  unix_time
end

#to_s ⇒ String

The KSUID as a base 62-encoded string

Examples:

ksuid = KSUID.from_base62('0vdbMgWkU6slGpLVCqEFwkkZvuW')

ksuid.to_s #=> "0vdbMgWkU6slGpLVCqEFwkkZvuW"

Returns:

  • (String) —

    the base 62-encoded string for the KSUID



139
140
141
 
# File 'lib/ksuid/type.rb', line 139

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"

Returns:

  • (String) —

    the base 62-encoded string for the KSUID



153
154
155
 
# File 'lib/ksuid/type.rb', line 153

def to_time
  Time.at(to_i + EPOCH_TIME)
end