ruby-ulid 0.0.12 → 0.0.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 0adfc974863e1b2d248eac28305322e20d6b2dc94465b7ca3462fdd2c8676352
4
- data.tar.gz: caecb83a030fa1eda5534e748ee3206208ebf25a1d9f76d33ad04030b4ea0f0c
3
+ metadata.gz: 9e2d0489b211160618fc0ae6ecd30cbbbbaa411683162def97930ca95a860696
4
+ data.tar.gz: 0063c982795d2a42e2f6bac7b236d831753c685b36f4d047e2999dbe7368c6de
5
5
  SHA512:
6
- metadata.gz: 4a216a8032385e9be00252fb0d9faf1aaa18bdfe75a0ae4b0a2cb1aa438a8786a7e9c477debd87fb6871274c0a50e1579cee41584513199c47b0198c51c6ac6a
7
- data.tar.gz: 664d85fe6070a9c0017e831727a33a87799d1b10e7c4992b44b77be288fcc3cab51ecb528ce01fe0ce5d7a6262f61a2786ce30c54dcd90e8ef36c698f3f76f45
6
+ metadata.gz: 825dab6b7e01f4e1dee5fcd03031ef27645de6a1b56e8392fd784a55c860268af5b84ae4ac3697cdf3eba630dbae197da28cde4b8fbef043c8d0ff48b587f992
7
+ data.tar.gz: f2039e401c77cf15bda81d10587085b7fa167c253a19a66bc0b14ee5fda71162325b7a278f2ebb185d53cbb3fd01563ccb4c6875ffbaebf7fc676a2a24c73767
data/README.md CHANGED
@@ -35,6 +35,8 @@ Instead, herein is proposed ULID:
35
35
 
36
36
  ## Install
37
37
 
38
+ Require Ruby 2.6 or later
39
+
38
40
  ```console
39
41
  $ gem install ruby-ulid
40
42
  #=> Installed
@@ -55,27 +57,7 @@ ulid.octets #=> [1, 121, 20, 95, 7, 202, 187, 60, 175, 51, 76, 60, 49, 73, 37, 7
55
57
  ulid.pattern #=> /(?<timestamp>01F4A5Y1YA)(?<randomness>QCYAYCTC7GRMJ9AA)/i
56
58
  ```
57
59
 
