ruby-ulid 0.1.1 → 0.1.2

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: d9517a4c0fe5e9feec91b2d8e19366baed6b8f1c1ccb42640389c1ad11066854
4
- data.tar.gz: 24344ffd2549f7eae76f6f344169eb74baf3168e05499a9d7577a18fea63fc4d
3
+ metadata.gz: 04b50bb9543b78d03a0e1676b988060b3e34348c0785979fde52c46e414be1d8
4
+ data.tar.gz: bf070ba0522e8ce743c67bcfa225bf5b49009ae4ecd6532eef19484d51eb14ce
5
5
  SHA512:
6
- metadata.gz: 5420da3cddc622a02a9d84ba398c17f59c733eea62d122aef0e5fb39dfade8e76cb3e4608814a0afb5c2e0251c6ebbbb2a10c6b27ea68b4ff8e32ad9f2e31ee3
7
- data.tar.gz: 7bb4f8f941ed3f3ec2d5ebef03b4559b1ba2b07eaf5a9970ee3936ba6157bf5ff818eabc63847ba973536910bd6e8b8c65ae3382b74a368af85e228fec6524dd
6
+ metadata.gz: 4ad79f68c4903f775750417085676a98e810cae71b635b0b0e3e5547dd8b652a6bd89b01cb452510054f400a9bfef7ae26e308456d46a7571be10cb7ef1f334f
7
+ data.tar.gz: 88769b682521bb83b3775784e808b4e08636313d2055c7afe1f6b3a966e211237c597e0c354e0a6a6a26e227246c96845671f24cd7ebb8bf9d93014d043147f0
data/README.md CHANGED
@@ -10,7 +10,7 @@ Also providing [ruby/rbs](https://github.com/ruby/rbs) signature files.
10
10
 
11
11
  ![ULIDlogo](https://raw.githubusercontent.com/kachick/ruby-ulid/main/logo.png)
12
12
 
13
- ![Build Status](https://github.com/kachick/ruby-ulid/actions/workflows/test.yml/badge.svg?branch=main)
13
+ ![Build Status](https://github.com/kachick/ruby-ulid/actions/workflows/test_behaviors.yml/badge.svg?branch=main)
14
14
  [![Gem Version](https://badge.fury.io/rb/ruby-ulid.png)](http://badge.fury.io/rb/ruby-ulid)
15
15
 
16
16
  ## Universally Unique Lexicographically Sortable Identifier
@@ -49,7 +49,7 @@ Should be installed!
49
49
  Add this line to your application/library's `Gemfile` is needed in basic use-case
50
50
 
51
51
  ```ruby
52
- gem 'ruby-ulid', '>= 0.1.1', '< 0.2.0'
52
+ gem 'ruby-ulid', '>= 0.1.2', '< 0.2.0'
53
53
  ```
54
54
 
55
55
  ### Generator and Parser
@@ -170,7 +170,7 @@ exclude_end = ULID.range(time1...time2) #=> The end of `Range[ULID]` will be the
170
170
 
171
171
  # Below patterns are acceptable
172
172
  pinpointing = ULID.range(time1..time1) #=> This will match only for all IDs in `time1`
173
- until_the_end = ULID.range(..time1) #=> This will match only for all IDs upto `time1` (The `nil` starting `Range` can be used since Ruby 2.7)
173
+ # until_the_end = ULID.range(..time1) #=> This will match only for all IDs upto `time1` (The `nil` starting `Range` can be used since Ruby 2.7)
174
174
  until_the_end = ULID.range(ULID.min.to_time..time1) #=> This is same as above for Ruby 2.6
175
175
  until_the_ulid_limit = ULID.range(time1..) # This will match only for all IDs from `time1` to max value of the ULID limit
176
176
 
@@ -313,7 +313,7 @@ ulids.take(10)
313
313
  # ULID(2021-04-29 03:18:24.152 UTC: 01F4DT4Z4RA0QV8WFQGRAG63EH),
314
314
  # ULID(2021-05-02 13:27:16.394 UTC: 01F4PM605ABF5SDVMEHBH8JJ9R)]
315
315
  ULID.sample(10, period: ulid1.to_time..ulid2.to_time)
316
- #=>
316
+ #=>
317
317
  # [ULID(2021-04-29 06:44:41.513 UTC: 01F4E5YPD9XQ3MYXWK8ZJKY8SW),
318
318
  # ULID(2021-05-01 00:35:06.629 UTC: 01F4JNKD85SVK1EAEYSJGF53A2),
319
319
  # ULID(2021-05-02 12:45:28.408 UTC: 01F4PHSEYRG9BWBEWMRW1XE6WW),
@@ -335,7 +335,7 @@ The imported timestamp is meaningless. So ULID's benefit will lost.
335
335
  # Currently experimental feature, so needed to load the extension.
336
336
  require 'ulid/uuid'
337
337
 
338
- # Basically reversible
338
+ # Basically reversible
339
339
  ulid = ULID.from_uuidv4('0983d0a2-ff15-4d83-8f37-7dd945b5aa39') #=> ULID(2301-07-10 00:28:28.821 UTC: 09GF8A5ZRN9P1RYDVXV52VBAHS)
340
340
  ulid.to_uuidv4 #=> "0983d0a2-ff15-4d83-8f37-7dd945b5aa39"
341
341
 
@@ -403,81 +403,11 @@ NOTE: It is still having precision issue similar as `ulid gem` in the both gener
403
403
  1. [Fix to handle timestamp precision in parser](https://github.com/abachman/ulid-ruby/pull/5)
404
404
  1. [Fix to handle timestamp precision in generator](https://github.com/abachman/ulid-ruby/pull/4)
405
405
 
406
- ### Generating benchmarks
407
-
408
- This runs rough benchmarks
409
-
410
- ```console
411
- $ rake benchmark_with_other_gems
412
- (Do not use `bundle exec`!)
413
- ```
414
-
415
- <details>
416
- <summary>One of the result at 2021/05/10 on my machine</summary>
417
-
418
- ```plaintext
419
- #### rafaelsales - ulid
420
- cd ./benchmark/compare_with_othergems/rafaelsales && bundle install --quiet && bundle exec ruby -v ./generate.rb
421
- ruby 3.0.1p64 (2021-04-05 revision 0fb782ee38) [x86_64-darwin20]
422
- Warming up --------------------------------------
423
- ULID.generate 5.560k i/100ms
424
- Calculating -------------------------------------
425
- ULID.generate 52.655k (±11.0%) i/s - 261.320k in 5.029719s
426
- "`ulid gem - 1.3.0` generated products: 371927 - sample: [\"01F59Y97807D2S67KE6X7ATK7Z\", \"01F59Y9AVRQJFAT5M2N7Z72BVF\", \"01F59Y95Z1042X4Z1K9729BSE3\", \"01F59Y95ZMVDFKD63Y8TT145GQ\", \"01F59Y94YQEZ3PH5STZ8PS1JPG\"]"
427
- ------------------------------------------------------------------------
428
- #### abachman - ulid-ruby
429
- cd ./benchmark/compare_with_othergems/abachman && bundle install --quiet && bundle exec ruby -v ./generate.rb
430
- ruby 3.0.1p64 (2021-04-05 revision 0fb782ee38) [x86_64-darwin20]
431
- Warming up --------------------------------------
432
- ULID.generate 3.862k i/100ms
433
- Calculating -------------------------------------
434
- ULID.generate 38.415k (±13.1%) i/s - 189.238k in 5.025788s
435
- "`ulid-ruby gem - 1.0.0` generated products: 260625 - sample: [\"01F59Y9H9V17EPXTYNZDCXB9EZ\", \"01F59Y9J4S4XZ68MF5DJDWHTAC\", \"01F59Y9J8887VC8E850QSBDCDX\", \"01F59Y9JEJPD088EYXVHB86W3N\", \"01F59Y9GGAZFXGCB92EQD695CZ\"]"
436
- ------------------------------------------------------------------------
437
- #### kachick - ruby-ulid(This one)
438
- cd ./benchmark/compare_with_othergems/kachick && bundle install --quiet && bundle exec ruby -v ./generate.rb
439
- ruby 3.0.1p64 (2021-04-05 revision 0fb782ee38) [x86_64-darwin20]
440
- Warming up --------------------------------------
441
- ULID.generate.to_s 3.185k i/100ms
442
- Calculating -------------------------------------
443
- ULID.generate.to_s 31.934k (± 9.1%) i/s - 159.250k in 5.030707s
444
- "`ruby-ulid gem (this one) - 0.1.0` generated products: 223867 - sample: [\"01F59Y9SPZHM6JCTYP50CHGVAX\", \"01F59Y9VB7X0SX32MMKF78KJR3\", \"01F59Y9W0C83RYCNYVH84R4JG3\", \"01F59Y9V218Q3D4YP3W74ET3EW\", \"01F59Y9X6DD8NX99WBGCR7RNXF\"]"
445
- ```
406
+ ### Compare performance with them
446
407
 
447
- In another execution, Changed as below. So there doesn't seem to be a big difference.
448
-
449
- ```plaintext
450
- #### rafaelsales - ulid
451
- cd ./benchmark/compare_with_othergems/rafaelsales && bundle install --quiet && bundle exec ruby -v ./generate.rb
452
- ruby 3.0.1p64 (2021-04-05 revision 0fb782ee38) [x86_64-darwin20]
453
- Warming up --------------------------------------
454
- ULID.generate 2.473k i/100ms
455
- Calculating -------------------------------------
456
- ULID.generate 24.101k (±15.9%) i/s - 118.704k in 5.066190s
457
- "`ulid gem - 1.3.0` generated products: 164763 - sample: [\"01F59YEGPFMXXZWC1YQ49TSK8Y\", \"01F59YEFF7VX5WAW91VTCSE2N9\", \"01F59YEEZ5P9428SDYEDYW8D27\", \"01F59YEHVK56DZBJSNSQK6V1W6\", \"01F59YEHE07M98PVV97ABBAKHM\"]"
458
- ------------------------------------------------------------------------
459
- #### abachman - ulid-ruby
460
- cd ./benchmark/compare_with_othergems/abachman && bundle install --quiet && bundle exec ruby -v ./generate.rb
461
- ruby 3.0.1p64 (2021-04-05 revision 0fb782ee38) [x86_64-darwin20]
462
- Warming up --------------------------------------
463
- ULID.generate 2.620k i/100ms
464
- Calculating -------------------------------------
465
- ULID.generate 27.571k (±14.2%) i/s - 136.240k in 5.056272s
466
- "`ulid-ruby gem - 1.0.0` generated products: 186683 - sample: [\"01F59YEVX6GC9TC0RCZ74RC6Z3\", \"01F59YESJXWYGZ61TXHKRVKS97\", \"01F59YEVQ4QQKBED5T49RTV1MA\", \"01F59YEPJ6MMZY1N63DNW7C4SN\", \"01F59YEQK52K8TKTP1ESC6VC5X\"]"
467
- ------------------------------------------------------------------------
468
- #### kachick - ruby-ulid(This one)
469
- cd ./benchmark/compare_with_othergems/kachick && bundle install --quiet && bundle exec ruby -v ./generate.rb
470
- ruby 3.0.1p64 (2021-04-05 revision 0fb782ee38) [x86_64-darwin20]
471
- Warming up --------------------------------------
472
- ULID.generate.to_s 3.014k i/100ms
473
- Calculating -------------------------------------
474
- ULID.generate.to_s 31.612k (±10.1%) i/s - 156.728k in 5.013432s
475
- "`ruby-ulid gem (this one) - 0.1.0` generated products: 212293 - sample: [\"01F59YF1WP49TT4GQPDN3E9JTJ\", \"01F59YF1MW1ZDQW93NX4J6RG4G\", \"01F59YF0KRX2CZKHDQQSN5HXHW\", \"01F59YEZVNH8YHP4ZHDK2ZRWSR\", \"01F59YF1J0FV3CVV099SHA2Q9A\"]"
476
- ```
408
+ See [Benchmark](https://github.com/kachick/ruby-ulid/wiki/Benchmark).
477
409
 
478
- I have an excuse, This gem does not aim `faster than other`.
479
- So I think the results are acceptable.
480
- </details>
410
+ The results are not something to be proud of.
481
411
 
482
412
  ## References
483
413
 
data/lib/ulid.rb CHANGED
@@ -259,10 +259,9 @@ class ULID
259
259
  from_integer(CrockfordBase32.decode(string))
260
260
  end
261
261
 
262
- # @param [String, #to_str] string
263
262
  # @return [Boolean]
264
- def self.valid?(string)
265
- string = String.try_convert(string)
263
+ def self.valid?(object)
264
+ string = String.try_convert(object)
266
265
  string ? STRICT_PATTERN_WITH_CROCKFORD_BASE32_SUBSET.match?(string) : false
267
266
  end
268
267
 
@@ -51,6 +51,7 @@ class ULID
51
51
  CROCKFORD_BASE32_CHAR_BY_N32_CHAR = N32_CHAR_BY_CROCKFORD_BASE32_CHAR.invert.freeze
52
52
  N32_CHAR_PATTERN = /[#{CROCKFORD_BASE32_CHAR_BY_N32_CHAR.keys.join}]/.freeze
53
53
 
54
+ # @api private
54
55
  # @param [String] string
55
56
  # @return [Integer]
56
57
  def self.decode(string)
@@ -58,6 +59,7 @@ class ULID
58
59
  n32encoded.to_i(32)
59
60
  end
60
61
 
62
+ # @api private
61
63
  # @param [Integer] integer
62
64
  # @return [String]
63
65
  def self.encode(integer)
data/lib/ulid/uuid.rb CHANGED
@@ -18,7 +18,7 @@ class ULID
18
18
  uuid = String.try_convert(uuid)
19
19
  raise ArgumentError, 'ULID.from_uuidv4 takes only strings' unless uuid
20
20
 
21
- prefix_trimmed = uuid.sub(/\Aurn:uuid:/, '')
21
+ prefix_trimmed = uuid.delete_prefix('urn:uuid:')
22
22
  unless UUIDV4_PATTERN.match?(prefix_trimmed)
23
23
  raise ParserError, "given `#{uuid}` does not match to `#{UUIDV4_PATTERN.inspect}`"
24
24
  end
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.1.1'
5
+ VERSION = '0.1.2'
6
6
  end
data/sig/ulid.rbs CHANGED
@@ -1,5 +1,4 @@
1
- # Classes
2
- class ULID
1
+ class ULID < Object
3
2
  VERSION: String
4
3
  CROCKFORD_BASE32_ENCODING_STRING: String
5
4
  TIMESTAMP_ENCODED_LENGTH: 10
@@ -45,21 +44,28 @@ class ULID
45
44
  CROCKFORD_BASE32_CHAR_BY_N32_CHAR: Hash[String, String]
46
45
  N32_CHAR_PATTERN: Regexp
47
46
 
47
+ # A pribate API. Should not be used in your code.
48
48
  def self.encode: (Integer integer) -> String
49
+
50
+ # A pribate API. Should not be used in your code.
49
51
  def self.decode: (String string) -> Integer
50
52
  end
51
53
 
52
54
  class MonotonicGenerator
53
55
  @mutex: Thread::Mutex
54
56
  attr_reader prev: ULID | nil
57
+
58
+ # A pribate API. Should not be used in your code.
55
59
  def initialize: -> void
60
+
61
+ # See [How to keep `Sortable` even if in same timestamp](https://github.com/kachick/ruby-ulid#how-to-keep-sortable-even-if-in-same-timestamp)
56
62
  def generate: (?moment: moment) -> ULID
57
63
  def inspect: -> String
58
64
  alias to_s inspect
59
65
  def freeze: -> void
60
66
  end
61
67
 
62
- interface _ULID
68
+ interface _ToULID
63
69
  def to_ulid: () -> ULID
64
70
  end
65
71
 
@@ -75,57 +81,409 @@ class ULID
75
81
  @inspect: String?
76
82
  @time: Time?
77
83
 
84
+ # Retuns a ULID
85
+ #
86
+ # They are sortable when generated in different timestamp with milliseconds precision
87
+ #
88
+ # ```ruby
89
+ # ulids = 1000.times.map do
90
+ # sleep(0.001)
91
+ # ULID.generate
92
+ # end
93
+ # ulids.uniq(&:to_time).size #=> 1000
94
+ # ulids.sort == ulids #=> true
95
+ # ```
96
+ #
97
+ # `ULID.generate` can take fixed `Time` instance.
98
+ # See also the short hand [ULID.at](https://kachick.github.io/ruby-ulid/ULID.html#at-class_method)
99
+ #
100
+ # ```ruby
101
+ # time = Time.at(946684800).utc #=> 2000-01-01 00:00:00 UTC
102
+ # ULID.generate(moment: time) #=> ULID(2000-01-01 00:00:00.000 UTC: 00VHNCZB00N018DCPJA4H9379P)
103
+ # ULID.generate(moment: time) #=> ULID(2000-01-01 00:00:00.000 UTC: 00VHNCZB006WQT3JTMN0T14EBP)
104
+ # ```
105
+ #
106
+ # The basic generator prefers `randomness`, it does not guarantee `sortable` for same milliseconds ULIDs.
107
+ #
108
+ # ```ruby
109
+ # ulids = 10000.times.map do
110
+ # ULID.generate
111
+ # end
112
+ # ulids.uniq(&:to_time).size #=> 35 (the size is not fixed, might be changed in environment)
113
+ # ulids.sort == ulids #=> false
114
+ # ```
115
+ #
116
+ # If you want to keep sortable even if in same timestamp, See also [ULID::MonotonicGenerator](https://github.com/kachick/ruby-ulid#how-to-keep-sortable-even-if-in-same-timestamp)
117
+ #
78
118
  def self.generate: (?moment: moment, ?entropy: Integer) -> self
119
+
120
+ # Shorthand of `ULID.generate(moment: Time)`
121
+ # See also [ULID.generate](https://kachick.github.io/ruby-ulid/ULID.html#generate-class_method)
122
+ #
123
+ # ```ruby
124
+ # time = Time.at(946684800).utc #=> 2000-01-01 00:00:00 UTC
125
+ # ULID.at(time) #=> ULID(2000-01-01 00:00:00.000 UTC: 00VHNCZB002W5BGWWKN76N22H6)
126
+ #
127
+ # ulids = 1000.times.map do |n|
128
+ # ULID.at(time + n)
129
+ # end
130
+ # ulids.sort == ulids #=> true
131
+ # ```
79
132
  def self.at: (Time time) -> self
133
+
134
+ # A pribate API. Should not be used in your code.
80
135
  def self.current_milliseconds: -> Integer
136
+
137
+ # A pribate API. Should not be used in your code.
81
138
  def self.milliseconds_from_moment: (moment moment) -> Integer
139
+
140
+ # `ULID` can be element of the `Range`. If you generated the IDs in monotonic generator, ID based filtering is easy and reliable
141
+ #
142
+ # ```ruby
143
+ # include_end = ulid1..ulid2
144
+ # exclude_end = ulid1...ulid2
145
+ #
146
+ # ulids.grep(one_of_the_above)
147
+ # ulids.grep_v(one_of_the_above)
148
+ # ```
149
+ #
150
+ # When want to filter ULIDs with `Time`, we should consider to handle the precision.
151
+ # So this gem provides `ULID.range` to generate reasonable `Range[ULID]` from `Range[Time]`
152
+ #
153
+ # ```ruby
154
+ # # Both of below, The begin of `Range[ULID]` will be the minimum in the floored milliseconds of the time1
155
+ # include_end = ULID.range(time1..time2) #=> The end of `Range[ULID]` will be the maximum in the floored milliseconds of the time2
156
+ # exclude_end = ULID.range(time1...time2) #=> The end of `Range[ULID]` will be the minimum in the floored milliseconds of the time2
157
+ #
158
+ # # Below patterns are acceptable
159
+ # pinpointing = ULID.range(time1..time1) #=> This will match only for all IDs in `time1`
160
+ # until_the_end = ULID.range(..time1) #=> This will match only for all IDs upto `time1` (The `nil` starting `Range` can be used since Ruby 2.7)
161
+ # until_the_end = ULID.range(ULID.min.to_time..time1) #=> This is same as above for Ruby 2.6
162
+ # until_the_ulid_limit = ULID.range(time1..) # This will match only for all IDs from `time1` to max value of the ULID limit
163
+ #
164
+ # # So you can use the generated range objects as below
165
+ # ulids.grep(one_of_the_above)
166
+ # ulids.grep_v(one_of_the_above)
167
+ # #=> I hope the results should be actually you want!
168
+ # ```
169
+ #
82
170
  def self.range: (period period) -> Range[ULID]
171
+
172
+ # Returns new `Time` with truncating excess precisions in ULID spec.
173
+ #
174
+ # ```ruby
175
+ # time = Time.at(946684800, Rational('123456.789')).utc
176
+ # #=> 2000-01-01 00:00:00.123456789 UTC
177
+ # ULID.floor(time) #=> 2000-01-01 00:00:00.123 UTC
178
+ # ```
83
179
  def self.floor: (Time time) -> Time
84
- def self.parse: (String string) -> self
180
+
181
+ # Get ULID instance from encoded String.
182
+ #
183
+ # ```ruby
184
+ # ulid = ULID.parse('01ARZ3NDEKTSV4RRFFQ69G5FAV')
185
+ # #=> ULID(2016-07-30 23:54:10.259 UTC: 01ARZ3NDEKTSV4RRFFQ69G5FAV)
186
+ # ```
187
+ def self.parse: (_ToStr string) -> self
188
+
189
+ # ```ruby
190
+ # # Currently experimental feature, so needed to load the extension.
191
+ # require 'ulid/uuid'
192
+ #
193
+ # # Basically reversible
194
+ # ulid = ULID.from_uuidv4('0983d0a2-ff15-4d83-8f37-7dd945b5aa39')
195
+ # #=> ULID(2301-07-10 00:28:28.821 UTC: 09GF8A5ZRN9P1RYDVXV52VBAHS)
196
+ # ulid.to_uuidv4 #=> "0983d0a2-ff15-4d83-8f37-7dd945b5aa39"
197
+ # ```
198
+ #
199
+ # See also [Why this is experimental?](https://github.com/kachick/ruby-ulid/issues/76)
85
200
  def self.from_uuidv4: (String uuid) -> ULID
86
201
  def self.from_integer: (Integer integer) -> self
202
+
203
+ # Returns termination values for ULID spec.
204
+ #
205
+ # ```ruby
206
+ # ULID.min
207
+ # #=> ULID(1970-01-01 00:00:00.000 UTC: 00000000000000000000000000)
208
+ # ```
209
+ #
210
+ # It can take `Time` instance as an optional argument.
211
+ # Then returns ULID that has minimum value of randomness part in the timestamp.
212
+ #
213
+ # ```ruby
214
+ # time = Time.at(946684800, Rational('123456.789')).utc
215
+ # #=> 2000-01-01 00:00:00.123456789 UTC
216
+ # ULID.min(time)
217
+ # #=> ULID(2000-01-01 00:00:00.123 UTC: 00VHNCZB3V0000000000000000)
218
+ # ```
219
+ #
220
+ # See also [ULID.max](https://kachick.github.io/ruby-ulid/ULID.html#max-class_method)
87
221
  def self.min: (?moment moment) -> ULID
222
+
223
+ # Returns termination values for ULID spec.
224
+ #
225
+ # ```ruby
226
+ # ULID.max
227
+ # #=> ULID(10889-08-02 05:31:50.655 UTC: 7ZZZZZZZZZZZZZZZZZZZZZZZZZ)
228
+ # ```
229
+ #
230
+ # It can take `Time` instance as an optional argument.
231
+ # Then returns ULID that has maximum value of randomness part in the timestamp.
232
+ #
233
+ # ```ruby
234
+ # time = Time.at(946684800, Rational('123456.789')).utc
235
+ # #=> 2000-01-01 00:00:00.123456789 UTC
236
+ # ULID.max(time)
237
+ # #=> ULID(2000-01-01 00:00:00.123 UTC: 00VHNCZB3VZZZZZZZZZZZZZZZZ)
238
+ # ```
239
+ #
240
+ # See also [ULID.min](https://kachick.github.io/ruby-ulid/ULID.html#min-class_method)
88
241
  def self.max: (?moment moment) -> ULID
242
+
243
+ # Returns random ULIDs.
244
+ #
245
+ # Basically ignores generating time.
246
+ #
247
+ # ```ruby
248
+ # ULID.sample #=> ULID(2545-07-26 06:51:20.085 UTC: 0GGKQ45GMNMZR6N8A8GFG0ZXST)
249
+ # ULID.sample #=> ULID(5098-07-26 21:31:06.946 UTC: 2SSBNGGYA272J7BMDCG4Z6EEM5)
250
+ # ULID.sample(0) #=> []
251
+ # ULID.sample(1) #=> [ULID(2241-04-16 03:31:18.440 UTC: 07S52YWZ98AZ8T565MD9VRYMQH)]
252
+ # ULID.sample(5)
253
+ # #=>
254
+ # #[ULID(5701-04-29 12:41:19.647 UTC: 3B2YH2DV0ZYDDATGTYSKMM1CMT),
255
+ # # ULID(2816-08-01 01:21:46.612 UTC: 0R9GT6RZKMK3RG02Q2HAFVKEY2),
256
+ # # ULID(10408-10-05 17:06:27.848 UTC: 7J6CPTEEC86Y24EQ4F1Y93YYN0),
257
+ # # ULID(2741-09-02 16:24:18.803 UTC: 0P4Q4V34KKAJW46QW47WQB5463),
258
+ # # ULID(2665-03-16 14:50:22.724 UTC: 0KYFW9DWM4CEGFNTAC6YFAVVJ6)]
259
+ # ```
260
+ #
261
+ # You can specify a range object for the timestamp restriction, See also [ULID.range](https://kachick.github.io/ruby-ulid/ULID.html#range-class_method).
262
+ #
263
+ # ```ruby
264
+ # ulid1 = ULID.parse('01F4A5Y1YAQCYAYCTC7GRMJ9AA') #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
265
+ # ulid2 = ULID.parse('01F4PTVCSN9ZPFKYTY2DDJVRK4') #=> ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK4)
266
+ # ulids = ULID.sample(1000, period: ulid1..ulid2)
267
+ # ulids.uniq.size #=> 1000
268
+ # ulids.take(10)
269
+ # #=>
270
+ # #[ULID(2021-05-02 06:57:19.954 UTC: 01F4NXW02JNB8H0J0TK48JD39X),
271
+ # # ULID(2021-05-02 07:06:07.458 UTC: 01F4NYC372GVP7NS0YAYQGT4VZ),
272
+ # # ULID(2021-05-01 06:16:35.791 UTC: 01F4K94P6F6P68K0H64WRDSFKW),
273
+ # # ULID(2021-04-27 22:17:37.844 UTC: 01F4APHGSMFJZQTGXKZBFFBPJP),
274
+ # # ULID(2021-04-28 20:17:55.357 UTC: 01F4D231MXQJXAR8G2JZHEJNH3),
275
+ # # ULID(2021-04-30 07:18:54.307 UTC: 01F4GTA2332AS2VPHC4FMKC7R5),
276
+ # # ULID(2021-05-02 12:26:03.480 UTC: 01F4PGNXARG554Y3HYVBDW4T9S),
277
+ # # ULID(2021-04-29 09:52:15.107 UTC: 01F4EGP483ZX2747FQPWQNPPMW),
278
+ # # ULID(2021-04-29 03:18:24.152 UTC: 01F4DT4Z4RA0QV8WFQGRAG63EH),
279
+ # # ULID(2021-05-02 13:27:16.394 UTC: 01F4PM605ABF5SDVMEHBH8JJ9R)]
280
+ # ULID.sample(10, period: ulid1.to_time..ulid2.to_time)
281
+ # #=>
282
+ # # [ULID(2021-04-29 06:44:41.513 UTC: 01F4E5YPD9XQ3MYXWK8ZJKY8SW),
283
+ # # ULID(2021-05-01 00:35:06.629 UTC: 01F4JNKD85SVK1EAEYSJGF53A2),
284
+ # # ULID(2021-05-02 12:45:28.408 UTC: 01F4PHSEYRG9BWBEWMRW1XE6WW),
285
+ # # ULID(2021-05-01 03:06:09.130 UTC: 01F4JY7ZBABCBMX16XH2Q4JW4W),
286
+ # # ULID(2021-04-29 21:38:58.109 UTC: 01F4FS45DX4049JEQK4W6TER6G),
287
+ # # ULID(2021-04-29 17:14:14.116 UTC: 01F4F9ZDQ449BE8BBZFEHYQWG2),
288
+ # # ULID(2021-04-30 16:18:08.205 UTC: 01F4HS5DPD1HWDVJNJ6YKJXKSK),
289
+ # # ULID(2021-04-30 10:31:33.602 UTC: 01F4H5ATF2A1CSQF0XV5NKZ288),
290
+ # # ULID(2021-04-28 16:49:06.484 UTC: 01F4CP4PDM214Q6H3KJP7DYJRR),
291
+ # # ULID(2021-04-28 15:05:06.808 UTC: 01F4CG68ZRST94T056KRZ5K9S4)]
292
+ # ```
89
293
  def self.sample: (?period: period) -> self
90
294
  | (Integer number, ?period: period) -> Array[self]
91
- def self.valid?: (untyped string) -> bool
92
- def self.scan: (String string) -> Enumerator[self, singleton(ULID)]
93
- | (String string) { (self ulid) -> void } -> singleton(ULID)
295
+ def self.valid?: (untyped) -> bool
296
+
297
+ # Returns parsed ULIDs from given String for rough operations.
298
+ #
299
+ # ```ruby
300
+ # json =<<'EOD'
301
+ # {
302
+ # "id": "01F4GNAV5ZR6FJQ5SFQC7WDSY3",
303
+ # "author": {
304
+ # "id": "01F4GNBXW1AM2KWW52PVT3ZY9X",
305
+ # "name": "kachick"
306
+ # },
307
+ # "title": "My awesome blog post",
308
+ # "comments": [
309
+ # {
310
+ # "id": "01F4GNCNC3CH0BCRZBPPDEKBKS",
311
+ # "commenter": {
312
+ # "id": "01F4GNBXW1AM2KWW52PVT3ZY9X",
313
+ # "name": "kachick"
314
+ # }
315
+ # },
316
+ # {
317
+ # "id": "01F4GNCXAMXQ1SGBH5XCR6ZH0M",
318
+ # "commenter": {
319
+ # "id": "01F4GND4RYYSKNAADHQ9BNXAWJ",
320
+ # "name": "pankona"
321
+ # }
322
+ # }
323
+ # ]
324
+ # }
325
+ # EOD
326
+ #
327
+ # ULID.scan(json).to_a
328
+ # #=>
329
+ # # [ULID(2021-04-30 05:51:57.119 UTC: 01F4GNAV5ZR6FJQ5SFQC7WDSY3),
330
+ # # ULID(2021-04-30 05:52:32.641 UTC: 01F4GNBXW1AM2KWW52PVT3ZY9X),
331
+ # # ULID(2021-04-30 05:52:56.707 UTC: 01F4GNCNC3CH0BCRZBPPDEKBKS),
332
+ # # ULID(2021-04-30 05:52:32.641 UTC: 01F4GNBXW1AM2KWW52PVT3ZY9X),
333
+ # # ULID(2021-04-30 05:53:04.852 UTC: 01F4GNCXAMXQ1SGBH5XCR6ZH0M),
334
+ # # ULID(2021-04-30 05:53:12.478 UTC: 01F4GND4RYYSKNAADHQ9BNXAWJ)]
335
+ # ```
336
+ def self.scan: (_ToStr string) -> Enumerator[self, singleton(ULID)]
337
+ | (_ToStr string) { (self ulid) -> void } -> singleton(ULID)
94
338
  def self.from_milliseconds_and_entropy: (milliseconds: Integer, entropy: Integer) -> self
95
- def self.try_convert: (_ULID) -> self
339
+ def self.try_convert: (_ToULID) -> ULID
96
340
  | (untyped) -> nil
341
+
342
+ # ```ruby
343
+ # ulid = ULID.generate
344
+ # #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
345
+ # ulid.milliseconds #=> 1619544442826
346
+ # ```
97
347
  attr_reader milliseconds: Integer
98
348
  attr_reader entropy: Integer
99
- def initialize: (milliseconds: Integer, entropy: Integer, integer: Integer) -> void
349
+
350
+ # ```ruby
351
+ # ulid = ULID.generate
352
+ # #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
353
+ # ulid.to_s #=> "01F4A5Y1YAQCYAYCTC7GRMJ9AA"
354
+ # ```
100
355
  def to_s: -> String
356
+
357
+ # ```ruby
358
+ # ulid = ULID.generate
359
+ # #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
360
+ # ulid.to_i #=> 1957909092946624190749577070267409738
361
+ # ```
101
362
  def to_i: -> Integer
102
363
  alias hash to_i
364
+
365
+ # Basically same as String based sort.
366
+ #
367
+ # ```ruby
368
+ # ulids = ULID.sample(10000); nil
369
+ # ulids.map(&:to_s).sort == ulids.sort.map(&:to_s)
370
+ # #=> true
371
+ # ```
372
+ #
373
+ # To be precise, this sorting unaffected with `case sensitive or not` and might handle [ulid/spec#57](https://github.com/ulid/spec/pull/57) in future. So preferable than `lexicographically sortable` in actual case.
374
+ #
103
375
  def <=>: (ULID other) -> Integer
104
376
  | (untyped other) -> nil
377
+
378
+ # ```ruby
379
+ # ulid = ULID.generate
380
+ # ulid.inspect #=> "ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)"
381
+ # ```
105
382
  def inspect: -> String
383
+
384
+ # ```ruby
385
+ # ULID.parse('4NNB20D9C1ME2NGMTX51ERZJX0') == ULID.parse('4nnb20d9c1me2ngmtx51erzjx0')
386
+ # #=> true
387
+ # ```
106
388
  def eql?: (untyped other) -> bool
107
389
  alias == eql?
108
390
  def ===: (untyped other) -> bool
391
+
392
+ # ```ruby
393
+ # ulid = ULID.generate
394
+ # #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
395
+ # ulid.to_time #=> 2021-04-27 17:27:22.826 UTC
396
+ # ```
109
397
  def to_time: -> Time
398
+
399
+ # ```ruby
400
+ # ulid = ULID.generate
401
+ # #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
402
+ # ulid.timestamp #=> "01F4A5Y1YA"
403
+ # ```
110
404
  def timestamp: -> String
405
+
406
+ # ```ruby
407
+ # ulid = ULID.generate
408
+ # #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
409
+ # ulid.randomness #=> "QCYAYCTC7GRMJ9AA"
410
+ # ```
111
411
  def randomness: -> String
412
+
413
+ # Intentionally avoiding to use `Record type` ref: https://github.com/ruby/rbs/blob/4fb4c33b2325d1a73d79ff7aaeb49f21cec1e0e5/docs/syntax.md#record-type
414
+ # Because the returning values are not fixed.
112
415
  def patterns: -> Hash[Symbol, Regexp | String]
113
416
  def octets: -> octets
114
417
  def timestamp_octets: -> timestamp_octets
115
418
  def randomness_octets: -> randomness_octets
419
+
420
+ # ```ruby
421
+ # # Currently experimental feature, so needed to load the extension.
422
+ # require 'ulid/uuid'
423
+ #
424
+ # # Basically reversible
425
+ # ulid = ULID.from_uuidv4('0983d0a2-ff15-4d83-8f37-7dd945b5aa39')
426
+ # #=> ULID(2301-07-10 00:28:28.821 UTC: 09GF8A5ZRN9P1RYDVXV52VBAHS)
427
+ # ulid.to_uuidv4 #=> "0983d0a2-ff15-4d83-8f37-7dd945b5aa39"
428
+ # ```
429
+ #
430
+ # See also [Why this is experimental?](https://github.com/kachick/ruby-ulid/issues/76)
116
431
  def to_uuidv4: -> String
117
- def next: -> ULID?
118
- alias succ next
432
+
433
+ # Returns next(successor) ULID.
434
+ # Especially `ULID#succ` makes it possible `Range[ULID]#each`.
435
+ #
436
+ # NOTE: But basically `Range[ULID]#each` should not be used, incrementing 128 bits IDs are not reasonable operation in most case
437
+ #
438
+ # ```ruby
439
+ # ULID.parse('01BX5ZZKBKZZZZZZZZZZZZZZZY').next.to_s #=> "01BX5ZZKBKZZZZZZZZZZZZZZZZ"
440
+ # ULID.parse('01BX5ZZKBKZZZZZZZZZZZZZZZZ').next.to_s #=> "01BX5ZZKBM0000000000000000"
441
+ # ULID.parse('7ZZZZZZZZZZZZZZZZZZZZZZZZZ').next #=> nil
442
+ # ```
443
+ #
444
+ # See also [ULID#pred](https://kachick.github.io/ruby-ulid/ULID.html#pred-instance_method)
445
+ def succ: -> ULID?
446
+ alias next succ
447
+
448
+ # Returns predecessor ULID.
449
+ #
450
+ # ```ruby
451
+ # ULID.parse('01BX5ZZKBK0000000000000001').pred.to_s #=> "01BX5ZZKBK0000000000000000"
452
+ # ULID.parse('01BX5ZZKBK0000000000000000').pred.to_s #=> "01BX5ZZKBJZZZZZZZZZZZZZZZZ"
453
+ # ULID.parse('00000000000000000000000000').pred #=> nil
454
+ # ```
455
+ #
456
+ # See also [ULID#succ](https://kachick.github.io/ruby-ulid/ULID.html#succ-instance_method)
119
457
  def pred: -> ULID?
120
458
  def freeze: -> self
459
+
460
+ # Returns `self`
121
461
  def to_ulid: -> self
462
+
463
+ # Returns `self`. Not a new instance.
122
464
  def dup: -> self
123
- # Same as https://github.com/ruby/rbs/blob/4fb4c33b2325d1a73d79ff7aaeb49f21cec1e0e5/core/object.rbs#L79
465
+
466
+ # Same API as [Object#clone](https://github.com/ruby/rbs/blob/4fb4c33b2325d1a73d79ff7aaeb49f21cec1e0e5/core/object.rbs#L79)
467
+ # But actually returns `self`. Not a new instance.
124
468
  def clone: (?freeze: bool) -> self
125
469
 
126
470
  private
471
+
472
+ # A pribate API. Should not be used in your code.
473
+ def self.new: (milliseconds: Integer, entropy: Integer, integer: Integer) -> self
474
+
475
+ # A pribate API. Should not be used in your code.
127
476
  def self.reasonable_entropy: -> Integer
477
+
478
+ # A pribate API. Should not be used in your code.
128
479
  def self.milliseconds_from_time: (Time time) -> Integer
480
+
481
+ # A pribate API. Should not be used in your code.
129
482
  def self.safe_get_class_name: (untyped object) -> String
483
+
484
+ # A pribate API. Should not be used in your code.
485
+ def initialize: (milliseconds: Integer, entropy: Integer, integer: Integer) -> void
486
+
487
+ # A pribate API. Should not be used in your code.
130
488
  def cache_all_instance_variables: -> void
131
489
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: ruby-ulid
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.1
4
+ version: 0.1.2
5
5
  platform: ruby
6
6
  authors:
7
7
  - Kenichi Kamiya