hashery 2.1.2 → 2.2.0

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.
@@ -1,11 +1,23 @@
1
- require 'enumerator'
2
-
3
1
  module Hashery
4
2
 
5
3
  # Hash with LRU expiry policy. There are at most max_size elements in a
6
4
  # LRUHash. When adding more elements old elements are removed according
7
5
  # to LRU policy.
8
6
  #
7
+ # Reading an entry with #[], #fetch, #assoc, #rassoc, #key or #values_at
8
+ # marks it as the most recently used. Membership checks (#has_key?,
9
+ # #has_value?) and iteration do not.
10
+ #
11
+ # Iteration (#each, #keys, #values, etc.) runs from the most recently used
12
+ # entry to the least recently used one.
13
+ #
14
+ # The optional #release_proc is called with the key and value of every
15
+ # entry that leaves the hash, whether evicted, deleted or cleared.
16
+ # It is not called when a value is overwritten.
17
+ #
18
+ # An LRUHash is not thread-safe. Guard it with a Mutex if it is shared
19
+ # between threads.
20
+ #
9
21
  # Based on Robert Klemme's LRUHash class.
10
22
  #
11
23
  # LRUHash, Copyright (c) 2010 Robert Klemme.
@@ -23,31 +35,46 @@ module Hashery
23
35
  #
24
36
  # Initialize new LRUHash instance.
25
37
  #
26
- # max_size -
27
- # default_value -
28
- # block -
38
+ # max_size - Maximum number of entries. Must be a positive integer
39
+ # (or something whose #to_i is).
40
+ # default_value - Value returned by #[] for missing keys.
41
+ # block - Default procedure called with the hash and key for
42
+ # missing keys, like Hash.new's block.
29
43
  #
30
44
  def initialize(max_size, default_value=nil, &block)
31
45
  @max_size = normalize_max(max_size)
32
46
  @default = default_value
33
47
  @default_proc = block
34
48
 
35
- @h = {}
36
- @head = Node.new
37
- @tail = front(Node.new)
49
+ # Maps each key to a [key, value] pair. Hash keeps insertion order,
50
+ # so the first entry is the least recently used and the last entry
51
+ # the most recently used. Moving an entry to the end is a delete
52
+ # followed by a re-insert of the same pair.
53
+ @table = {}
38
54
  end
39
55
 
40
56
  #
41
- # Iterate over each pair.
57
+ # Make a dup or clone independent of the original.
58
+ #
59
+ def initialize_copy(source)
60
+ super
61
+ @table = {}
62
+ source.instance_variable_get(:@table).each_value do |key, value|
63
+ @table[key] = [key, value]
64
+ end
65
+ end
66
+
67
+ #
68
+ # Iterate over each pair, most recently used first.
42
69
  #
43
70
  def each_pair
44
- if block_given?
45
- each_node do |n|
46
- yield [n.key, n.value]
47
- end
48
- else
49
- enum_for :each_pair
71
+ return enum_for(:each_pair) { size } unless block_given?
72
+
73
+ @table.values.reverse_each do |key, value|
74
+ yield [key, value]
50
75
  end
76
+
77
+ self
51
78
  end
52
79
 
53
80
  #
@@ -56,86 +83,105 @@ module Hashery
56
83
  alias each each_pair
57
84
 
58
85
  #
59
- # Iterate over each key.
86
+ # Iterate over each key, most recently used first.
60
87
  #
61
88
  def each_key
62
- if block_given?
63
- each_node do |n|
64
- yield n.key
65
- end
66
- else
67
- enum_for :each_key
89
+ return enum_for(:each_key) { size } unless block_given?
90
+
91
+ @table.values.reverse_each do |key, _value|
92
+ yield key
68
93
  end
94
+
95
+ self
69
96
  end
70
97
 
71
98
  #
72
- # Iterate over each value.
99
+ # Iterate over each value, most recently used first.
73
100
  #
74
101
  def each_value
75
- if block_given?
76
- each_node do |n|
77
- yield n.value
78
- end
79
- else
80
- enum_for :each_value
102
+ return enum_for(:each_value) { size } unless block_given?
103
+
104
+ @table.values.reverse_each do |_key, value|
105
+ yield value
81
106
  end
107
+
108
+ self
82
109
  end
83
110
 
84
111
  #
85
112
  # Size of the hash.
86
113
  #
87
114
  def size
88
- @h.size
115
+ @table.size
89
116
  end
90
117
 
118
+ alias length size
119
+
91
120
  #
92
- #
121
+ # Is the hash empty?
93
122
  #