58
- Generator can take `Time` instance
59
-
60
- ```ruby
61
- time = Time.at(946684800, in: 'UTC') #=> 2000-01-01 00:00:00 UTC
62
- ULID.generate(moment: time) #=> ULID(2000-01-01 00:00:00.000 UTC: 00VHNCZB00N018DCPJA4H9379P)
63
- ULID.generate(moment: time) #=> ULID(2000-01-01 00:00:00.000 UTC: 00VHNCZB006WQT3JTMN0T14EBP)
64
-
65
- ulids = 1000.times.map do
66
- ULID.generate(moment: time)
67
- end
68
- ulids.sort == ulids #=> false
69
-
70
- ulids = 1000.times.map do |n|
71
- ULID.generate(moment: time + n)
72
- end
73
- ulids.sort == ulids #=> true
74
- ```
75
-
76
- You can parse from exists IDs
77
-
78
- FYI: Current parser/validator/matcher implementation aims `strict`, It might be changed in [ulid/spec#57](https://github.com/ulid/spec/pull/57) and [ruby-ulid#57](https://github.com/kachick/ruby-ulid/issues/57).
60
+ You can get the objects from exists encoded ULIDs
79
61
 
80
62
  ```ruby
81
63
  ulid = ULID.parse('01ARZ3NDEKTSV4RRFFQ69G5FAV') #=> ULID(2016-07-30 23:54:10.259 UTC: 01ARZ3NDEKTSV4RRFFQ69G5FAV)
@@ -93,6 +75,19 @@ ulids.sort == ulids #=> true
93
75
  ulids.uniq(&:to_time).size #=> 1000
94
76
  ```
95
77
 
78
+ `ULID.generate` can take fixed `Time` instance
79
+
80
+ ```ruby
81
+ time = Time.at(946684800, in: 'UTC') #=> 2000-01-01 00:00:00 UTC
82
+ ULID.generate(moment: time) #=> ULID(2000-01-01 00:00:00.000 UTC: 00VHNCZB00N018DCPJA4H9379P)
83
+ ULID.generate(moment: time) #=> ULID(2000-01-01 00:00:00.000 UTC: 00VHNCZB006WQT3JTMN0T14EBP)
84
+
85
+ ulids = 1000.times.map do |n|
86
+ ULID.generate(moment: time + n)
87
+ end
88
+ ulids.sort == ulids #=> true
89
+ ```
90
+
96
91
  The basic generator prefers `randomness`, it does not guarantee `sortable` for same milliseconds ULIDs.
97
92
 
98
93
  ```ruby
@@ -103,7 +98,7 @@ ulids.uniq(&:to_time).size #=> 35 (the size is not fixed, might be changed in en
103
98
  ulids.sort == ulids #=> false
104
99
  ```
105
100
 
106
- If you want to prefer `sortable` rather than the `strict randomness`, Use `MonotonicGenerator` instead. It is called as [Monotonicity](https://github.com/ulid/spec/tree/d0c7170df4517939e70129b4d6462cc162f2d5bf#monotonicity) on the spec.
101
+ If you want to prefer `sortable` rather than the `randomness`, Use `MonotonicGenerator` instead. It is called as [Monotonicity](https://github.com/ulid/spec/tree/d0c7170df4517939e70129b4d6462cc162f2d5bf#monotonicity) on the spec.
107
102
  (Though it starts with new random value when changed the timestamp)
108
103
 
109
104
  ```ruby
@@ -112,23 +107,41 @@ monotonic_ulids = 10000.times.map do
112
107
  monotonic_generator.generate
113
108
  end
114
109
  sample_ulids_by_the_time = monotonic_ulids.uniq(&:to_time)
115
- sample_ulids_by_the_time.size #=> 34 (the size is not fixed, might be changed in environment)
116
- sample_ulids_by_the_time.take(10).map(&:randomness)
117
- #=>
118
- ["JZW56CTA8704D5AQ",
119
- "JGEBH2A2B2EA97MW",
120
- "0XPE4NS3MZH0NAJ4",
121
- "E0S3ZAVADFBPW57Y",
122
- "E5CX1T6281443THQ",
123
- "3SK8WHSH03CVF7J2",
124
- "DDS35BT0R20P3V49",
125
- "60KG2W9FVEN1ZX8C",
126
- "X59YJVXXVH7AXJJE",
127
- "1ZBQ7SNGFKXGH1Y4"]
110
+ sample_ulids_by_the_time.size #=> 32 (the size is not fixed, might be changed in environment)
111
+
112
+ # In same milliseconds creation, it just increments the end of randomness part
113
+ monotonic_ulids.take(5) #=>
114
+ # [ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK4),
115
+ # ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK5),
116
+ # ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK6),
117
+ # ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK7),
118
+ # ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK8)]
119
+
120
+ # When the milliseconds is updated, it starts with new randomness
121
+ sample_ulids_by_the_time.take(5) #=>
122
+ # [ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK4),
123
+ # ULID(2021-05-02 15:23:48.918 UTC: 01F4PTVCSPF2KXG4ABT7CK3204),
124
+ # ULID(2021-05-02 15:23:48.919 UTC: 01F4PTVCSQF1GERBPCQV6TCX2K),
125
+ # ULID(2021-05-02 15:23:48.920 UTC: 01F4PTVCSRBXN2H4P1EYWZ27AK),
126
+ # ULID(2021-05-02 15:23:48.921 UTC: 01F4PTVCSSK0ASBBZARV7013F8)]
128
127
 
129
128
  monotonic_ulids.sort == monotonic_ulids #=> true
130
129
  ```
131
130
 
131
+ When filtering ULIDs by `Time`, we should consider to handle the precision.
132
+ So this gem provides `ULID.range` to generate `Range[ULID]` from given `Range[Time]`
133
+
134
+ ```ruby
135
+ # Both of below, The begin of `Range[ULID]` will be the minimum in the floored milliseconds of the time1
136
+ include_end = ULID.range(time1..time2) #=> The end of `Range[ULID]` will be the maximum in the floored milliseconds of the time2
137
+ exclude_end = ULID.range(time1...time2) #=> The end of `Range[ULID]` will be the minimum in the floored milliseconds of the time2
138
+
139
+ # So you can use the generated range objects as below
140
+ ulids.grep(include_end)
141
+ ulids.grep(exclude_end)
142
+ #=> I hope the results should be actually you want!
143
+ ```
144
+
132
145
  For rough operations, `ULID.scan` might be useful.
133
146
 
134
147
  ```ruby
@@ -205,6 +218,8 @@ ULID.from_uuidv4('0983d0a2-ff15-4d83-8f37-7dd945b5aa39')
205
218
 
206
219
  ## References
207
220
 
221
+ - [Repository](https://github.com/kachick/ruby-ulid)
208
222
  - [API documents](https://kachick.github.io/ruby-ulid/)
209
223
  - [ulid/spec](https://github.com/ulid/spec)
210
- - [Another choices are UUIDv6, UUIDv7, UUIDv8. But they are still in draft state](https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-01.html)
224
+ - [Another choices are UUIDv6, UUIDv7, UUIDv8. But they are still in draft state](https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-01.html), I will track them in [ruby-ulid#37](https://github.com/kachick/ruby-ulid/issues/37)
225
+ - Current parser/validator/matcher implementation aims `strict`, It might be changed in [ulid/spec#57](https://github.com/ulid/spec/pull/57) and [ruby-ulid#57](https://github.com/kachick/ruby-ulid/issues/57).
data/lib/ulid.rb CHANGED
@@ -121,6 +121,39 @@ class ULID
121
121
  new milliseconds: milliseconds, entropy: entropy
122
122
  end
123
123
 
124
+ # @param [Range<Time>] time_range
125
+ # @return [Range<ULID>]
126
+ def self.range(time_range)
127
+ raise ArgumentError, 'ULID.range takes only Range[Time]' unless time_range.kind_of?(Range)
128
+ begin_time, end_time, exclude_end = time_range.begin, time_range.end, time_range.exclude_end?
129
+
130
+ case begin_time
131
+ when Time
132
+ begin_ulid = min(moment: begin_time)
133
+ when nil
134
+ begin_ulid = min
135
+ else
136
+ raise ArgumentError, 'ULID.range takes only Range[Time]'
137
+ end
138
+
139
+ case end_time
140
+ when Time
141
+ if exclude_end
142
+ end_ulid = min(moment: end_time)
143
+ else
144
+ end_ulid = max(moment: end_time)
145
+ end
146
+ when nil
147
+ # The end should be max and include end, because nil end means to cover endless ULIDs until the limit
148
+ end_ulid = max
149
+ exclude_end = false
150
+ else
151
+ raise ArgumentError, 'ULID.range takes only Range[Time]'
152
+ end
153
+
154
+ Range.new(begin_ulid, end_ulid, exclude_end)
155
+ end
156
+
124
157
  # @param [Time] time
125
158
  # @return [Time]
126
159
  def self.floor(time)
data/lib/ulid/version.rb CHANGED
@@ -2,5 +2,5 @@
2
2
  # frozen_string_literal: true
3
3
 
4
4
  class ULID
5
- VERSION = '0.0.12'
5
+ VERSION = '0.0.13'
6
6
  end
data/sig/ulid.rbs CHANGED
@@ -63,6 +63,7 @@ class ULID
63
63
  def self.current_milliseconds: -> Integer
64
64
  def self.milliseconds_from_time: (Time time) -> Integer
65
65
  def self.milliseconds_from_moment: (moment moment) -> Integer
66
+ def self.range: (Range[Time] time_range) -> Range[ULID]
66
67
  def self.floor: (Time time) -> Time
67
68
  def self.reasonable_entropy: -> Integer
68
69
  def self.parse: (String string) -> ULID
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: ruby-ulid
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.0.12
4
+ version: 0.0.13
5
5
  platform: ruby
6
6
  authors:
7
7
  - Kenichi Kamiya
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2021-05-02 00:00:00.000000000 Z
11
+ date: 2021-05-03 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: integer-base
@@ -30,6 +30,20 @@ dependencies:
30
30
  - - "<"
31
31
  - !ruby/object:Gem::Version
32
32
  version: 0.2.0
33
+ - !ruby/object:Gem::Dependency
34
+ name: rbs
35
+ requirement: !ruby/object:Gem::Requirement
36
+ requirements:
37
+ - - ">="
38
+ - !ruby/object:Gem::Version
39
+ version: 1.2.0
40
+ type: :development
41
+ prerelease: false
42
+ version_requirements: !ruby/object:Gem::Requirement
43
+ requirements:
44
+ - - ">="
45
+ - !ruby/object:Gem::Version
46
+ version: 1.2.0
33
47
  - !ruby/object:Gem::Dependency
34
48
  name: benchmark-ips
35
49
  requirement: !ruby/object:Gem::Requirement
@@ -102,14 +116,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
102
116
  requirements:
103
117
  - - ">="
104
118
  - !ruby/object:Gem::Version
105
- version: '2.5'
119
+ version: 2.6.0
106
120
  required_rubygems_version: !ruby/object:Gem::Requirement
107
121
  requirements:
108
122
  - - ">="
109
123
  - !ruby/object:Gem::Version
110
124
  version: '0'
111
125
  requirements: []
112
- rubygems_version: 3.2.15
126
+ rubygems_version: 3.1.4
113
127
  signing_key:
114
128
  specification_version: 4
115
129
  summary: A handy ULID library