Class: KSUID::Prefixed

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

Overview

Encapsulates the data type for a prefixed KSUID

When you have different types of KSUIDs in your application, it can be helpful to add an identifier to the front of them to give you an idea for what kind of object the KSUID belongs to.

For example, you might use KSUIDs to identify both Events and Customers. For an Event, you could prefix the KSUID with the string ‘evt_`. Likewise, for Customers, you could prefix them with the string `cus_`.

Prefixed gives you affordances for doing just this.

## Ordering

Prefixeds are partially orderable with Type by their timestamps. When ordering them with other Prefixed instances, they order first by prefix, then by timestamp. This means that in a mixed collection, all Customer KSUIDs (prefix: ‘cus_`) would be grouped before all Event KSUIDs (prefix `evt_`).

## Interface

You typically will not instantiate this class directly, but instead use the prefixed builder method to save some typing.

The most commonly used helper methods for the KSUID module also exist on Prefixed for converting between different forms of output.

## Differences from Type

One other thing to note is that Prefixed is not intended to handle binary data because the prefix does not make sense in either the byte string or packed array formats.

Since:

  • 0.5.0

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Type

#eql?, #inspect, #payload, #to_bytes, #to_i, #to_time

Constructor Details

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

Instantiates a new KSUID::Prefixed

Examples:

Generate a new KSUID::Prefixed for the current second

KSUID::Prefixed.new('evt_')

Generate a new KSUID::Prefixed for a given timestamp

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

Parameters:

  • prefix (String) —

    the prefix to add to the KSUID

  • 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

Raises:

  • (ArgumentError)

Since:

  • 0.5.0



129
130
131
132
133
134
135
 
# File 'lib/ksuid/prefixed.rb', line 129

def initialize(prefix, payload: nil, time: Time.now)
  raise ArgumentError, 'requires a prefix' unless prefix

  super(payload: payload, time: time)

  @prefix = prefix
end

Instance Attribute Details

#prefix ⇒ String (readonly)

The prefix in front of the KSUID

Examples:

Getting the prefix to create a similar KSUID::Prefixed

ksuid1 = KSUID.prefixed('cus_')
ksuid2 = KSUID.prefixed(ksuid1.prefix)

Returns:

Since:

  • 0.5.0



146
147
148
 
# File 'lib/ksuid/prefixed.rb', line 146

def prefix
  @prefix
end

Class Method Details

.call(ksuid, prefix:) ⇒ KSUID::Prefixed

Converts a KSUID-compatible value into a KSUID::Prefixed

Examples:

Converts a base 62 KSUID string into a KSUID::Prefixed

KSUID::Prefixed.call('15Ew2nYeRDscBipuJicYjl970D1', prefix: 'evt_')

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if the value is not prefixed KSUID-compatible

Since:

  • 0.5.0



52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/ksuid/prefixed.rb', line 52

def self.call(ksuid, prefix:)
  return unless ksuid && prefix

  case ksuid
  when KSUID::Prefixed then from_base62(ksuid.to_ksuid.to_s, prefix: prefix)
  when KSUID::Type then from_base62(ksuid.to_s, prefix: prefix)
  when String then cast_string(ksuid, prefix: prefix)
  else
    raise ArgumentError, "Cannot convert #{ksuid.inspect} to KSUID::Prefixed"
  end
end

.from_base62(string, prefix:) ⇒ KSUID::Prefixed

Converts a base 62-encoded string into a KSUID::Prefixed

Examples:

Parse a KSUID string into a prefixed object

KSUID::Prefixed.from_base62('0vdbMgWkU6slGpLVCqEFwkkZvuW', prefix: 'evt_')

Parameters:

  • string (String) —

    the base 62-encoded KSUID to convert into an object

  • prefix (String) —

    the prefix to add to the KSUID

Returns:

Since:

  • 0.5.0



74
75
76
77
78
79
80
 
# File 'lib/ksuid/prefixed.rb', line 74

def self.from_base62(string, prefix:)
  string = string.sub(/\A#{prefix}/, '')
  int = Base62.decode(string)
  bytes = Utils.int_to_bytes(int, 160)

  from_bytes(bytes, prefix: prefix)
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 KSUID::Prefixeds

Parameters:

  • other (KSUID::Type) —

    the other object to compare against

Returns:

  • (Integer, nil) —

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

Since:

  • 0.5.0



155
156
157
158
159
160
161
162
163
164
 
# File 'lib/ksuid/prefixed.rb', line 155

def <=>(other)
  return unless other.is_a?(Type)
  return super if other.instance_of?(Type)

  if (result = prefix <=> other.prefix).nonzero?
    result
  else
    super
  end
end

#==(other) ⇒ Boolean

Checks whether this KSUID::Prefixed is equal to another

Examples:

Checks whether two KSUIDs are equal

KSUID.prefixed('evt_') == KSUID.prefixed('evt_')

Parameters:

Returns:

  • (Boolean)

Since:

  • 0.5.0



175
176
177
178
179
 
# File 'lib/ksuid/prefixed.rb', line 175

def ==(other)
  other.is_a?(Prefixed) &&
    prefix == other.prefix &&
    super
end

#hash ⇒ Integer

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

Examples:

Using a KSUID as a Hash key

ksuid1 = KSUID.prefixed('evt_')
ksuid2 = ksuid1.dup
values_by_ksuid = {}

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

Returns:

  • (Integer)

Since:

  • 0.5.0



194
195
196
 
# File 'lib/ksuid/prefixed.rb', line 194

def hash
  [prefix, @uid].hash
end

#raw ⇒ String

The KSUID::Prefixed as a prefixed, hex-encoded string

This is generally useful for comparing against the Go tool.

Examples:

ksuid = KSUID::Prefixed.from_base62('0vdbMgWkU6slGpLVCqEFwkkZvuW', prefix: 'evt_')

ksuid.raw #=> "evt_0683F789049CC215C099D42B784DBE99341BD79C"

Returns:

  • (String) —

    a prefixed, hex-encoded string

Since:

  • 0.5.0



210
211
212
 
# File 'lib/ksuid/prefixed.rb', line 210

def raw
  super.prepend(prefix)
end

#to_ksuid ⇒ KSUID::Type

Converts the KSUID::Prefixed into a Type by dropping the prefix

Examples:

Convert an Event KSUID into a plain KSUID

ksuid = KSUID.prefixed('evt_')

ksuid.to_ksuid

Returns:

Since:

  • 0.5.0



224
225
226
 
# File 'lib/ksuid/prefixed.rb', line 224

def to_ksuid
  KSUID.from_base62(to_s.sub(/\A#{prefix}/, ''))
end

#to_s ⇒ String

The KSUID::Prefixed as a base 62-encoded string

Examples:

ksuid = KSUID::Prefixed.from_base62('0vdbMgWkU6slGpLVCqEFwkkZvuW', prefix: 'evt_')

ksuid.to_s #=> "evt_0vdbMgWkU6slGpLVCqEFwkkZvuW"

Returns:

  • (String) —

    the prefixed, base 62-encoded string for the KSUID::Prefixed

Since:

  • 0.5.0



238
239
240
 
# File 'lib/ksuid/prefixed.rb', line 238

def to_s
  super.prepend(prefix)
end