94
123
  def empty?
95
- @head.succ.equal? @tail
124
+ @table.empty?
96
125
  end
97
126
 
98
127
  #
128
+ # Returns the value for the key, marking it most recently used. Like
129
+ # Hash#fetch, a missing key yields to the block if given, otherwise
130
+ # returns the default argument if given, otherwise raises KeyError.
99
131
  #
100
- #
101
- def fetch(key, &b)
102
- n = @h[key]
132
+ def fetch(key, default_value=UNDEFINED)
133
+ if (pair = @table.delete(key))
134
+ @table[pair[0]] = pair
135
+ return pair[1]
136
+ end
103
137
 
104
- if n
105
- front(n).value
138
+ if block_given?
139
+ unless UNDEFINED.equal?(default_value)
140
+ warn 'block supersedes default value argument', uplevel: 1
141
+ end
142
+ yield key
143
+ elsif !UNDEFINED.equal?(default_value)
144
+ default_value
106
145
  else
107
- (b || FETCH)[key]
146
+ raise KeyError.new("key not found: #{key.inspect}", receiver: self, key: key)
108
147
  end
109
148
  end
110
149
 
111
150
  #
112
- #
151
+ # Returns the value for the key, marking it most recently used, or
152
+ # the default if the key is missing.
113
153
  #
114
154
  def [](key)
115
- fetch(key) do |k|
116
- @default_proc ? @default_proc[self, k] : default
155
+ if (pair = @table.delete(key))
156
+ @table[pair[0]] = pair
157
+ pair[1]
158
+ elsif @default_proc
159
+ @default_proc[self, key]
160
+ else
161
+ default
117
162
  end
118
163
  end
119
164
 
120
165
  #
121
- #
166
+ # Keys, most recently used first.
122
167
  #
123
168
  def keys
124
- @h.keys
169
+ @table.keys.reverse!
125
170
  end
126
171
 
127
172
  #
128
- #
173
+ # Values, most recently used first.
129
174
  #
130
175
  def values
131
- @h.map {|k,n| n.value}
176
+ list = @table.map { |_key, pair| pair[1] }
177
+ list.reverse!
132
178
  end
133
179
 
134
180
  #
135
- #
181
+ # Does the hash contain the key? Does not affect LRU order.
136
182
  #
137
183
  def has_key?(key)
138
- @h.has_key? key
184
+ @table.key?(key)
139
185
  end
140
186
 
141
187
  alias key? has_key?
@@ -143,11 +189,12 @@ module Hashery
143
189
  alias include? has_key?
144
190
 
145
191
  #
146
- #
192
+ # Does the hash contain the value (compared with #eql?)?
193
+ # Does not affect LRU order.
147
194
  #
148
195
  def has_value?(value)
149
- each_pair do |k, v|
150
- return true if value.eql? v
196
+ @table.each_value do |pair|
197
+ return true if value.eql?(pair[1])
151
198
  end
152
199
 
153
200
  false
@@ -155,116 +202,129 @@ module Hashery
155
202
 
156
203
  alias value? has_value?
157
204
 
205
+ #
206
+ # Values for the given keys, as by #[].
207
+ #
158
208
  def values_at(*key_list)
159
209
  key_list.map {|k| self[k]}
160
210
  end
161
211
 
162
212
  #
163
- #
213
+ # Returns [key, value] for the key, marking it most recently used,
214
+ # or nil if missing.
164
215
  #
165
216
  def assoc(key)
166
- n = @h[key]
167
-
168
- if n
169
- front(n)
170
- [n.key, n.value]
217
+ if (pair = @table.delete(key))
218
+ @table[pair[0]] = pair
219
+ [pair[0], pair[1]]
171
220
  end
172
221
  end
173
222
 
174
223
  #
175
- #
224
+ # Returns [key, value] for the most recently used entry whose value is
225
+ # #eql? to the given value, marking it most recently used, or nil.
176
226
  #
177
227
  def rassoc(value)
178
- each_node do |n|
179
- if value.eql? n.value
180
- front(n)
181
- return [n.key, n.value]
228
+ @table.values.reverse_each do |pair|
229
+ if value.eql?(pair[1])
230
+ @table.delete(pair[0])
231
+ @table[pair[0]] = pair
232
+ return [pair[0], pair[1]]
182
233
  end
183
234
  end
235
+
184
236
  nil
185
237
  end
186
238
 
187
239
  #
188
- #
240
+ # Returns the key for the given value, as by #rassoc.
189
241
  #
190
242
  def key(value)
191
243
  pair = rassoc(value) and pair.first
192
244
  end
193
245
 
194
246
  #
195
- #
247
+ # Store a value, marking it most recently used. If the hash is full
248
+ # and the key is new, the least recently used entry is evicted first.
196
249
  #
197
250
  def store(key, value)
198
- # same optimization as in Hash
199
- key = key.dup.freeze if String === key && !key.frozen?
200
-
201
- n = @h[key]
202
-
203
- unless n
204
- if size == max_size
205
- # reuse node to optimize memory usage
206
- n = delete_oldest
207
- n.key = key
208
- n.value = value
209
- else
210
- n = Node.new key, value
211
- end
251
+ if (pair = @table.delete(key))
252
+ pair[1] = value
253
+ @table[pair[0]] = pair
254
+ else
255
+ # same optimization as in Hash
256
+ key = key.dup.freeze if String === key && !key.frozen?
257
+
258
+ evict_oldest if @table.size >= max_size
212
259
 
213
- @h[key] = n
260
+ @table[key] = [key, value]
214
261
  end
215
262
 
216
- front(n).value = value
263
+ value
217
264
  end
218
265
 
219
266
  alias []= store
220
267
 
221
268
  #
222
- #
269
+ # Delete the entry, calling the release_proc. Returns the value, or,
270
+ # if the key is missing, the result of the block if given, else nil.
223
271
  #
224
272
  def delete(key)
225
- n = @h[key] and remove_node(n).value
273
+ if (pair = @table.delete(key))
274
+ release(pair)
275
+ pair[1]
276
+ elsif block_given?
277
+ yield key
278
+ end
226
279
  end
227
280
 
228
281
  #
229
- #
282
+ # Delete every entry for which the block returns true, calling
283
+ # the release_proc for each.
230
284
  #
231
285
  def delete_if
232
- each_node do |n|
233
- remove_node n if yield n.key, n.value
286
+ return enum_for(:delete_if) { size } unless block_given?
287
+
288
+ @table.values.reverse_each do |key, value|
289
+ next unless yield(key, value)
290
+ pair = @table.delete(key)
291
+ release(pair) if pair
234
292
  end
293
+
294
+ self
235
295
  end
236
296
 
237
297
  #
238
- #
298
+ # Change the maximum size, evicting least recently used entries
299
+ # as needed.
239
300
  #
240
301
  def max_size=(limit)
241
302
  limit = normalize_max(limit)
242
303
 
243
304
  while size > limit
244
- delete_oldest
305
+ evict_oldest
245
306
  end
246
307
 
247
308
  @max_size = limit
248
309
  end
249
310
 
250
311
  #
251
- #
312
+ # Remove all entries, least recently used first, calling the
313
+ # release_proc for each.
252
314
  #
253
315
  def clear
254
316
  until empty?
255
- delete_oldest
317
+ evict_oldest
256
318
  end
257
319
 
258
320
  self
259
321
  end
260
322
 
261
323
  #
262
- #
324
+ # String representation, like Hash#inspect, most recently used first.
263
325
  #
264
326
  def to_s
265
- s = nil
266
- each_pair {|k, v| (s ? (s << ', ') : s = '{') << k.to_s << '=>' << v.to_s}
267
- s ? (s << '}') : '{}'
327
+ to_h.inspect
268
328
  end
269
329
 
270
330
  alias inspect to_s
@@ -272,49 +332,20 @@ module Hashery
272
332
  private
273
333
 
274
334
  #
275
- # Iterate nodes.
276
- #
277
- def each_node
278
- n = @head.succ
279
-
280
- until n.equal? @tail
281
- succ = n.succ
282
- yield n
283
- n = succ
284
- end
285
-
286
- self
287
- end
288
-
289
- #
290
- # Move node to front.
291
- #
292
- # node - [Node]
293
- #
294
- def front(node)
295
- node.insert_after(@head)
296
- end
297
-
298
- #
299
- # Remove the node and invoke release_proc
300
- # if set
301
- #
302
- # node - [Node]
335
+ # Remove the least recently used entry, returning its [key, value] pair.
303
336
  #
304
- def remove_node(node)
305
- n = @h.delete(node.key)
306
- n.unlink
307
- release_proc and release_proc[n.key, n.value]
308
- n
337
+ def evict_oldest
338
+ _key, pair = @table.shift
339
+ raise "Cannot delete from empty hash" unless pair
340
+ release(pair)
341
+ pair
309
342
  end
310
343
 
311
344
  #
312
- # Remove the oldest node returning the node
345
+ # Call the release_proc, if any, for a removed [key, value] pair.
313
346
  #
314
- def delete_oldest
315
- n = @tail.pred
316
- raise "Cannot delete from empty hash" if @head.equal? n
317
- remove_node n
347
+ def release(pair)
348
+ release_proc and release_proc[pair[0], pair[1]]
318
349
  end
319
350
 
320
351
  #
@@ -325,38 +356,14 @@ module Hashery
325
356
  # n - [#to_i] max size
326
357
  #
327
358
  def normalize_max(n)
328
- n = n.to_i
329
- raise ArgumentError, 'Invalid max_size: %p' % n unless Integer === n && n > 0
330
- n
359
+ i = n.to_i
360
+ raise ArgumentError, 'Invalid max_size: %p' % [n] unless Integer === i && i > 0
361
+ i
331
362
  end
332
363
 
333
- #
334
- FETCH = Proc.new {|k| raise KeyError, 'key not found'}
335
-
336
- # A single node in the doubly linked LRU list of nodes.
337
- Node = Struct.new :key, :value, :pred, :succ do
338
- def unlink
339
- pred.succ = succ if pred
340
- succ.pred = pred if succ
341
- self.succ = self.pred = nil
342
- self
343
- end
344
-
345
- def insert_after(node)
346
- raise 'Cannot insert after self' if equal? node
347
- return self if node.succ.equal? self
348
-
349
- unlink
350
-
351
- self.succ = node.succ
352
- self.pred = node
353
-
354
- node.succ.pred = self if node.succ
355
- node.succ = self
356
-
357
- self
358
- end
359
- end
364
+ # Marker for an omitted argument.
365
+ UNDEFINED = Object.new.freeze
366
+ private_constant :UNDEFINED
360
367
 
361
368
  end
362
369
 
@@ -82,7 +82,7 @@ module Hashery
82
82
  if @safe
83
83
  raise ArgumentError, "cannot set public method" unless methods.empty?
84
84
  else
85
- (class << self; self; end).class_eval{ protected *methods }
85
+ (class << self; self; end).class_eval{ protected(*methods) }
86
86
  end
87
87
  methods
88
88
  end
@@ -110,7 +110,7 @@ module Hashery
110
110
  # Returns +methods+.
111
111
  #
112
112
  def close!(*methods)
113
- (class << self; self; end).class_eval{ public *methods }
113
+ (class << self; self; end).class_eval{ public(*methods) }
114
114
  methods
115
115
  end
116
116
 
@@ -1,3 +1,5 @@
1
+ require 'hashery/crud_hash'
2
+
1
3
  module Hashery
2
4
 
3
5
  # StaticHash ia a Hash object which raises an error if any
@@ -0,0 +1,3 @@
1
+ module Hashery
2
+ VERSION = "2.2.0"
3
+ end
data/lib/hashery.rb CHANGED
@@ -1,6 +1,4 @@
1
- module Hashery
2
- VERSION = "2.1.0"
3
- end
1
+ require 'hashery/version'
4
2
 
5
3
  require 'hashery/core_ext'
6
4
 
@@ -14,8 +14,8 @@ testcase Association do
14
14
  class_method :[] do
15
15
  test do
16
16
  a = Association[:a, 1]
17
- a.assert.index == :a
18
- a.assert.value == 1
17
+ a.index.assert == :a
18
+ a.value.assert == 1
19
19
  end
20
20
  end
21
21
 
@@ -6,6 +6,30 @@ test_case IniHash do
6
6
  test do
7
7
  h = IniHash.new('foo.ini', false)
8
8
  end
9
+
10
+ test "from a hash" do
11
+ h = IniHash.new('a' => '1')
12
+ h['a'].assert == '1'
13
+ end
14
+ end
15
+
16
+ class_method :text do
17
+ test do
18
+ IniHash.text('a' => '1', 'b' => {'c' => '3'}).assert == "a=1\n[b]\nc=3\n"
19
+ end
20
+ end
21
+
22
+ class_method :write_to_file do
23
+ test "with a comment" do
24
+ require 'tmpdir'
25
+ Dir.mktmpdir do |dir|
26
+ path = File.join(dir, 'out.ini')
27
+ IniHash.write_to_file(path, {'a' => '1'}, "one\ntwo\n")
28
+ File.read(path).assert == "# one\n# two\na=1\n"
29
+ IniHash.read_comment_from_file(path).assert == "one\ntwo\n"
30
+ IniHash.read_from_file(path).assert == {'a' => '1'}
31
+ end
32
+ end
9
33
  end
10
34
 
11
35
  method :[]= do